feat!: split out definitions #128
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
|
There is one blocker, that I am not quite sure how we solve... For this to work, the separate schemas need to be bundled together again to provide the full file once again, i.e. automatically bundle all the schemas together to form https://github.com/asyncapi/spec-json-schemas/blob/master/schemas/2.2.0.json. For now, I have not found any library yet, that accurately provides this behavior... I could implement it myself, as it is quite an easy hack, but I kinda don't want to... Whenever we do find a solution, we need to create a workflow that automatically bundles the files when changes to the files have been made. |
|
As the implementation of a bundling behavior is quite simple, lets try to focus on https://github.com/hyperjump-io/json-schema-bundler It however does have one blocking "bug" - hyperjump-io/json-schema-bundle#2 |
hmm, I have not. Maybe this fits more our use-case 🤔 |
|
Ignore the request, need to refactor some stuff to make parser compatible. |
|
So... The "problem" is that tooling has a very different way of handling the bundling, and I am not quite sure what to choose. I am not able to get any of the tools to replicate the full AsyncAPI file we currently have. This means that we need to force a major version change. i.e. Our parser expects the schema object to be located under
"patternProperties": {
"^x-[\\w\\d.\\-_]+$": {
"$ref": "http://asyncapi.com/draft-07/schemas/specificationExtension"
}
},{
"additionalItems": true,
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/draft-07/schemas/specificationExtension"
}This will bundle it like: "definitions": {
"http://asyncapi.com/draft-07/schemas/specificationExtension": {
"$id": "http://asyncapi.com/draft-07/schemas/specificationExtension",
"description": "Any property starting with x- is valid.",
"additionalProperties": true,
"additionalItems": true
},
}
So what do you think we should do? 🤔 |
Technically no I guess 🤔 Let me try that approach, now that we have
@derberg I made a suggestion to expose them, see asyncapi/website#502. This also means, if the library you use supports fetching references, you don't need the bundled version, as they will be fetchable. Enables more use-cases, such as if you just want to validate a part of the AsyncAPI file 🙂
Yes, changing the id's of the schemas is the breaking change 🙂 |
@derberg not quite sure how we should handle the Go library as it expects the schemas to be present, and I dont see a way it can use the bundle library 😅 Reverting. |
You should update your documents with the changes I made to the regular expressions. As you can see here, your version is not compliant: https://regex101.com/r/tlOY2C/1 |
There was a problem hiding this comment.
Can you also configure release candidates setup for next-major?
as for your comment about Go package needs. Actually, we need to move it out, same with NPM package that stores schemas. Have a look at #130
Or we end up with more and more complex monorepo that will require us to break current workflows approach we have. It is doable, we just need to forget about GH releases, and do tags like these folks for example https://github.com/actions/toolkit/tags but does it make sense. Easier for us is to do a split
| "generate:assets": "npm run build", | ||
| "prepublishOnly": "npm run build", | ||
| "bundle": "cd tools/bundler && npm i && npm run bundle", | ||
| "startNewVersion": "newVersion=$npm_config_new_version && latestVersion=$(ls -d ./definitions/* | sort -V -r | head -1 | xargs -n 1 basename) && [ -d ./definitions/${newVersion} ] && echo Directory ./definitions/$newVersion already exist and cannot be overwritten. Please create a different version. || (cp -R ./definitions/$latestVersion ./definitions/$newVersion && find ./definitions/$newVersion -name '*.json' -exec sed -i '' \"s+definitions/$latestVersion+definitions/$newVersion+g\" {} +)", |
There was a problem hiding this comment.
Yeea, not sure if we should just leave it, or create something like a script folder? 🤔
There was a problem hiding this comment.
I definitely recommend moving it out into separate script, it is scary, and in separate script you can add comments 😅
There was a problem hiding this comment.
I'll make sure to split it out in another PR to simplify it 🙂
|
Kudos, SonarCloud Quality Gate passed!
|
Done 👍
Do you want me to remove the Go package now and remove the bundled schema files? Or should that be in another PR? We are generating the assets on releases, so all we need to do is removing Go package and bundled schema files. |
There was a problem hiding this comment.
@jonaslagoni this PR is complex enough, so do not remove Go package, especially that NPM package much also be moved out.
@dalelane @fmvilas anything from your side. I think we are ready to merge. It goes to release branch so any overlooked issues will not affect official packages anyway
|
Thanks for the review folks! /rtm |
|
🎉 This PR is included in version 3.0.0-next-major.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
NOTICE: THIS WILL TRIGGER A MAJOR VERSION CHANGE
Description
This PR helps ease the maintainability of the JSON Schema document for the specification since we now have small sub-schemas where the bundling process is now automated.
Changes introduced:
generate:assetsscript that is run on each release triggers the generation of the bundled files, ensuring they are always up to date.startNewVersionto create new version.$idandidproperties) to followhttp://asyncapi.com/definitions/<version>/<name>.jsoninstead of<name>while providing a migration guide. The reason for this is to follow an accurate bundling behavior from JSON Schema and made the most sense.Bugs it solves:
uflag. This means changing^x-[\\w\\d\\.\\-\\_]+$to^x-[\\w\\d.\\-_]+$.uflag. This means changing^x-[\\w\\d\\.\\-\\_]+$to^x-[\\w\\d.\\-_]+$patternproperty regex for parameter and correlationIdlocationneeds to be valid againstuflag. This means changing^\\$message\\.(header|payload)\\#(\\/(([^\\/~])|(~[01]))*)*to^\\$message\\.(header|payload)#(\\/(([^\\/~])|(~[01]))*)*$refis incorrectly defined for a server.Related issue(s)
Fixes #164
Fixes #127
Fixes #120
Paired PR's
Spec adapting release process: asyncapi/spec#659
Parser-js updating package and usage: asyncapi/parser-js#423
Website exposing all these files remotely: asyncapi/website#502