If youβre using Meshery or if you like the project, please β this repository to show your support! π€©
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.
--> 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.
Β
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 and the Repository Overview for a cursory description of repository by technology and programming language. Jump into community Slack or discussion forum to participate.
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.
Please do! We're a warm and welcoming community of open source contributors. All types of contributions are welcome. Please read:
- General Contributor Guide - Overview of contribution processes
- Schema Contributor Guide - Schema-specific development workflows and guidelines
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.
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
andx-go-import-path
to avoid generating redundant Go structs. Refer to existing patterns in the codebase.
All schemas are located in the schemas/
directory at the root of the Meshery repository:
schemas/
constructs/
<schema-version>/ # e.g., v1beta1
<construct>/ # e.g., model, component
<construct>.json # Schema definition for the construct (noun)
subschemas/ # Reusable modular pieces
openapi.yml # API operations (verbs: create, update, delete)
<construct>_template.json # Generated JSON template from schema
<construct>_template.yaml # Generated YAML template from schema
constructs/
β Holds schemas for various versions.<schema-version>/
β Represents a version (e.g.,v1alpha2
,v1beta1
).<construct>/
β A specific construct likepattern
,component
, etc.<construct>.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.
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.
Use the following command to perform the entire schema-driven generation workflow:
make build
-
Bundles OpenAPI schemas for:
- Meshery
- Remote Providers (e.g. Layer5 Cloud)
- Combined (all constructs)
-
Generates:
- Golang structs
- TypeScript types
- JSON & YAML templates
- RTK Query clients
β οΈ This is the recommended way to stay in sync with schema changes.
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. Layer5 Cloud) |
meshery_schema.yml |
Meshery-specific APIs |
To control which schema paths are included in each bundled output, use the x-internal
annotation inside the OpenAPI operations (get
, post
, etc.).
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.
Meshery uses a helper script (generate.sh
) to map schema constructs to generated output:
generate_schema_models <construct> <schema-version> [<openapi-file>]
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
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:
# 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
Before using the generated RTK clients, ensure you have:
-
Installed the required dependencies:
@reduxjs/toolkit
@layer5/schemas
-
Set up environment variables:
RTK_CLOUD_ENDPOINT_PREFIX
: Base URL for Cloud API endpointsRTK_MESHERY_ENDPOINT_PREFIX
: Base URL for Meshery API endpoints
To avoid cyclical imports that can break your application, import API slices from their specific exports:
// β
Correct: Import from specific API exports
import { cloudApi as cloudBaseApi } from "@layer5/schemas/dist/cloudApi";
import { mesheryApi } from "@layer5/schemas/dist/mesheryApi";
// β Incorrect: Do not import directly from generic API file
// import { api } from "@layer5/schemas/dist/api"; // Can cause cyclical imports
Add the API reducers and middleware to your Redux store configuration:
import { combineReducers, configureStore } from "@reduxjs/toolkit";
import { cloudApi as cloudBaseApi } from "@layer5/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);
After configuring your store, you can import and use the generated hooks:
import {
useGetPlansQuery,
useCreateDesignMutation,
useGetDesignsQuery,
// Other cloud API hooks...
} from "@layer5/schemas/dist/cloudApi";
function MyComponent() {
// Use hooks directly in your components
const { data: plans, isLoading, error } = useGetPlansQuery();
// Handle loading states
if (isLoading) return <div>Loading plans...</div>;
// Handle errors
if (error) return <div>Error loading plans</div>;
// Use data
return (
<div>
{plans.map(plan => (
<div key={plan.id}>{plan.name}</div>
))}
</div>
);
}
import {
useGetMeshModelsQuery,
useSubmitMeshConfigMutation,
// Other Meshery API hooks...
} from "@layer5/schemas/dist/mesheryApi";
function MesheryComponent() {
const { data: meshModels } = useGetMeshModelsQuery();
// ...
}
-
Stuck Loading States:
- Verify environment variables are correctly set
- Check for CORS issues
- Ensure proper authentication headers are included
-
Cyclical Imports:
- Always import from specific API files (
cloudApi.ts
,mesheryApi.ts
) - Avoid importing from generic
api.ts
files
- Always import from specific API files (
-
Multiple RTK Instances:
- Ensure proper reducer and middleware registration
- Check for naming conflicts in reducerPaths
For better debugging, use Redux DevTools to monitor:
- API request lifecycles
- State changes
- Caching behavior
-
Handle Loading States:
const { data, isLoading, isFetching, error } = useGetDataQuery();
-
Leverage Cache Options:
const { data } = useGetDataQuery(null, { pollingInterval: 30000, // Re-fetch every 30 seconds refetchOnMountOrArgChange: true, skip: !isReady // Skip query when not ready });
-
Use Transformations When Needed:
const transformedData = data?.map(item => ({ ...item, formattedValue: formatValue(item.value) }));
Validate your schema updates before committing by running:
make build
Or validate a single file:
npx @redocly/cli lint schemas/constructs/v1beta1/pattern/openapi.yml
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 |
This repository and site are available as open-source under the terms of the Apache 2.0 License.
MESHERY IS A CLOUD NATIVE COMPUTING FOUNDATION PROJECT