-
-
Notifications
You must be signed in to change notification settings - Fork 275
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Introduce Schema Versioning #697
Comments
Another hack - one that I've used - is to use That's not to disagree with the point you're making - that being able to describe versions (without depending on ad-hoc descriptions or naming conventions) would help. |
Thanks Dale. Using |
yes, that's true |
Come to think of it, if they were embedded in a message, they wouldn't have a name, they'd be anonymous, in terms of their path within the AsyncAPI file. |
As I remember @damaru-inc we talked about this once in a discussion on slack :) The idea with
In the JSON Schema specification there are metadata that are used more for making references (like Additionally, having this keyword we can always create several versions and specify the default version like: components:
schemas:
Person:
# have in mind that we haven't clarify how to override part of spec - related issue https://github.com/asyncapi/spec/issues/649
$ref: "#/components/schemas/Person/$versions/latest"
$versions:
"1.0.0":
title: Person
properties: ...
"1.1.0":
title: Person
properties: ...
"latest":
$ref: "#/components/schemas/Person/$versions/1.1.0" Currently if someone doesn't need to keep several versions of the same schema in one AsyncAPI file, can always split those versions into a separate file and already it is supported (also by tooling): # asyncapi.yaml
asyncapi: 2.2.0
info: ...
servers: ...
channels:
someChannel:
message:
payload:
$ref: ./some-schema.yaml#1.0.0
# some-schema.yaml
"1.0.0":
...
"2.0.0":
... |
Thanks, that's helpful. I think we need to figure out a standard way to do this so that parser-js can return the list of schema versions properly. As you noted, Studio will not render the schemas if we add the |
I wrote about our problem in the official |
I'm pasting the conversation with Ben Hutton (core maintainer of JSON Schema):
Mentioned blog post about bundling JSON Schema: https://json-schema.org/blog/posts/bundling-json-schema-compound-documents. At the moment we don't have a clue how referencing in AsyncAPi should work (issue #649), but if we will add the possibility to use # I use the proposal for 3.0.0 https://github.com/asyncapi/spec/issues/618
asyncapi: 3.0.0
info: ...
operations:
someOperation:
message:
payload:
$ref: https://example.com/schemas/Person/1.0.0
components:
schemas:
Person_1_0_0:
$id: https://example.com/schemas/Person/1.0.0
Person_2_0_0:
$id: https://example.com/schemas/Person/2.0.0 |
Just leaving a thought here for the future. IMHO, I think whatever solution we come up with, we should make sure it can easily integrate with external schema registries. Also, this feature together with #628, opens the door for a pure schema registry file. And that's exciting! 🙌 |
Random thought. We can probably encode the version number in the schema name as @damaru-inc is proposing in his first example but in a more standardized way. Example: components:
schemas:
Person: # No version; or version = undefined?
title: Person
properties: ...
[email protected]:
title: Person
properties: ...
[email protected]:
title: Person
properties: ... This seems to be more readable but it has a big constraint: if we ever want to evolve into some kind of schema changelog and want to add more info about what this new version provides compared to the previous one, we would not be able. Not saying we should evolve into a schema changelog but just saying this should be taken into account. |
Thanks for today meeting! That moment when we were talking about this issue and someone suggested (I don't remember who exactly, sorry) that it should be possible to define "info" for schemas came up with an idea to exactly have components:
schemas:
Person:
info:
id: 'some:company:Person' # unique id for schema. It will be very helpful for schema registries
version: '1.0.0'
description: '...'
comment: '' # developer comment with possible changes in opposite to previous one version etc
... # other fields like externalDocs, contact, license etc
meta: # field related to the https://github.com/asyncapi/spec/issues/622 issue to define meta information related to the schema format type
format: ... # schema format
... # other fields like `namespace` for avro, `rootObject` for XSD when we want to use external definition by $ref
definition:
... # definition for that schema in JSON Schema or other format
type: object
properties: ...
... etc
[email protected]:
info:
id: 'some:company:Person'
version: '1.1.0'
...
... I hope the idea itself is quite understandable. The only problem would still be in referencing a given schema. We would still have to operate on the absolute path to a given schema by operating on the path in Of course the same idea with the components:
messages:
SomeMessage:
info:
id: ...
description: ...
comment: ...
definition:
payload: ...
headers: ... WDYT? @fmvilas @jessemenning @damaru-inc @derberg @jonaslagoni EDIT: We should consider using JSONPath in AsyncAPI, not as current JSON Pointer https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html |
@magicmatatjahu How do you plan to have multiple versions of the same schema using this structure? It's not clear to me 🤔 If you're gonna rely on the
Notice you get two objects with version 1.1.0. I know you can make it fail at parser level but IMHO we should encourage a structure that doesn't allow this kind of conflicts in first place. Also the |
Personally I don't like that solution with
I don't think the key itself in There is also another option using the components:
schemas:
Person:
versions:
1.0.0:
info:
...
definition:
...
2.0.0:
info:
...
definition:
...
definition: # default definition
$ref: #/components/schemas/Person/versions/2.0.0
Before you ask, why do we need |
I'm not sure about
But yeah, tbh I don't understand how would that be consumed on a message level. I understand the need of versioning but don't understand how all suddenly thanks to versioning we solve:
How would that work on code generation level for example? I know version but still do not know which one to use |
Yeah, I agree, it's very problematic. I think the bigger problem is the inability to define the version for the schema itself and then use the corresponding reference in the message. The version itself (as well as the |
My 5 cents, I fear you might be mixing and matching solutions to problems that have not been raised 😅
Based on your issue @damaru-inc I am assuming (please correct me if I misinterpreted your issue) you are trying to solve the problem of having multiple versions of a specific schema. I.e. grouping all related schema versions for your
If this is the case, you don't really care about explicitly defining the version through something like @magicmatatjahu suggestion with Some of the solutions proposed here all fall back to what @damaru-inc (assumably) does not want to do, define multiple schemas in an unrelated way. Regardless of whether you use
This might need multiple issues to keep the discussion on track 🤔 Otherwise I fear it will be a problem reaching a consensus 😅 |
Right, I'm starting to get lost in this problem too. We should create other issues where we should try to solve other problems discussed here and leave this issue only for schema versioning. So the issues I see to be separated:
|
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
A somewhat outsider perspective - and playing the devil's advocate here - is what exactly is the pressing need to declare multiple schemas of the same object type within a single Async API document? AFAIK the sister spec of OpenAPI does not have nor need this capability, and I see nothing particularly different about an event-driven world that warrants this added complexity and capability. In the REST + microservices world, it is fairly common that a single service or client will need to speak multiple versions of a particular object type to various upstream services -- but this does not mean the API spec supports all of them at once. To the contrary, the downstream application resolves this by having multiple client versions each derived from a single, versioned OpenAPI specification. In an event-driven architecture world, it is possible to invoke two versions of the same action -- each with their respective data schemas and broker channels -- by simply consuming two API specs and generating the respective client-side code. Doing so keeps an API and likewise an Async API specification as "atomically versioned" - all channels and data types within represent a fully-compatible snapshot in time: a versioned release. Doing anything else opens up some very complex questions about cross-dependencies and coupling, and muddies the water on "what version of the API" a client is attempting to use. |
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
It is common in Event Driven Architectures to support several versions of a schema. One can imagine an application that sends two different message types to two different channels of a broker, each represented by a different version of a schema, because different downstream applications consume different versions of the message.
Currently AsyncAPI does not explicitly support different schema versions in the same file (unless each is directly in the payload section of a different message). If we want different schema versions to be under components schemas, we need to introduce a hack such as appending the version to the schema name like so:
This is not ideal, as any software consuming this would have to know the convention of how the schema name and version get combined. It would be better if the spec supported construct like this:
The text was updated successfully, but these errors were encountered: