feature: update schemas $id structure: model, component, connection and all which they reference #308
Conversation
…d all which they reference Signed-off-by: Nikita B <[email protected]>
…d all which they reference: run make generate-types Signed-off-by: Nikita B <[email protected]>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hello @n2h9, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
Summary of Changes
This pull request focuses on updating the $id structure within the Meshery schemas to align with RFC specifications for JSON schema. The primary goal is to ensure that the schemas can be effectively used with backend validation libraries and to prepare for potential online exposure of the schemas under https://schemas.meshery.io. The changes involve modifying the $id fields in several JSON schema files, including core.json, capability.json, relationship.json, category.json, component.json, connection.json, model.json, and subcategory.json. Additionally, corresponding updates are made in the TypeScript definition files to reflect the new $id structure.
Highlights
- Schema ID Updates: The
$idfields in multiple JSON schema files have been updated to use absolute URIs, following RFC specifications. This change affectsmodel,component,connection,relationship, and related sub-schemas. - TypeScript Definition Updates: TypeScript definition files, specifically
core.d.ts, have been modified to reflect the updated$idstructure in the JSON schemas. This includes renaming interfaces to match the new URI-based naming convention. - OpenAPI Schema Updates: OpenAPI schema files, such as
ComponentOpenApiSchema.tsandModelOpenApiSchema.ts, have been updated to use the new$idvalues for the JSON schemas. This ensures consistency across the codebase.
Changelog
Click here to see the changelog
- schemas/constructs/core.json
- Updated
$idfrom relative path to absolute URI:../core.jsontohttps://schemas.meshery.io/core.json.
- Updated
- schemas/constructs/v1alpha1/capability/capability.json
- Updated
$idto include version and entity path:https://schemas.meshery.io/capability.jsontohttps://schemas.meshery.io/v1alpha1/capability/capability.json.
- Updated
- schemas/constructs/v1alpha3/relationship.json
- Updated
$idto include version:https://schemas.meshery.io/relationship.jsontohttps://schemas.meshery.io/v1alpha3/relationship.json.
- Updated
- schemas/constructs/v1beta1/category/category.json
- Updated
$idto include version and entity path:https://schemas.meshery.io/category.jsontohttps://schemas.meshery.io/v1beta1/category/category.json.
- Updated
- schemas/constructs/v1beta1/component/component.json
- Updated
$idto include version and entity path:https://schemas.meshery.io/component.jsontohttps://schemas.meshery.io/v1beta1/component/component.json.
- Updated
- schemas/constructs/v1beta1/connection.json
- Updated
$idto include version:https://schemas.meshery.io/component.jsontohttps://schemas.meshery.io/v1beta1/connection.json.
- Updated
- schemas/constructs/v1beta1/model/model.json
- Updated
$idto include version and entity path:https://schemas.meshery.io/model.jsontohttps://schemas.meshery.io/v1beta1/model/model.json.
- Updated
- schemas/constructs/v1beta1/subcategory/subcategory.json
- Updated
$idto include version and entity path:https://schemas.meshery.io/category.jsontohttps://schemas.meshery.io/v1beta1/subcategory/subcategory.json.
- Updated
- typescript/constructs/core.d.ts
- Renamed interfaces referencing
CoreJsontoHttpsSchemasMesheryIoCoreJson.
- Renamed interfaces referencing
- typescript/constructs/v1alpha1/capability/CapabilityOpenApiSchema.ts
- Updated
$idin Capability schema tohttps://schemas.meshery.io/v1alpha1/capability/capability.json.
- Updated
- typescript/constructs/v1alpha1/capability/capability.d.ts
- Renamed interface
HttpsSchemasMesheryIoCapabilityJsontoHttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson.
- Renamed interface
- typescript/constructs/v1alpha2/relationship.d.ts
- Updated references to
HttpsSchemasMesheryIoModelJsontoHttpsSchemasMesheryIoV1Beta1ModelModelJson. - Updated references to
HttpsSchemasMesheryIoComponentJsontoHttpsSchemasMesheryIoV1Beta1ConnectionJson. - Updated references to
HttpsSchemasMesheryIoCategoryJsontoHttpsSchemasMesheryIoV1Beta1CategoryCategoryJson. - Updated references to
HttpsSchemasMesheryIoCapabilityJsontoHttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson.
- Updated references to
- typescript/constructs/v1alpha3/relationship.d.ts
- Renamed interface
HttpsSchemasMesheryIoRelationshipJsontoHttpsSchemasMesheryIoV1Alpha3RelationshipJson.
- Renamed interface
- typescript/constructs/v1alpha3/selector.d.ts
- Updated references to
HttpsSchemasMesheryIoModelJsontoHttpsSchemasMesheryIoV1Beta1ModelModelJson. - Updated references to
HttpsSchemasMesheryIoComponentJsontoHttpsSchemasMesheryIoV1Beta1ConnectionJson. - Updated references to
HttpsSchemasMesheryIoCategoryJsontoHttpsSchemasMesheryIoV1Beta1CategoryCategoryJson. - Updated references to
HttpsSchemasMesheryIoCapabilityJsontoHttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson.
- Updated references to
- typescript/constructs/v1beta1/category/CategoryOpenApiSchema.ts
- Updated
$idin CategoryDefinition schema tohttps://schemas.meshery.io/v1beta1/category/category.json.
- Updated
- typescript/constructs/v1beta1/category/category.d.ts
- Renamed interface
HttpsSchemasMesheryIoCategoryJsontoHttpsSchemasMesheryIoV1Beta1CategoryCategoryJson.
- Renamed interface
- typescript/constructs/v1beta1/component/ComponentOpenApiSchema.ts
- Updated
$idin ComponentDefinition schema tohttps://schemas.meshery.io/v1beta1/component/component.json. - Updated
$idin Model schema tohttps://schemas.meshery.io/v1beta1/model/model.json. - Updated
$idin Connection schema tohttps://schemas.meshery.io/v1beta1/connection.json. - Updated
$idin CategoryDefinition schema tohttps://schemas.meshery.io/v1beta1/category/category.json. - Updated
$idin SubCategory schema tohttps://schemas.meshery.io/v1beta1/subcategory/subcategory.json. - Updated
$idin Capability schema tohttps://schemas.meshery.io/v1alpha1/capability/capability.json.
- Updated
- typescript/constructs/v1beta1/component/component.d.ts
- Renamed interface
HttpsSchemasMesheryIoComponentJsontoHttpsSchemasMesheryIoV1Beta1ComponentComponentJson. - Updated references to
HttpsSchemasMesheryIoModelJsontoHttpsSchemasMesheryIoV1Beta1ModelModelJson. - Updated references to
HttpsSchemasMesheryIoCapabilityJson1toHttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson1. - Updated references to
HttpsSchemasMesheryIoComponentJson1toHttpsSchemasMesheryIoV1Beta1ConnectionJson. - Updated references to
HttpsSchemasMesheryIoCategoryJsontoHttpsSchemasMesheryIoV1Beta1CategoryCategoryJson. - Updated references to
HttpsSchemasMesheryIoCapabilityJsontoHttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson.
- Renamed interface
- typescript/constructs/v1beta1/connection.d.ts
- Renamed interface
HttpsSchemasMesheryIoComponentJsontoHttpsSchemasMesheryIoV1Beta1ConnectionJson.
- Renamed interface
- typescript/constructs/v1beta1/design/DesignOpenApiSchema.ts
- Updated
$idin Component schema tohttps://schemas.meshery.io/v1beta1/component/component.json. - Updated
$idin Model schema tohttps://schemas.meshery.io/v1beta1/model/model.json. - Updated
$idin Connection schema tohttps://schemas.meshery.io/v1beta1/connection.json. - Updated
$idin CategoryDefinition schema tohttps://schemas.meshery.io/v1beta1/category/category.json. - Updated
$idin SubCategory schema tohttps://schemas.meshery.io/v1beta1/subcategory/subcategory.json. - Updated
$idin Capability schema tohttps://schemas.meshery.io/v1alpha1/capability/capability.json. - Updated
$idin Relationship schema tohttps://schemas.meshery.io/v1alpha3/relationship.json.
- Updated
- typescript/constructs/v1beta1/design/design.d.ts
- Updated references to
HttpsSchemasMesheryIoComponentJsontoHttpsSchemasMesheryIoV1Beta1ComponentComponentJson. - Updated references to
HttpsSchemasMesheryIoRelationshipJsontoHttpsSchemasMesheryIoV1Alpha3RelationshipJson. - Updated references to
HttpsSchemasMesheryIoModelJsontoHttpsSchemasMesheryIoV1Beta1ModelModelJson. - Updated references to
HttpsSchemasMesheryIoComponentJson1toHttpsSchemasMesheryIoComponentJson. - Updated references to
HttpsSchemasMesheryIoCapabilityJson1toHttpsSchemasMesheryIoCapabilityJson. - Updated references to
HttpsSchemasMesheryIoModelJson2toHttpsSchemasMesheryIoModelJson1. - Updated references to
HttpsSchemasMesheryIoComponentJson3toHttpsSchemasMesheryIoComponentJson1. - Updated references to
HttpsSchemasMesheryIoCapabilityJson4toHttpsSchemasMesheryIoCapabilityJson2. - Updated references to
HttpsSchemasMesheryIoModelJson3toHttpsSchemasMesheryIoModelJson2. - Updated references to
HttpsSchemasMesheryIoComponentJson4toHttpsSchemasMesheryIoComponentJson2. - Updated references to
HttpsSchemasMesheryIoCapabilityJson5toHttpsSchemasMesheryIoCapabilityJson3. - Updated references to
HttpsSchemasMesheryIoModelJson4toHttpsSchemasMesheryIoModelJson3. - Updated references to
HttpsSchemasMesheryIoComponentJson5toHttpsSchemasMesheryIoComponentJson3. - Updated references to
HttpsSchemasMesheryIoCapabilityJson6toHttpsSchemasMesheryIoCapabilityJson4. - Updated references to
HttpsSchemasMesheryIoModelJson5toHttpsSchemasMesheryIoModelJson4. - Updated references to
HttpsSchemasMesheryIoComponentJson6toHttpsSchemasMesheryIoComponentJson4. - Updated references to
HttpsSchemasMesheryIoCapabilityJson7toHttpsSchemasMesheryIoCapabilityJson5.
- Updated references to
- typescript/constructs/v1beta1/evaluation/EvaluationOpenApiSchema.ts
- Updated
$idin Component schema tohttps://schemas.meshery.io/v1beta1/component/component.json. - Updated
$idin Model schema tohttps://schemas.meshery.io/v1beta1/model/model.json. - Updated
$idin Connection schema tohttps://schemas.meshery.io/v1beta1/connection.json. - Updated
$idin CategoryDefinition schema tohttps://schemas.meshery.io/v1beta1/category/category.json. - Updated
$idin SubCategory schema tohttps://schemas.meshery.io/v1beta1/subcategory/subcategory.json. - Updated
$idin Capability schema tohttps://schemas.meshery.io/v1alpha1/capability/capability.json. - Updated
$idin Relationship schema tohttps://schemas.meshery.io/v1alpha3/relationship.json.
- Updated
- typescript/constructs/v1beta1/model/ModelOpenApiSchema.ts
- Updated
$idin ModelDefinition schema tohttps://schemas.meshery.io/v1beta1/model/model.json. - Updated
$idin Connection schema tohttps://schemas.meshery.io/v1beta1/connection.json. - Updated
$idin CategoryDefinition schema tohttps://schemas.meshery.io/v1beta1/category/category.json. - Updated
$idin SubCategory schema tohttps://schemas.meshery.io/v1beta1/subcategory/subcategory.json. - Updated
$idin Capability schema tohttps://schemas.meshery.io/v1alpha1/capability/capability.json.
- Updated
- typescript/constructs/v1beta1/model/model.d.ts
- Renamed interface
HttpsSchemasMesheryIoModelJsontoHttpsSchemasMesheryIoV1Beta1ModelModelJson. - Updated references to
HttpsSchemasMesheryIoComponentJsontoHttpsSchemasMesheryIoV1Beta1ConnectionJson. - Updated references to
HttpsSchemasMesheryIoCategoryJsontoHttpsSchemasMesheryIoV1Beta1CategoryCategoryJson. - Updated references to
HttpsSchemasMesheryIoCapabilityJsontoHttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson.
- Renamed interface
- typescript/constructs/v1beta1/subcategory/SubcategoryOpenApiSchema.ts
- Updated
$idin SubCategoryDefinition schema tohttps://schemas.meshery.io/v1beta1/subcategory/subcategory.json.
- Updated
- typescript/constructs/v1beta2-draft/catalog_data.d.ts
- Updated references to
HttpsSchemasMesheryIoModelJsontoHttpsSchemasMesheryIoV1Beta1ModelModelJson. - Updated references to
HttpsSchemasMesheryIoComponentJsontoHttpsSchemasMesheryIoV1Beta1ConnectionJson. - Updated references to
HttpsSchemasMesheryIoCategoryJsontoHttpsSchemasMesheryIoV1Beta1CategoryCategoryJson. - Updated references to
HttpsSchemasMesheryIoCapabilityJsontoHttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson.
- Updated references to
- typescript/constructs/v1beta2-draft/draft-v1beta2.d.ts
- Updated references to
HttpsSchemasMesheryIoModelJsontoHttpsSchemasMesheryIoV1Beta1ModelModelJson. - Updated references to
HttpsSchemasMesheryIoComponentJson1toHttpsSchemasMesheryIoV1Beta1ConnectionJson. - Updated references to
HttpsSchemasMesheryIoCategoryJsontoHttpsSchemasMesheryIoV1Beta1CategoryCategoryJson. - Updated references to
HttpsSchemasMesheryIoCapabilityJsontoHttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson.
- Updated references to
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
A schema's ID,
Now clear for all to see,
Validation sings.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
This PR updates the $id fields in the JSON schemas to use absolute URIs, which is a good practice for interoperability and validation. The changes seem well-considered, and the provided explanation is clear. However, there are a few minor issues that should be addressed before merging.
Summary of Findings
- Typos in descriptions: There are a few typos in the descriptions of the schemas. While not critical, correcting them would improve the overall quality of the documentation.
- Inconsistent $id structure: The $id in
schemas/constructs/core.jsondoes not follow the same pattern as the other $id values. It should be updated tohttps://schemas.meshery.io/core.jsonto maintain consistency. - Interface naming in
typescript/constructs/core.d.ts: The interfaces intypescript/constructs/core.d.tsare being renamed to include the full URL. While technically correct, this results in very long and unwieldy names. Consider if there's a better way to represent this, perhaps by aliasing or using a different naming convention. - Inconsistent interface naming in
typescript/constructs/v1alpha1/capability/capability.d.ts: The interface intypescript/constructs/v1alpha1/capability/capability.d.tsis being renamed to include the full URL. While technically correct, this results in very long and unwieldy names. Consider if there's a better way to represent this, perhaps by aliasing or using a different naming convention.
Merge Readiness
The pull request is almost ready for merging. Addressing the typos and considering the interface naming in the TypeScript definitions would be beneficial. I am unable to directly approve this pull request, and strongly recommend that others review and approve this code before merging. Given the presence of medium severity comments, I recommend that the pull request not be merged until those are addressed (at a minimum).
| * This interface was referenced by `HttpsSchemasMesheryIoCoreJson`'s JSON-Schema | ||
| * via the `definition` "inputString". |
There was a problem hiding this comment.
Consider aliasing HttpsSchemasMesheryIoCoreJson to something shorter, as it's used repeatedly. The same applies to other interfaces in this file.
There was a problem hiding this comment.
@gemini-code-assist, will you suggest how to create an alias?
There was a problem hiding this comment.
There are a couple of ways to create an alias in TypeScript. One common approach is to use a type alias. Here's how you could apply that to HttpsSchemasMesheryIoCoreJson:
type CoreJson = HttpsSchemasMesheryIoCoreJson;You would place this line at the top of the core.d.ts file. Then, you can use CoreJson throughout the file as a shorthand for HttpsSchemasMesheryIoCoreJson. This improves readability, especially when the type is used repeatedly.
Another approach, if HttpsSchemasMesheryIoCoreJson is an interface, you could use interface extension:
interface CoreJson extends HttpsSchemasMesheryIoCoreJson {}However, this approach is less about creating a simple alias and more about creating a new interface that inherits from the original. For the purpose of shortening the name, a type alias is generally more appropriate.
| * This interface was referenced by `HttpsSchemasMesheryIoCoreJson`'s JSON-Schema | |
| * via the `definition` "inputString". | |
| type CoreJson = HttpsSchemasMesheryIoCoreJson; |
| @@ -8,7 +8,7 @@ | |||
| /** | |||
| * Meshery manages entities in accordance with their specific capabilities. This field explicitly identifies those capabilities largely by what actions a given component supports; e.g. metric-scrape, sub-interface, and so on. This field is extensible. Entities may define a broad array of capabilities, which are in-turn dynamically interpretted by Meshery for full lifecycle management. | |||
| */ | |||
| export interface HttpsSchemasMesheryIoCapabilityJson { | |||
| export interface HttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson { | |||
There was a problem hiding this comment.
Consider aliasing HttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson to something shorter, as it's used repeatedly. The same applies to other interfaces in this file.
There was a problem hiding this comment.
To Gemini's point, is this interface name auto-generated (something out of our direct control) or something that we might easily shorten, e.g. v1Alpha1Capability?
There was a problem hiding this comment.
Yes, the interface name is auto-generated from the JSON schema file name. Shortening it to V1Alpha1Capability would improve readability without losing clarity. This change would need to be reflected wherever the interface is used.
| export interface HttpsSchemasMesheryIoV1Alpha1CapabilityCapabilityJson { | |
| export interface V1Alpha1Capability { | |
There was a problem hiding this comment.
Oh, wow, it can even respond to the messages 😮
Right all typescript in this pr is auto generated.
To the point that it would be nice to have this autogeneration in ci, so that pr will not have this load.
I do not even know if this typescript is related to current changes in schema, or somebody just forgot to run
make generate-types on their prThere was a problem hiding this comment.
Oh, right, it is related.
The name is generated from $id
$id was "https://schemas.meshery.io/v1alpha1/capability.json"
and now $id is "https://schemas.meshery.io/v1alpha1/capability/capability.json"
wondering if it means some updates will be required on frontend 🤔 ?
@leecalcote @aabidsofi19
| @@ -13,7 +13,7 @@ const schema = { | |||
| "components": { | |||
| "schemas": { | |||
| "CategoryDefinition": { | |||
| "$id": "https://schemas.meshery.io/category.json", | |||
| "$id": "https://schemas.meshery.io/v1beta1/category/category.json", | |||
There was a problem hiding this comment.
Consider aliasing HttpsSchemasMesheryIoV1Beta1CategoryCategoryJson to something shorter, as it's used repeatedly. The same applies to other interfaces in this file.
| @@ -8,7 +8,7 @@ | |||
| /** | |||
| * Category of the model. | |||
| */ | |||
| export interface HttpsSchemasMesheryIoCategoryJson { | |||
| export interface HttpsSchemasMesheryIoV1Beta1CategoryCategoryJson { | |||
There was a problem hiding this comment.
Consider aliasing HttpsSchemasMesheryIoV1Beta1CategoryCategoryJson to something shorter, as it's used repeatedly. The same applies to other interfaces in this file.
There was a problem hiding this comment.
"$id": "https://schemas.meshery.io/v1alpha1/capability/capability.json",
Perfect. What we previously had (currently have) is without identification of schema version. Other than the core.json schema, to reference a schema without inclusion of it's version is to not reference a schema at all.
Notes for Reviewers
This PR introduces an update to the $id field values.
What do we want?
Why do we need this update?
Based on the draft-07 RFC schemas and subschemas does not operate with the entity like folder. There is a concept of an URI
According to the schema section 8.2:
hence when there is an $id field with a absolute URI the resolution of $ref within this schema is done based on the $id property.
What does it mean in our case. F.e. for v1beta1 model.json, it has $id = "https://schemas.meshery.io/model.json" and references to core.json as
../../core.jsonand so this is resolved to "https://schemas.meshery.io/core.json" according to rules defined in RFC. And both go libraries which I tried resolve it like this.For proper use with backend validation libraries within a filesystem, we could set up a custom loader to say that all URIs starting from this domains https://schemas.meshery.io take fron this directory, how I did it here: #306 f.e.
For this we need update in $id structure like in this pr.
I assume it will be also useful / necessary when we expose all schemas to be available online under https://schemas.meshery.io
For now I am only updating model, component, relationship and sub schemas that they refer.
Signed commits