Proposal: Moving Toward Complete API Schema Migration to meshery/schemas

[Pragalva Sapkota]

Hi Team, 

With the ongoing efforts toward the Meshery v1 release, we’ve already made significant progress in moving API definitions into meshery/schemas.

I wanted to propose that we continue in this direction by gradually migrating the remaining locally defined API paths from meshery/meshery into meshery/schemas, aligning with the approach used in Meshery Cloud.

The long term goal would be to make meshery/schemas the single source of truth for API contracts across both repositories, with future API changes originating from schemas and propagating outward.

Why this direction could be beneficial:

• Consistency: Reduces drift between Meshery and Meshery Cloud APIs
• Maintainability: Centralizes API changes instead of duplicating efforts
• Stability: Minimizes hidden mismatches and potential regressions

I’d love to hear thoughts from others on whether this is a direction worth formalizing and how we might approach it.

Best regards,

Pragalva 

[Lee Calcote]

Hi Pragalva,

Thanks for initiating this discussion. Directionally, I agree. For my part, I would certainly like to see us get there. From what I can see, there are a few of details to be ironed out:

1. Extensibility

2. Overlap / underlap

3. Auto-generation of documentation

I have thoughts to share on each these topics, but not the time to articulate them fully in this email. I didn't want to let this conversation stagnate before it has even begun, though, so I'm quickly listing out these three areas (and maybe there are others?), so as to advance the discussion and encourage other contributors to bring their thoughts.

Cheers,

Lee

--
You received this message because you are subscribed to the Google Groups "Meshery Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@meshery.io.
To view this discussion visit https://groups.google.com/a/meshery.io/d/msgid/developers/CANuiXpyNQZQFSGwsbfxvv2aNuobrHb5VNtNvy4AsMCSboHytMA%40mail.gmail.com.

[Aditya Upasani]

Hi Lee, Pragalva,

On the overlap/underlap point , having worked on relationship definitions across azure-container-service, KEDA, cert-manager and Flux, I've noticed that the boundary between what lives in the model files versus what should be schema-level contract isn't always clear. Right now relationship structure is implicitly enforced by convention rather than validated against a formal schema, which means drift can creep in silently across models.

If schemas becomes the source of truth, having explicit validation at PR time against those contracts would catch that kind of inconsistency early. That might also help scope what counts as overlap versus legitimate model-level variation.

Happy to contribute to however this gets formalized.

Aditya

To view this discussion visit https://groups.google.com/a/meshery.io/d/msgid/developers/3A0F519C-1C6C-4F5C-A241-C3C1248FD603%40layer5.io.

[Yash Mahakal]

Hi Pragalva, Lee,

This is a direction I've been actively researching, and I'm glad it's being discussed formally.

From hands-on auditing of Meshery's API endpoints against meshery/schemas, a clear picture has emerged of where we stand today:

A significant portion of endpoints already use ModelDefinition, ComponentDefinition, and RelationshipDefinition from meshery/schemas internally, but the HTTP handlers wrap them in locally-defined response envelopes that are never documented in the schema repository. The schemas are doing most of the heavy lifting, but the last mile - the API contract, isn't captured.

There is also a second gap: a large number of API paths simply don't exist in any api.yml file within meshery/schemas. The data models exist, but the endpoint documentation doesn't, meaning tools and clients can't reliably auto-generate or validate against them.

On Lee's points:

• Extensibility: The Provider interface in providers.go is a meaningful blocker. It's typed against local structs (*models.Preference, *models.User), which means even handlers that want to be schema-driven are forced to go through a local translation layer. Schema-driving the Provider interface itself would unlock a lot of endpoints at once.
• Overlap / Underlap: There are cases where both a local model and a schema model exist for the same concept (e.g., Preference), and they've diverged silently. Reconciling these before migration would prevent subtle regressions.
• Auto-generation of documentation: Most of Meshery's Swagger docs today are generated from inline swagger:route comments in handler files. If meshery/schemas becomes the source of truth, those comments become redundant, coordinating that transition carefully matters, However it'll fantastic to use schemas as final source of truth.

A phased approach starting with endpoints where the schema types are already embedded internally seems like a natural first step, the schemas are mostly there, it's just about removing the local envelopes and letting the schema types flow directly through.

Happy to contribute more concrete findings or help scope specific endpoints for a first migration batch.

Best,

Yash

To view this discussion visit https://groups.google.com/a/meshery.io/d/msgid/developers/3A0F519C-1C6C-4F5C-A241-C3C1248FD603%40layer5.io.