Skip to content

Commit 3c61f49

Browse files
GreenRoverderberg
andauthored
feat: allow defining schema format other than default (#910)
Co-authored-by: Lukasz Gornicki <[email protected]>
1 parent 1987e69 commit 3c61f49

File tree

1 file changed

+56
-31
lines changed

1 file changed

+56
-31
lines changed

spec/asyncapi.md

Lines changed: 56 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,7 @@ Aside from the issues mentioned above, there may also be infrastructure configur
105105
- [External Documentation Object](#externalDocumentationObject)
106106
- [Components Object](#componentsObject)
107107
- [Reference Object](#referenceObject)
108+
- [Multi Format Schema Object](#multiFormatSchemaObject)
108109
- [Schema Object](#schemaObject)
109110
- [Security Scheme Object](#securitySchemeObject)
110111
- [OAuth Flows Object](#oauth-flows-object)
@@ -1227,10 +1228,9 @@ Describes a message received on a given channel and operation.
12271228
Field Name | Type | Description
12281229
---|:---:|---
12291230
<a name="messageObjectMessageId"></a>messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions.
1230-
<a name="messageObjectHeaders"></a>headers | [Schema Object](#schemaObject) &#124; [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers.
1231-
<a name="messageObjectPayload"></a>payload | `any` | Definition of the message payload. It can be of any type but defaults to [Schema object](#schemaObject). It must match the schema format, including encoding type - e.g Avro should be inlined as either a YAML or JSON object NOT a string to be parsed as YAML or JSON.
1231+
<a name="messageObjectHeaders"></a>headers | [Multi Format Schema Object](#multiFormatSchemaObject) &#124; [Schema Object](#schemaObject) &#124; [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. If this is a [Schema Object](#schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#A2SVersionString).
1232+
<a name="messageObjectPayload"></a>payload | [Multi Format Schema Object](#multiFormatSchemaObject) &#124; [Schema Object](#schemaObject) &#124; [Reference Object](#referenceObject) | Definition of the message payload. If this is a [Schema Object](#schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#A2SVersionString).
12321233
<a name="messageObjectCorrelationId"></a>correlationId | [Correlation ID Object](#correlationIdObject) &#124; [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching.
1233-
<a name="messageObjectSchemaFormat"></a>schemaFormat | `string` | A string containing the name of the schema format used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). When the payload is defined using a `$ref` to a remote file, it is RECOMMENDED the schema format includes the file encoding type to allow implementations to parse the file correctly. E.g., adding `+yaml` if content type is `application/vnd.apache.avro` results in `application/vnd.apache.avro+yaml`.<br/><br/>Check out the [supported schema formats table](#messageObjectSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#messageObjectSchemaFormatTable).
12341234
<a name="messageObjectContentType"></a>contentType | `string` | The content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. `application/json`). When omitted, the value MUST be the one specified on the [defaultContentType](#defaultContentTypeString) field.
12351235
<a name="messageObjectName"></a>name | `string` | A machine-friendly name for the message.
12361236
<a name="messageObjectTitle"></a>title | `string` | A human-friendly title for the message.
@@ -1244,24 +1244,6 @@ Field Name | Type | Description
12441244

12451245
This object MAY be extended with [Specification Extensions](#specificationExtensions).
12461246

1247-
##### <a name="messageObjectSchemaFormatTable"></a>Schema formats table
1248-
1249-
The following table contains a set of values that every implementation MUST support.
1250-
1251-
Name | Allowed values | Notes
1252-
---|:---:|---
1253-
[AsyncAPI 3.0.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided.
1254-
[JSON Schema Draft 07](https://json-schema.org/specification-links.html#draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` |
1255-
1256-
The following table contains a set of values that every implementation is RECOMMENDED to support.
1257-
1258-
Name | Allowed values | Notes
1259-
---|:---:|---
1260-
[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` |
1261-
[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` |
1262-
[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` |
1263-
1264-
12651247
##### Message Object Example
12661248

12671249
```json
@@ -1388,9 +1370,11 @@ Example using Avro to define the payload:
13881370
{ "name": "signup" },
13891371
{ "name": "register" }
13901372
],
1391-
"schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
13921373
"payload": {
1393-
"$ref": "path/to/user-create.avsc#/UserCreate"
1374+
"schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
1375+
"schema": {
1376+
"$ref": "path/to/user-create.avsc#/UserCreate"
1377+
}
13941378
}
13951379
}
13961380
```
@@ -1405,9 +1389,10 @@ tags:
14051389
- name: user
14061390
- name: signup
14071391
- name: register
1408-
schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0'
14091392
payload:
1410-
$ref: 'path/to/user-create.avsc/#UserCreate'
1393+
schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0'
1394+
schema:
1395+
$ref: 'path/to/user-create.avsc/#UserCreate'
14111396
```
14121397

14131398

@@ -1427,9 +1412,8 @@ If you're looking to apply traits to an operation, see the [Operation Trait Obje
14271412
Field Name | Type | Description
14281413
---|:---:|---
14291414
<a name="messageTraitObjectMessageId"></a>messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions.
1430-
<a name="messageTraitObjectHeaders"></a>headers | [Schema Object](#schemaObject) &#124; [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers.
1415+
<a name="messageTraitObjectHeaders"></a>headers | [Multi Format Schema Object](#multiFormatSchemaObject) &#124; [Schema Object](#schemaObject) &#124; [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. If this is a [Schema Object](#schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#A2SVersionString).
14311416
<a name="messageTraitObjectCorrelationId"></a>correlationId | [Correlation ID Object](#correlationIdObject) &#124; [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching.
1432-
<a name="messageTraitObjectSchemaFormat"></a>schemaFormat | `string` | A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject).
14331417
<a name="messageTraitObjectContentType"></a>contentType | `string` | The content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. `application/json`). When omitted, the value MUST be the one specified on the [defaultContentType](#defaultContentTypeString) field.
14341418
<a name="messageTraitObjectName"></a>name | `string` | A machine-friendly name for the message.
14351419
<a name="messageTraitObjectTitle"></a>title | `string` | A human-friendly title for the message.
@@ -1446,13 +1430,11 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
14461430

14471431
```json
14481432
{
1449-
"schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
14501433
"contentType": "application/json"
14511434
}
14521435
```
14531436

14541437
```yaml
1455-
schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0'
14561438
contentType: application/json
14571439
```
14581440

@@ -1465,7 +1447,7 @@ Message Example Object represents an example of a [Message Object](#messageObjec
14651447
Field Name | Type | Description
14661448
---|:---:|---
14671449
<a name="messageExampleObjectHeaders"></a>headers | `Map[string, any]` | The value of this field MUST validate against the [Message Object's headers](#messageObjectHeaders) field.
1468-
<a name="messageExampleObjectPayload"></a>payload | `any` | The value of this field MUST validate against the [Message Object's payload](#messageObjectPayload) field.
1450+
<a name="messageExampleObjectPayload"></a>payload | `Map[string, any]` | The value of this field MUST validate against the [Message Object's payload](#messageObjectPayload) field.
14691451
<a name="messageExampleObjectName"></a>name | `string` | A machine-friendly name.
14701452
<a name="messageExampleObjectSummary"></a>summary | `string` | A short summary of what the example is about.
14711453

@@ -1606,7 +1588,7 @@ All objects defined within the components object will have no effect on the API
16061588

16071589
Field Name | Type | Description
16081590
---|:---|---
1609-
<a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject).
1591+
<a name="componentsSchemas"></a> schemas | Map[`string`, [Multi Format Schema Object](#multiFormatSchemaObject) \| [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Object](#schemaObject). If this is a [Schema Object](#schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#A2SVersionString).
16101592
<a name="componentsServers"></a> servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject).
16111593
<a name="componentsChannels"></a> channels | Map[`string`, [Channel Object](#channelObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Objects](#channelObject).
16121594
<a name="componentsOperations"></a> operations | Map[`string`, [Operation Item Object](#operationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Item Objects](#operationObject).
@@ -1669,6 +1651,12 @@ my.org.User
16691651
"type": "string"
16701652
}
16711653
}
1654+
},
1655+
"AvroExample": {
1656+
"schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
1657+
"schema": {
1658+
"$ref": "path/to/user-create.avsc#/UserCreate"
1659+
}
16721660
}
16731661
},
16741662
"servers": {
@@ -1791,6 +1779,10 @@ components:
17911779
format: int64
17921780
name:
17931781
type: string
1782+
AvroExample:
1783+
schemaFormat: application/vnd.apache.avro+json;version=1.9.0
1784+
schema:
1785+
$ref: 'path/to/user-create.avsc/#UserCreate'
17941786
servers:
17951787
development:
17961788
url: "{stage}.in.mycompany.com:{port}"
@@ -1856,6 +1848,39 @@ components:
18561848
maximum: 100
18571849
```
18581850
1851+
#### <a name="multiFormatSchemaObject"></a>Multi Format Schema Object
1852+
1853+
The Multi Format Schema Object represents a schema definition. It differs from the [Schema Object](#schemaObject) in that it supports multiple schema formats or languages (e.g., JSON Schema, Avro, etc.).
1854+
1855+
##### Fixed Fields
1856+
1857+
Field Name | Type | Description
1858+
---|:---:|---
1859+
<a name="multiFormatSchemaObjectSchemaFormat"></a>schemaFormat | `string` | **Required**. A string containing the name of the schema format that is used to define the information.
1860+
If `schemaFormat` is missing, it MUST default to `application/vnd.aai.asyncapi+json;version={{asyncapi}}` where `{{version}}` matches the [AsyncAPI Version String](#A2SVersionString). In such a case, this would make the Multi Format Schema Object equivalent to the [Schema Object](#schemaObject). When using [Reference Object](#referenceObject) within the schema, the `schemaFormat` of the resource being referenced MUST match the `schemaFormat` of the schema that contains the initial reference. For example, if you reference Avro `schema`, then `schemaFormat` of referencing resource and the resource being reference MUST match. <br/><br/>Check out the [supported schema formats table](#multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#multiFormatSchemaFormatTable).<br/><br/>When using [Reference Objects](#referenceObject) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference.
1861+
<a name="multiFormatSchemaObjectSchema"></a>schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#schemaObject). It MUST match the schema format defined in [`schemaFormat`](#multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string.
1862+
1863+
This object MAY be extended with [Specification Extensions](#specificationExtensions).
1864+
1865+
##### <a name="multiFormatSchemaFormatTable"></a>Schema formats table
1866+
1867+
The following table contains a set of values that every implementation MUST support.
1868+
1869+
Name | Allowed values | Notes
1870+
---|:---:|---
1871+
[AsyncAPI 3.0.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided.
1872+
[JSON Schema Draft 07](https://json-schema.org/specification-links.html#draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` |
1873+
1874+
The following table contains a set of values that every implementation is RECOMMENDED to support.
1875+
1876+
Name | Allowed values | Notes
1877+
---|:---:|---
1878+
[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` |
1879+
[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` |
1880+
[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` |
1881+
[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` |
1882+
1883+
18591884
#### <a name="schemaObject"></a>Schema Object
18601885

18611886
The Schema Object allows the definition of input and output data types.

0 commit comments

Comments
 (0)