https://github.com/meshery/schemas
Logical object models for Meshery
https://github.com/meshery/schemas
cloud-native cloud-native-applications cloud-native-architectures cloud-native-management cloud-native-manager cncf json-schemas kubernetes meshery ontology openapi
Last synced: about 1 month ago
JSON representation
Logical object models for Meshery
- Host: GitHub
- URL: https://github.com/meshery/schemas
- Owner: meshery
- License: apache-2.0
- Created: 2023-09-30T20:14:16.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2025-09-06T12:56:35.000Z (about 1 month ago)
- Last Synced: 2025-09-06T14:39:40.872Z (about 1 month ago)
- Topics: cloud-native, cloud-native-applications, cloud-native-architectures, cloud-native-management, cloud-native-manager, cncf, json-schemas, kubernetes, meshery, ontology, openapi
- Language: TypeScript
- Size: 127 MB
- Stars: 43
- Watchers: 7
- Forks: 65
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: .github/security-insights.yml
- Governance: GOVERNANCE.md
- Maintainers: MAINTAINERS.md
Awesome Lists containing this project
README
If you’re using Meshery or if you like the project, please ★ this repository to show your support! 🤩
# Meshery Schemas
Meshery follows schema-driven development. As a project, Meshery has different types of schemas. Some schemas are external facing, and some internal to Meshery itself. This repository serves as a central location for storing schemas from which all Meshery components can take reference.
Meshery schemas offer a powerful system designed for:
- **Model-Driven Management:** Meshery uses explicit models for describing infrastructure and applications.
- **Dynamic Discovery:** The ability to process different kinds of relationships and styles, enables a sophisticated system that can adapt to many configurations.
- **Lifecycle Management:** The schema properties track status and lifecycle of resources.
- **Extensibility:** Open-ended metadata and modular schema components enable expansion and customization.
- **Visual Representation:** The properties for styling of edges and nodes is for creating a user friendly visual representation.
- **Automated Operations:** The schemas can support validation and automated configuration of infrastructure and applications, and patching.
For an explanation of Meshery's terminology regarding schemas, definitions, declarations, and instances, please see [Contributor's Guide to Models](https://docs.meshery.io/project/contributing/contributing-models).
## Contributing
--> **For an explanation of the directory structure of this repository and how to contribute changes to Meshery's schemas, see [Contributor's Guide to Schema-Driven Development](https://docs.meshery.io/project/contributing/contributing-schemas).**
## Join the Meshery community!
Our projects are community-built and welcome collaboration. 👍 Be sure to see the Contributor Welcome Guide and Community Handbook for a tour of resources available to you. Jump into community Slack or discussion forum to participate.
Find your MeshMate
MeshMates are experienced community members, who will help you learn your way around, discover live projects, and expand your community network. Connect with a Meshmate today!
Find out more on the Meshery community.
✔️ Join any or all of the weekly meetings on community calendar.
✔️ Watch community meeting recordings.
✔️ Fill-in a community member form to gain access to community resources.
✔️ Discuss in the Community Forum.
✔️ Explore more in the Community Handbook.
Not sure where to start? Grab an open issue with the help-wanted label.
## Contributing
Please do! We're a warm and welcoming community of open source contributors. All types of contributions are welcome. Please read:
- [General Contributor Guide](https://docs.meshery.io/project/contributing) - Overview of contribution processes
- [Schema Contributor Guide](./CONTRIBUTING.md) - Schema-specific development workflows and guidelines
# 🧬 Schema-Driven Development Guide
Meshery follows a **Schema-Driven Development (SDD)** approach. This means that the **structure of data** used throughout the system is centrally defined using **schemas**. These schemas power consistency, validation, and code generation across the Meshery platform.
---
## 🧾 Schema Definition in Meshery
Meshery uses the **OpenAPI v3** specification to define and manage schemas. Given the complexity of the platform, Meshery adopts a **modular, versioned, and extensible** schema strategy:
* ✅ **Versioned schemas** for backward compatibility.
* 🧩 **Modular constructs** for maintainability and reuse.
* 🧪 **Schemas are used** for validation, API documentation, and automatic code generation.
> 💡 **TIP**: When referencing models or other constructs in the schema, **always add `x-go-type` and `x-go-import-path`** to avoid generating redundant Go structs. Refer to existing patterns in the codebase.
---
## 📁 Schema Directory Structure
All schemas are located in the `schemas/` directory at the root of the Meshery repository:
```
schemas/
constructs/
/ # e.g., v1beta1
/ # e.g., model, component
.json # Schema definition for the construct (noun)
subschemas/ # Reusable modular pieces
openapi.yml # API operations (verbs: create, update, delete)
_template.json # Generated JSON template from schema
_template.yaml # Generated YAML template from schema
```
### 🧠 Explanation
* **`constructs/`** – Holds schemas for various versions.
* **`/`** – Represents a version (e.g., `v1alpha2`, `v1beta1`).
* **`/`** – A specific construct like `pattern`, `component`, etc.
* **`.json`** – Defines the **data model (noun)** for the construct.
* **`subschemas/`** – Contains shared schema components for reuse.
* **`openapi.yml`** – Defines **API operations** (verbs).
* **Templates** – `*_template.json` and `*_template.yaml` are auto-generated examples with resolved references and defaults.
---
## ⚙️ Code Generation
Meshery supports **automated code generation** from schemas for:
* **Go**: Strongly-typed models for backend.
* **TypeScript**: Interfaces and types for frontend use.
* **RTK Query**: Clients generated from OpenAPI for use with Redux.
* **JSON/YAML**: Templates with defaults and resolved references.
---
## 🚀 Unified Build: One Command for Everything
Use the following command to perform the **entire schema-driven generation workflow**:
```bash
make build
```
### 🔧 What `make build` does:
1. **Bundles OpenAPI schemas** for:
* Meshery
* Remote Providers (e.g. Meshery Cloud)
* Combined (all constructs)
2. **Generates:**
* Golang structs
* TypeScript types
* JSON & YAML templates
* RTK Query clients
> ⚠️ This is the recommended way to stay in sync with schema changes.
---
## 🧱 Bundled Schema Outputs
After running `make build`, three bundled schema files are created:
| File | Purpose |
| -------------------- | ---------------------------------------------- |
| `merged_schema.yml` | All schemas combined (used by Meshery clients) |
| `cloud_schema.yml` | Cloud-specific APIs for Remote Providers (e.g. Meshery Cloud) |
| `meshery_schema.yml` | Meshery-specific APIs |
---
## ✍️ Annotating OpenAPI Paths
To control which schema paths are included in each bundled output, use the `x-internal` annotation inside the OpenAPI operations (`get`, `post`, etc.).
### Example:
```yaml
paths:
/api/entitlement/plans:
get:
x-internal: ["cloud"]
operationId: getPlans
tags:
- Plans
summary: Get all plans supported by the system
responses:
"200":
description: Plans fetched successfully
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Plan"
```
* **With `x-internal`**: Included only in the respective client (e.g., `cloud`).
* **Without `x-internal`**: Included in **all** clients.
---
## 🛠️ Advanced Usage (Optional)
### 📌 Custom Generation in `generate.sh`
Meshery uses a helper script (`generate.sh`) to map schema constructs to generated output:
```bash
generate_schema_models []
generate_schema_models "capability" "v1alpha1"
generate_schema_models "category" "v1beta1"
generate_schema_models "pattern" "v1beta1" "schemas/constructs/v1beta1/design/openapi.yml"
```
This maps to Go packages like:
```
models/v1alpha1/capability/capability.go
```
### 🧩 RTK Query Client Generation
The OpenAPI bundle is passed to a codegen tool to generate RTK Query clients. Include relevant paths using `x-internal` annotations and define request/response schemas appropriately.
You can control this in `generate.sh` like:
```bash
# Merge relevant constructs for RTK generation
npx @redocly/cli join schemas/base_cloud.yml \
"${v1beta1}/pattern/${merged_construct}" \
"${v1beta1}/component/${merged_construct}" \
"${v1beta1}/model/${merged_construct}" \
... \
-o schemas/merged_openapi.yml \
--prefix-tags-with-info-prop title \
--prefix-components-with-info-prop title
```
# Using Generated RTK Query Clients
## Prerequisites
Before using the generated RTK clients, ensure you have:
1. Installed the required dependencies:
- `@reduxjs/toolkit`
- `@meshery/schemas`
2. Set up environment variables:
- `RTK_CLOUD_ENDPOINT_PREFIX`: Base URL for Cloud API endpoints
- `RTK_MESHERY_ENDPOINT_PREFIX`: Base URL for Meshery API endpoints
## Store Configuration
### Import API Slices Correctly
To avoid cyclical imports that can break your application, import API slices from their specific exports:
```javascript
// ✅ Correct: Import from specific API exports
import { cloudApi as cloudBaseApi } from "@meshery/schemas/dist/cloudApi";
import { mesheryApi } from "@meshery/schemas/dist/mesheryApi";
// ❌ Incorrect: Do not import directly from generic API file
// import { api } from "@meshery/schemas/dist/api"; // Can cause cyclical imports
```
### Configure Redux Store
Add the API reducers and middleware to your Redux store configuration:
```javascript
import { combineReducers, configureStore } from "@reduxjs/toolkit";
import { cloudApi as cloudBaseApi } from "@meshery/schemas/dist/cloudApi";
import catalogReducer from "./slices/catalog";
import connectionReducer from "./slices/connection";
import organizationReducer from "./slices/organization";
import chartReducer from "./slices/charts";
import themeReducer from "./slices/theme";
// Optional: If you have locally defined APIs
import { cloudApi } from "../api";
// Combine reducers
const rootReducer = combineReducers({
catalog: catalogReducer,
charts: chartReducer,
organization: organizationReducer,
connection: connectionReducer,
theme: themeReducer,
// Add generated API reducers
[cloudBaseApi.reducerPath]: cloudBaseApi.reducer,
// Optional: Add locally defined API reducers
[cloudApi.reducerPath]: cloudApi.reducer
});
// Configure store with middleware
export const store = configureStore({
reducer: reduxPersist.createPersistEnhancedReducer(rootReducer),
middleware: getDefaultMiddleware =>
getDefaultMiddleware()
// Add generated API middleware
.concat(cloudBaseApi.middleware)
// Optional: Add locally defined API middleware
.concat(cloudApi.middleware)
// Add persistence middleware if needed
.concat(reduxPersist.persistMiddleware)
});
// Set up listeners for RTK Query cache behaviors like refetchOnFocus/refetchOnReconnect
setupListeners(store.dispatch);
```
## Using API Hooks
After configuring your store, you can import and use the generated hooks:
### Cloud API Hooks
```javascript
import {
useGetPlansQuery,
useCreateDesignMutation,
useGetDesignsQuery,
// Other cloud API hooks...
} from "@meshery/schemas/dist/cloudApi";
function MyComponent() {
// Use hooks directly in your components
const { data: plans, isLoading, error } = useGetPlansQuery();
// Handle loading states
if (isLoading) return
Loading plans...;
// Handle errors
if (error) return
Error loading plans;
// Use data
return (
{plans.map(plan => (
{plan.name}
))}
);
}
```
### Meshery API Hooks
```javascript
import {
useGetMeshModelsQuery,
useSubmitMeshConfigMutation,
// Other Meshery API hooks...
} from "@meshery/schemas/dist/mesheryApi";
function MesheryComponent() {
const { data: meshModels } = useGetMeshModelsQuery();
// ...
}
```
## Troubleshooting
### Common Issues
1. **Stuck Loading States**:
- Verify environment variables are correctly set
- Check for CORS issues
- Ensure proper authentication headers are included
2. **Cyclical Imports**:
- Always import from specific API files (`cloudApi.ts`, `mesheryApi.ts`)
- Avoid importing from generic `api.ts` files
3. **Multiple RTK Instances**:
- Ensure proper reducer and middleware registration
- Check for naming conflicts in reducerPaths
### Redux DevTools
For better debugging, use Redux DevTools to monitor:
- API request lifecycles
- State changes
- Caching behavior
## Best Practices
1. **Handle Loading States**:
```javascript
const { data, isLoading, isFetching, error } = useGetDataQuery();
```
2. **Leverage Cache Options**:
```javascript
const { data } = useGetDataQuery(null, {
pollingInterval: 30000, // Re-fetch every 30 seconds
refetchOnMountOrArgChange: true,
skip: !isReady // Skip query when not ready
});
```
3. **Use Transformations When Needed**:
```javascript
const transformedData = data?.map(item => ({
...item,
formattedValue: formatValue(item.value)
}));
```
## 🧪 Testing & Validating Schemas
Validate your schema updates before committing by running:
```bash
make build
```
Or validate a single file:
```bash
npx @redocly/cli lint schemas/constructs/v1beta1/pattern/openapi.yml
```
---
## ✅ Summary
| Task | Command |
| ----------------------- | ----------------------- |
| Generate everything | `make build` |
| Generate Go code only | `make golang-generate` |
| Generate TS + templates | `make generate-types` |
| Lint OpenAPI | `npx @redocly/cli lint` |
---
### License
This repository and site are available as open-source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).
MESHERY IS A CLOUD NATIVE COMPUTING FOUNDATION PROJECT