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.

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.

 

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 and the Repository Overview for a cursory description of repository by technology and programming language. 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.

 

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 - Overview of contribution processes
• Schema Contributor Guide - 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 in the application is defined using schemas, ensuring consistency, validation, and code generation across the project.

Schema Definition in Meshery

Meshery uses OpenAPI v3 specification to define schemas. Given the complexity of the project, where multiple constructs and APIs exist, we adopt a structured approach to schema management:

• Schemas are versioned to maintain backward compatibility.
• Schemas are modular to support different components of Meshery independently.
• Schemas are used for validation, API definition, and automatic code generation.
• NOTE: As you ref to model , etc or other existing constructs also add x-go-type and x-go-import-path so redudant structs are not generated , check existing implementation

Schema Directory Structure

All schemas are stored in the schemas directory at the root of the project. The structure follows:

schemas/
  constructs/
    <schema-version>/               # e.g., v1beta1
      <construct>/                  # e.g., model, component
        <construct>.json            # Schema definition for the construct (noun)
        subschemas/                 # Any subschemas used within the construct
        openapi.yml                 # OpenAPI schema defining API operations (verbs like create, update, delete)
        <construct>_template.json   # json template generated from schema
        <construct>_template.yaml   # yaml template generated from schema

Explanation

• constructs/ – Contains schemas for different versions.
• <schema-version>/ – Each schema version (e.g., v1beta1, v1alpha2) is a separate directory.
• <construct>/ – Each construct (e.g., capability, category) has its own folder.
• <construct>.json – Defines the schema for the noun (i.e., the entity).
• subschemas/ – Contains reusable subschemas for modularity.
• openapi.yml – Defines API operations (verbs: create, update, delete) and serves as the entry point for the schema.
• <construct>_template.json - json template generated from schema. Valid json document generated from schema definition. Has all references resolved, contains default values.
• <construct>_template.yaml - yaml template generated from schema. Valid yaml document generated from schema definition. Has all references resolved, contains default values.

This approach ensures that schemas are well-organized, reusable, and scalable across different Meshery components.

---

Code Generation

Meshery supports automatic code generation for:

• Golang (structs and types)
• TypeScript (interfaces and types)
• JSON template (json document with default values)
• YAML template (yaml document with default values)

Generating Code from Schemas

The schema-to-code mapping is defined in generate.sh, which automates the generation process.

Generating Golang Models

To generate Go structs from schemas, use:

make golang-generate

Generating TypeScript Models, JSON and YAML templates

To generate

• TypeScript types
• json templates
• yaml templates

from schemas, use:

make generate-types

Schema-to-Code Mapping

Example mapping in generate.sh:

generate_schema_models <construct> <schema-version>
generate_schema_models "capability" "v1alpha1"
generate_schema_models "category" "v1beta1"
generate_schema_models "component" "v1beta1"
generate_schema_models "pattern" "v1beta1" "schemas/constructs/v1beta1/design/openapi.yml"
generate_schema_models "core" "v1alpha1"
generate_schema_models "catalog" "v1alpha2"

• The package name matches the construct name.
• Example: For the capability construct in v1alpha1, the generated Go code will be in:

  models/v1alpha1/capability/capability.go
  

Example Output

./generate-golang.sh
🔹 Processing: capability (v1alpha1)...
✅ Generated: models/v1alpha1/capability/capability.go
🔹 Processing: category (v1beta1)...
✅ Generated: models/v1beta1/category/category.go
🔹 Processing: pattern (v1beta1)...
✅ Generated: models/v1beta1/pattern/pattern.go
🔹 Processing: core (v1alpha1)...
✅ Generated: models/v1alpha1/core/core.go
🔹 Processing: catalog (v1alpha2)...
✅ Generated: models/v1alpha2/catalog/catalog.go

This ensures that schemas remain the single source of truth, making development efficient, consistent, and scalable.

License

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