Skip to content

Commit

Permalink
feat!: add 3.0.0 validation support (#462)
Browse files Browse the repository at this point in the history
Co-authored-by: Sergio Moya <[email protected]>
Co-authored-by: Khuda Dad Nomani <[email protected]>
Co-authored-by: Ace <[email protected]>
Co-authored-by: Fran Méndez <[email protected]>
Co-authored-by: Jeremy Whitlock <[email protected]>
Co-authored-by: Laurent Broudoux <[email protected]>
Co-authored-by: Lukasz Gornicki <[email protected]>
Co-authored-by: Maciej Urbańczyk <[email protected]>
  • Loading branch information
9 people committed Dec 4, 2023
1 parent 8369438 commit fdfa224
Show file tree
Hide file tree
Showing 158 changed files with 29,131 additions and 220 deletions.
14 changes: 13 additions & 1 deletion CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,16 @@

# The default owners are automatically added as reviewers when you open a pull request unless different owners are specified in the file.

* @fmvilas @derberg @dalelane @smoya @char0n @asyncapi-bot-eve
* @fmvilas @derberg @dalelane @smoya @char0n @asyncapi-bot-eve

/bindings/anypointmq/ @mboss37 @GeraldLoeffler
/bindings/ibmmq/ @rcoppen
/bindings/jms/ @rcoppen @SrfHead
/bindings/kafka/ @lbroudoux @dalelane
/bindings/googlepubsub/ @whitlockjc
/bindings/solace/ @damaru-inc @CameronRushton
/bindings/pulsar/ @VisualBean
/bindings/sns/ @dpwdec @iancooper
/bindings/sqs/ @dpwdec @iancooper

/bindings/*.json @KhudaDad414
35 changes: 26 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,39 @@
![npm](https://img.shields.io/npm/v/@asyncapi/specs?style=for-the-badge) ![npm](https://img.shields.io/npm/dt/@asyncapi/specs?style=for-the-badge)

# AsyncAPI
## Overview

This is a mono repository, which provides all the JSON Schema documents for validating AsyncAPI documents.

## Overview
### Two types of schemas

This repository contains [JSON Schema](https://json-schema.org) files for all the versions of AsyncAPI specification. There are two types of JSON Schema files, with and without **$id** feature. We need two versions of schemas because of the differences it tooling implementation of JSON Schema `$ref` and `$id` keywords. Some implementations treat `$id` by default as prefix reference for `$ref` and require it, therefore it is needed to properly correlate `$ref` and `$id` values. Unfortunately other tools do not understand `$id` values and fail dereferencing. This is why we need two different versions of schemas, with and without the `$id`.

### Releases and pre-releases

This repository contains JSON Schema files for official AsyncAPI releases and also for release candidates. Before you decide to use a specific JSON Schema file in production, make sure a corresponding [official release of AsyncAPI specification](https://github.com/asyncapi/spec/releases) is produced, not a release candidate.

JSON Schema which describes a version of AsyncAPI specification that is not yet officially released is considered an unstable pre-release that can change anytime and is not considered to be a breaking-change.

If you want to make sure you only use stable schemas, you have to make sure that you use only certain schema versions, not all by default.

### JSON Schema vs AsyncAPI specification

These JSON Schema files do not reflect 1:1 the specification and shouldn't be treated as specification itself but rather as a tool (e.g., for validation).

These JSON Schema files shouldn't be used as the only tool for validating AsyncAPI documents because some rules described in the AsyncAPI specification can't be described with JSON Schema.

### Libraries

* This repository contains [JSON Schema](https://json-schema.org) files for all the versions of AsyncAPI specification. There are two types of JSON Schema files, with and without **$id** feature. We need two versions of schemas because of the differences it tooling implementation of JSON Schema `$ref` and `$id` keywords. Some implementations treat `$id` by default as prefix reference for `$ref` and require it, therefore it is needed to properly correlate `$ref` and `$id` values. Unfortunately other tools do not understand `$id` values and fail dereferencing. This is why we need two different versions of schemas, with and without the `$id`.
* These JSON Schema files do not reflect 1:1 the specification and shouldn't be treated as specification itself but rather as a tool (e.g., for validation).
* These JSON Schema files shouldn't be used as the only tool for validating AsyncAPI documents because some rules described in the AsyncAPI specification can't be described with JSON Schema.
* In addition, this repo provides JavaScript and Go modules that make it easier to access JSON Schema files through code. These packages provide access only to schemas with version larger or equal 2.0.0.
In addition, this repo provides JavaScript and Go modules that make it easier to access JSON Schema files through code. These packages provide access only to schemas with version larger or equal 2.0.0.

## Custom Validation Needs

If you decide to validate AsyncAPI documents only with the JSON Schema files provided in this repo, your AsyncAPI documents will not be properly validated.
It's recommended to use [AsyncAPI JavaScript Parser](https://github.com/asyncapi/parser-js) that uses the AsyncAPI JSON Schema files for validation but also implements additional custom validations.

The following additional custom validations need to be provided:
The following additional custom validations need to be provided for documents prior to `3.0.0`:

* Variables provided in the URL property have a corresponding variable object defined and its example is correct.
* Variables provided in the `url` property have a corresponding variable object defined and its example is correct.
* `operationId`s are not duplicated in the document.
* `messageId`s are not duplicated in the document.
* Server security is declared properly and the name has a corresponding `securitySchemes` definition in `components` with the same name.
Expand Down Expand Up @@ -108,6 +123,8 @@ func Do() {

If you are currently using version 2, check out [migration guideline to version 3](./migrations/migrate-to-version-3.md).
If you are currently using version 3, check out [migration guideline to version 4](./migrations/migrate-to-version-4.md).
If you are currently using version 4, check out [migration guideline to version 5](./migrations/migrate-to-version-5.md).
If you are currently using version 5, check out [migration guideline to version 6](./migrations/migrate-to-version-6.md).

## Repository structure

Expand Down Expand Up @@ -183,7 +200,7 @@ Whenever a Breaking Change is introduced, the following steps should be taken in

## SchemaStore compatibility testing

AsyncAPI JSON Schema is referenced in [SchemaStore](https://www.schemastore.org/json/). In many IDEs, like VSCode, some extensions integrate with SchemaStore, like [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). This way we enable autocompletion, validation and tooltips that helps writing AsyncAPI documents.
AsyncAPI JSON Schema is referenced in [SchemaStore](https://www.schemastore.org/json/). In many IDEs, like VSCode, some extensions integrate with SchemaStore, like [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). This way we enable autocompletion, validation and tooltips that help write AsyncAPI documents.

Whenever you make changes in AsyncAPI JSON Schema, you should always manually verify that the schema is still supported by [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) and that it will be able to fetch and dereference it.

Expand Down
136 changes: 136 additions & 0 deletions bindings/amqp/0.2.0/channel.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/bindings/amqp/0.2.0/channel.json",
"title": "AMQP channel bindings object",
"description": "This object contains information about the channel representation in AMQP.",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-[\\w\\d\\.\\x2d_]+$": {
"$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
}
},
"properties": {
"is": {
"type": "string",
"enum": ["queue", "routingKey"],
"description": "Defines what type of channel is it. Can be either 'queue' or 'routingKey' (default)."
},
"exchange": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"description": "The name of the exchange. It MUST NOT exceed 255 characters long."
},
"type": {
"type": "string",
"enum": ["topic", "direct", "fanout", "default", "headers"],
"description": "The type of the exchange. Can be either 'topic', 'direct', 'fanout', 'default' or 'headers'."
},
"durable": {
"type": "boolean",
"description": "Whether the exchange should survive broker restarts or not."
},
"autoDelete": {
"type": "boolean",
"description": "Whether the exchange should be deleted when the last queue is unbound from it."
},
"vhost": {
"type": "string",
"default": "/",
"description": "The virtual host of the exchange. Defaults to '/'."
}
},
"description": "When is=routingKey, this object defines the exchange properties."
},
"queue": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"description": "The name of the queue. It MUST NOT exceed 255 characters long."
},
"durable": {
"type": "boolean",
"description": "Whether the queue should survive broker restarts or not."
},
"exclusive": {
"type": "boolean",
"description": "Whether the queue should be used only by one connection or not."
},
"autoDelete": {
"type": "boolean",
"description": "Whether the queue should be deleted when the last consumer unsubscribes."
},
"vhost": {
"type": "string",
"default": "/",
"description": "The virtual host of the queue. Defaults to '/'."
}
},
"description": "When is=queue, this object defines the queue properties."
},
"bindingVersion": {
"type": "string",
"enum": [
"0.2.0"
],
"description": "The version of this binding. If omitted, 'latest' MUST be assumed."
}
},
"oneOf": [
{
"properties": {
"is": { "const": "routingKey" }
},
"required": [
"exchange"
],
"not": {
"required": [
"queue"
]
}
},
{
"properties": {
"is": { "const": "queue" }
},
"required": [
"queue"
],
"not": {
"required": [
"exchange"
]
}
}
],
"examples": [
{
"is": "routingKey",
"exchange": {
"name": "myExchange",
"type": "topic",
"durable": true,
"autoDelete": false,
"vhost": "/"
},
"bindingVersion": "0.2.0"
},
{
"is": "queue",
"queue": {
"name": "my-queue-name",
"durable": true,
"exclusive": true,
"autoDelete": false,
"vhost": "/"
},
"bindingVersion": "0.2.0"
}
]
}
37 changes: 37 additions & 0 deletions bindings/amqp/0.2.0/message.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/bindings/amqp/0.2.0/message.json",
"title": "AMQP message bindings object",
"description": "This object contains information about the message representation in AMQP.",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-[\\w\\d\\.\\x2d_]+$": {
"$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
}
},
"properties": {
"contentEncoding": {
"type": "string",
"description": "A MIME encoding for the message content."
},
"messageType": {
"type": "string",
"description": "Application-specific message type."
},
"bindingVersion": {
"type": "string",
"enum": [
"0.2.0"
],
"description": "The version of this binding. If omitted, \"latest\" MUST be assumed."
}
},
"examples": [
{
"contentEncoding": "gzip",
"messageType": "user.signup",
"bindingVersion": "0.2.0"
}
]
}
89 changes: 89 additions & 0 deletions bindings/amqp/0.2.0/operation.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/bindings/amqp/0.2.0/operation.json",
"title": "AMQP operation bindings object",
"description": "This object contains information about the operation representation in AMQP.",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-[\\w\\d\\.\\x2d_]+$": {
"$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
}
},
"properties": {
"expiration": {
"type": "integer",
"minimum": 0,
"description": "TTL (Time-To-Live) for the message. It MUST be greater than or equal to zero."
},
"userId": {
"type": "string",
"description": "Identifies the user who has sent the message."
},
"cc": {
"type": "array",
"items": {
"type": "string"
},
"description": "The routing keys the message should be routed to at the time of publishing."
},
"priority": {
"type": "integer",
"description": "A priority for the message."
},
"deliveryMode": {
"type": "integer",
"enum": [1,2],
"description": "Delivery mode of the message. Its value MUST be either 1 (transient) or 2 (persistent)."
},
"mandatory": {
"type": "boolean",
"description": "Whether the message is mandatory or not."
},
"bcc": {
"type": "array",
"items": {
"type": "string"
},
"description": "Like cc but consumers will not receive this information."
},
"replyTo": {
"type": "string",
"description": "Name of the queue where the consumer should send the response."
},
"timestamp": {
"type": "boolean",
"description": "Whether the message should include a timestamp or not."
},
"ack": {
"type": "boolean",
"description": "Whether the consumer should ack the message or not."
},
"bindingVersion": {
"type": "string",
"enum": [
"0.2.0"
],
"description": "The version of this binding. If omitted, \"latest\" MUST be assumed."
}
},
"examples": [
{
"expiration": 100000,
"userId": "guest",
"cc": [
"user.logs"
],
"priority": 10,
"deliveryMode": 2,
"mandatory": false,
"bcc": [
"external.audit"
],
"replyTo": "user.signedup",
"timestamp": true,
"ack": false,
"bindingVersion": "0.2.0"
}
]
}
Loading

0 comments on commit fdfa224

Please sign in to comment.