Skip to content

Commit a0975d9

Browse files
sambhavgupta0705derberg
sambhavgupta0705
and
derberg
authored
feat: add extensions support (#506)
Co-authored-by: Lukasz Gornicki <[email protected]>%0ACo-authored-by: derberg <[email protected]>
1 parent 9507aff commit a0975d9

File tree

9 files changed

+555
-263
lines changed

9 files changed

+555
-263
lines changed

‎.sonarcloud.properties

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
sonar.exclusions=tools/**/*

‎README.md

+11
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,8 @@ This is the current project structure explained:
134134
- [./examples](./examples) - contain most individual definition examples that will automatically be bundled together to provide example for each definition in the schemas in [./schemas](./schemas).
135135
- [./tools/bundler](./tools/bundler) - is the tool that bundles all the individual schemas together.
136136
- [./schemas](./schemas) - contain all automatically bundled and complete schemas for each AsyncAPI version. These schemas should **NOT** be manually changed as they are automatically generated. Any changes should be done in [./definitions](./definitions).
137+
- [./extensions](./extensions) - contains all the schemas of the extensions that will automatically be bundled to provide informations about extensions.
138+
137139

138140
## Schema Bundling
139141

@@ -210,7 +212,16 @@ Whenever you make changes in AsyncAPI JSON Schema, you should always manually ve
210212
```yaml
211213
# yaml-language-server: $schema=YOUR-PROJECTS-DIRECTORY/spec-json-schemas/schemas/2.6.0-without-$id.json
212214
```
215+
216+
## Extensions
213217

218+
Extensions are a way to [extend AsyncAPI specification](https://www.asyncapi.com/docs/concepts/asyncapi-document/extending-specification) with fields that are not yet defined inside the specification. To add JSON schema of the extension in this repository, you need to first make sure it is added to the [extension-catalog](https://github.com/asyncapi/extensions-catalog) repository.
219+
### How to add schema of the extension
214220

221+
1. All the extensions must be present in [./extensions](./extensions) folder.
222+
2. A proper folder structure must be followed to add the extensions.
223+
3. A new folder just as [x extension](./extensions/x) must be added with proper `versioning` and `schema file`.
224+
4. All the schemas must be added in a file named `schema.json` just as one is defined for [x extension](./extensions/x/0.1.0/schema.json).
215225

226+
5. Extension schema should not be referenced directly in the definition of the object it extends. For example if you add an extension for `info`, your extension's schema should not be referenced from `info.json` but [infoExtensions.json](./definitions/3.0.0/infoExtensions.json). If the object that you extend doesn't have a corresponding `*Extensions.json` file, you need to create one.
216227

‎definitions/3.0.0/info.json

+61-57
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,70 @@
11
{
2-
"type": "object",
32
"description": "The object provides metadata about the API. The metadata can be used by the clients if needed.",
4-
"required": [
5-
"version",
6-
"title"
7-
],
8-
"additionalProperties": false,
9-
"patternProperties": {
10-
"^x-[\\w\\d\\.\\x2d_]+$": {
11-
"$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
12-
}
13-
},
14-
"properties": {
15-
"title": {
16-
"type": "string",
17-
"description": "A unique and precise title of the API."
18-
},
19-
"version": {
20-
"type": "string",
21-
"description": "A semantic version number of the API."
22-
},
23-
"description": {
24-
"type": "string",
25-
"description": "A longer description of the API. Should be different from the title. CommonMark is allowed."
26-
},
27-
"termsOfService": {
28-
"type": "string",
29-
"description": "A URL to the Terms of Service for the API. MUST be in the format of a URL.",
30-
"format": "uri"
31-
},
32-
"contact": {
33-
"$ref": "http://asyncapi.com/definitions/3.0.0/contact.json"
34-
},
35-
"license": {
36-
"$ref": "http://asyncapi.com/definitions/3.0.0/license.json"
37-
},
38-
"tags": {
39-
"type": "array",
40-
"description": "A list of tags for application API documentation control. Tags can be used for logical grouping of applications.",
41-
"items": {
42-
"oneOf": [
43-
{
44-
"$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
45-
},
46-
{
47-
"$ref": "http://asyncapi.com/definitions/3.0.0/tag.json"
48-
}
49-
]
3+
"allOf": [
4+
{
5+
"type": "object",
6+
"required": ["version", "title"],
7+
"additionalProperties": false,
8+
"patternProperties": {
9+
"^x-[\\w\\d\\.\\x2d_]+$": {
10+
"$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
11+
}
5012
},
51-
"uniqueItems": true
52-
},
53-
"externalDocs": {
54-
"oneOf": [
55-
{
56-
"$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
13+
"properties": {
14+
"title": {
15+
"type": "string",
16+
"description": "A unique and precise title of the API."
5717
},
58-
{
59-
"$ref": "http://asyncapi.com/definitions/3.0.0/externalDocs.json"
18+
"version": {
19+
"type": "string",
20+
"description": "A semantic version number of the API."
21+
},
22+
"description": {
23+
"type": "string",
24+
"description": "A longer description of the API. Should be different from the title. CommonMark is allowed."
25+
},
26+
"termsOfService": {
27+
"type": "string",
28+
"description": "A URL to the Terms of Service for the API. MUST be in the format of a URL.",
29+
"format": "uri"
30+
},
31+
"contact": {
32+
"$ref": "http://asyncapi.com/definitions/3.0.0/contact.json"
33+
},
34+
"license": {
35+
"$ref": "http://asyncapi.com/definitions/3.0.0/license.json"
36+
},
37+
"tags": {
38+
"type": "array",
39+
"description": "A list of tags for application API documentation control. Tags can be used for logical grouping of applications.",
40+
"items": {
41+
"oneOf": [
42+
{
43+
"$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
44+
},
45+
{
46+
"$ref": "http://asyncapi.com/definitions/3.0.0/tag.json"
47+
}
48+
]
49+
},
50+
"uniqueItems": true
51+
},
52+
"externalDocs": {
53+
"oneOf": [
54+
{
55+
"$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
56+
},
57+
{
58+
"$ref": "http://asyncapi.com/definitions/3.0.0/externalDocs.json"
59+
}
60+
]
6061
}
61-
]
62+
}
63+
},
64+
{
65+
"$ref": "http://asyncapi.com/definitions/3.0.0/infoExtensions.json"
6266
}
63-
},
67+
],
6468
"example": {
6569
"$ref": "http://asyncapi.com/examples/3.0.0/info.json"
6670
},

‎definitions/3.0.0/infoExtensions.json

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"type": "object",
3+
"description": "The object that lists all the extensions of Info",
4+
"properties": {
5+
"x-x":{
6+
"$ref": "http://asyncapi.com/extensions/x/0.1.0/schema.json"
7+
}
8+
},
9+
"$schema": "http://json-schema.org/draft-07/schema#",
10+
"$id": "http://asyncapi.com/definitions/3.0.0/infoExtensions.json"
11+
}

‎extensions/x/0.1.0/schema.json

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"type": "string",
3+
"description": "This extension allows you to provide the Twitter username of the account representing the team/company of the API.",
4+
"example": [
5+
"sambhavgupta75",
6+
"AsyncAPISpec"
7+
],
8+
"$schema": "http://json-schema.org/draft-07/schema#",
9+
"$id": "http://asyncapi.com/extensions/x/0.1.0/schema.json"
10+
}

‎schemas/3.0.0-without-$id.json

+81-57
Original file line numberDiff line numberDiff line change
@@ -50,68 +50,75 @@
5050
"additionalItems": true
5151
},
5252
"info": {
53-
"type": "object",
5453
"description": "The object provides metadata about the API. The metadata can be used by the clients if needed.",
55-
"required": [
56-
"version",
57-
"title"
58-
],
59-
"additionalProperties": false,
60-
"patternProperties": {
61-
"^x-[\\w\\d\\.\\x2d_]+$": {
62-
"$ref": "#/definitions/specificationExtension"
63-
}
64-
},
65-
"properties": {
66-
"title": {
67-
"type": "string",
68-
"description": "A unique and precise title of the API."
69-
},
70-
"version": {
71-
"type": "string",
72-
"description": "A semantic version number of the API."
73-
},
74-
"description": {
75-
"type": "string",
76-
"description": "A longer description of the API. Should be different from the title. CommonMark is allowed."
77-
},
78-
"termsOfService": {
79-
"type": "string",
80-
"description": "A URL to the Terms of Service for the API. MUST be in the format of a URL.",
81-
"format": "uri"
82-
},
83-
"contact": {
84-
"$ref": "#/definitions/contact"
85-
},
86-
"license": {
87-
"$ref": "#/definitions/license"
88-
},
89-
"tags": {
90-
"type": "array",
91-
"description": "A list of tags for application API documentation control. Tags can be used for logical grouping of applications.",
92-
"items": {
93-
"oneOf": [
94-
{
95-
"$ref": "#/definitions/Reference"
96-
},
97-
{
98-
"$ref": "#/definitions/tag"
99-
}
100-
]
54+
"allOf": [
55+
{
56+
"type": "object",
57+
"required": [
58+
"version",
59+
"title"
60+
],
61+
"additionalProperties": false,
62+
"patternProperties": {
63+
"^x-[\\w\\d\\.\\x2d_]+$": {
64+
"$ref": "#/definitions/specificationExtension"
65+
}
10166
},
102-
"uniqueItems": true
103-
},
104-
"externalDocs": {
105-
"oneOf": [
106-
{
107-
"$ref": "#/definitions/Reference"
67+
"properties": {
68+
"title": {
69+
"type": "string",
70+
"description": "A unique and precise title of the API."
10871
},
109-
{
110-
"$ref": "#/definitions/externalDocs"
72+
"version": {
73+
"type": "string",
74+
"description": "A semantic version number of the API."
75+
},
76+
"description": {
77+
"type": "string",
78+
"description": "A longer description of the API. Should be different from the title. CommonMark is allowed."
79+
},
80+
"termsOfService": {
81+
"type": "string",
82+
"description": "A URL to the Terms of Service for the API. MUST be in the format of a URL.",
83+
"format": "uri"
84+
},
85+
"contact": {
86+
"$ref": "#/definitions/contact"
87+
},
88+
"license": {
89+
"$ref": "#/definitions/license"
90+
},
91+
"tags": {
92+
"type": "array",
93+
"description": "A list of tags for application API documentation control. Tags can be used for logical grouping of applications.",
94+
"items": {
95+
"oneOf": [
96+
{
97+
"$ref": "#/definitions/Reference"
98+
},
99+
{
100+
"$ref": "#/definitions/tag"
101+
}
102+
]
103+
},
104+
"uniqueItems": true
105+
},
106+
"externalDocs": {
107+
"oneOf": [
108+
{
109+
"$ref": "#/definitions/Reference"
110+
},
111+
{
112+
"$ref": "#/definitions/externalDocs"
113+
}
114+
]
111115
}
112-
]
116+
}
117+
},
118+
{
119+
"$ref": "#/definitions/infoExtensions"
113120
}
114-
},
121+
],
115122
"examples": [
116123
{
117124
"title": "AsyncAPI Sample App",
@@ -292,6 +299,23 @@
292299
}
293300
]
294301
},
302+
"infoExtensions": {
303+
"type": "object",
304+
"description": "The object that lists all the extensions of Info",
305+
"properties": {
306+
"x-x": {
307+
"$ref": "#/definitions/extensions-x-0.1.0-schema"
308+
}
309+
}
310+
},
311+
"extensions-x-0.1.0-schema": {
312+
"type": "string",
313+
"description": "This extension allows you to provide the Twitter username of the account representing the team/company of the API.",
314+
"example": [
315+
"sambhavgupta75",
316+
"AsyncAPISpec"
317+
]
318+
},
295319
"servers": {
296320
"description": "An object representing multiple servers.",
297321
"type": "object",

0 commit comments

Comments
 (0)