Skip to content

Commit

Permalink
Merge branch 'extensions' of github.com:sambhavgupta0705/asyncapi-jso…
Browse files Browse the repository at this point in the history
…n-schemas into extensions

Signed-off-by: Sambhav Gupta <[email protected]>
  • Loading branch information
sambhavgupta0705 committed Dec 21, 2023
2 parents 5590964 + cfbf44a commit 4a6cb55
Show file tree
Hide file tree
Showing 101 changed files with 6,959 additions and 626 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/automerge.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ jobs:
env:
GITHUB_TOKEN: "${{ secrets.GH_TOKEN }}"
GITHUB_LOGIN: asyncapi-bot
MERGE_LABELS: ""
MERGE_LABELS: "!do-not-merge"
MERGE_METHOD: "squash"
MERGE_COMMIT_MESSAGE: "{pullRequest.title} (#{pullRequest.number})"
MERGE_RETRIES: "20"
Expand Down
1 change: 1 addition & 0 deletions .npmignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@ test
go.mod
go.sum
*.go
tools/bundler
17 changes: 10 additions & 7 deletions CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,14 @@

* @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/anypointmq/ @GeraldLoeffler
/bindings/ibmmq/ @rcoppen
/bindings/kafka/ @lbroudoux @dalelane
/bindings/googlepubsub/ @whitlockjc
/bindings/solace/ @damaru-inc @CameronRushton
/bindings/*.json @KhudaDad414
/bindings/pulsar/ @VisualBean
/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
9 changes: 8 additions & 1 deletion bindings/anypointmq/0.0.1/message.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,14 @@
},
"properties": {
"headers": {
"$ref": "http://asyncapi.com/definitions/3.0.0/schema.json",
"oneOf": [
{
"$ref": "http://asyncapi.com/definitions/3.0.0/schema.json"
},
{
"$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
}
],
"description": "A Schema object containing the definitions for Anypoint MQ-specific headers (protocol headers). This schema MUST be of type 'object' and have a 'properties' key. Examples of Anypoint MQ protocol headers are 'messageId' and 'messageGroupId'."
},
"bindingVersion": {
Expand Down
9 changes: 8 additions & 1 deletion bindings/http/0.1.0/message.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,14 @@
},
"properties": {
"headers": {
"$ref": "http://asyncapi.com/definitions/3.0.0/schema.json",
"oneOf": [
{
"$ref": "http://asyncapi.com/definitions/3.0.0/schema.json"
},
{
"$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
}
],
"description": "\tA Schema object containing the definitions for HTTP-specific headers. This schema MUST be of type 'object' and have a 'properties' key."
},
"bindingVersion": {
Expand Down
9 changes: 8 additions & 1 deletion bindings/http/0.1.0/operation.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,14 @@
"description": "When 'type' is 'request', this is the HTTP method, otherwise it MUST be ignored. Its value MUST be one of 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'CONNECT', and 'TRACE'."
},
"query": {
"$ref": "http://asyncapi.com/definitions/3.0.0/schema.json",
"oneOf": [
{
"$ref": "http://asyncapi.com/definitions/3.0.0/schema.json"
},
{
"$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
}
],
"description": "A Schema object containing the definitions for each query parameter. This schema MUST be of type 'object' and have a properties key."
},
"bindingVersion": {
Expand Down
Empty file removed bindings/jms/.keep
Empty file.
40 changes: 40 additions & 0 deletions bindings/jms/0.0.1/channel.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/bindings/jms/0.0.1/channel.json",
"title": "Channel Schema",
"description": "This object contains configuration for describing a JMS queue, or FIFO queue as an AsyncAPI channel. This objects only contains configuration that can not be provided in the AsyncAPI standard channel object.",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-[\\w\\d\\.\\x2d_]+$": {
"$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
}
},
"properties": {
"destination": {
"type": "string",
"description": "The destination (queue) name for this channel. SHOULD only be specified if the channel name differs from the actual destination name, such as when the channel name is not a valid destination name according to the JMS Provider. Defaults to the channel name."
},
"destinationType": {
"type": "string",
"enum": ["queue", "fifo-queue"],
"default": "queue",
"description": "The type of destination. SHOULD be specified to document the messaging model (point-to-point, or strict message ordering) supported by this channel."
},
"bindingVersion": {
"type": "string",
"enum": [
"0.0.1"
],
"description": "The version of this binding. If omitted, 'latest' MUST be assumed."
}

},
"examples": [
{
"destination": "user-signed-up",
"destinationType": "fifo-queue",
"bindingVersion": "0.0.1"
}
]
}
73 changes: 73 additions & 0 deletions bindings/jms/0.0.1/message.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/bindings/jms/0.0.1/message.json",
"title": "Message Schema",
"description": "This object contains configuration for describing a JMS message as an AsyncAPI message. This objects only contains configuration that can not be provided in the AsyncAPI standard message object.",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-[\\w\\d\\.\\x2d_]+$": {
"$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
}
},
"properties": {
"headers": {
"$ref": "http://asyncapi.com/definitions/3.0.0/schema.json",
"description": "A Schema object containing the definitions for JMS headers (protocol headers). This schema MUST be of type 'object' and have a 'properties' key. Examples of JMS protocol headers are 'JMSMessageID', 'JMSTimestamp', and 'JMSCorrelationID'."
},
"bindingVersion": {
"type": "string",
"enum": [
"0.0.1"
],
"description": "The version of this binding. If omitted, 'latest' MUST be assumed."
}

},
"examples": [
{
"headers": {
"type": "object",
"required": ["JMSMessageID"],
"properties": {
"JMSMessageID": {
"type": ["string", "null"],
"description": "A unique message identifier. This may be set by your JMS Provider on your behalf."
},
"JMSTimestamp": {
"type": "integer",
"description": "The time the message was sent. This may be set by your JMS Provider on your behalf. The time the message was sent. The value of the timestamp is the amount of time, measured in milliseconds, that has elapsed since midnight, January 1, 1970, UTC."
},
"JMSDeliveryMode": {
"type": "string",
"enum": ["PERSISTENT", "NON_PERSISTENT"],
"default": "PERSISTENT",
"description": "Denotes the delivery mode for the message. This may be set by your JMS Provider on your behalf."
},
"JMSPriority": {
"type": "integer",
"default": 4,
"description": "The priority of the message. This may be set by your JMS Provider on your behalf."
},
"JMSExpires": {
"type": "integer",
"description": "The time at which the message expires. This may be set by your JMS Provider on your behalf. A value of zero means that the message does not expire. Any non-zero value is the amount of time, measured in milliseconds, that has elapsed since midnight, January 1, 1970, UTC, at which the message will expire."
},
"JMSType": {
"type": ["string", "null"],
"description": "The type of message. Some JMS providers use a message repository that contains the definitions of messages sent by applications. The 'JMSType' header field may reference a message's definition in the provider's repository. The JMS API does not define a standard message definition repository, nor does it define a naming policy for the definitions it contains. Some messaging systems require that a message type definition for each application message be created and that each message specify its type. In order to work with such JMS providers, JMS clients should assign a value to 'JMSType', whether the application makes use of it or not. This ensures that the field is properly set for those providers that require it."
},
"JMSCorrelationID": {
"type": ["string", "null"],
"description": "The correlation identifier of the message. A client can use the 'JMSCorrelationID' header field to link one message with another. A typical use is to link a response message with its request message. Since each message sent by a JMS provider is assigned a message ID value, it is convenient to link messages via message ID, such message ID values must start with the 'ID:' prefix. Conversely, application-specified values must not start with the 'ID:' prefix; this is reserved for provider-generated message ID values."
},
"JMSReplyTo": {
"type": "string",
"description": "The queue or topic that the message sender expects replies to."
}
}
},
"bindingVersion": "0.0.1"
}
]
}
69 changes: 69 additions & 0 deletions bindings/jms/0.0.1/server.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/bindings/jms/0.0.1/server.json",
"title": "Server Schema",
"description": "This object contains configuration for describing a JMS broker as an AsyncAPI server. This objects only contains configuration that can not be provided in the AsyncAPI standard server object.",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-[\\w\\d\\.\\x2d_]+$": {
"$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
}
},
"required": ["jmsConnectionFactory"],
"properties": {
"jmsConnectionFactory": {
"type": "string",
"description": "The classname of the ConnectionFactory implementation for the JMS Provider."
},
"properties": {
"type": "array",
"items": {
"$ref": "http://asyncapi.com/bindings/jms/0.0.1/server.json#/definitions/property"
},
"description": "Additional properties to set on the JMS ConnectionFactory implementation for the JMS Provider."
},
"clientID": {
"type": "string",
"description": "A client identifier for applications that use this JMS connection factory. If the Client ID Policy is set to 'Restricted' (the default), then configuring a Client ID on the ConnectionFactory prevents more than one JMS client from using a connection from this factory."
},
"bindingVersion": {
"type": "string",
"enum": [
"0.0.1"
],
"description": "The version of this binding. If omitted, 'latest' MUST be assumed."
}

},
"definitions": {
"property": {
"type": "object",
"required": ["name", "value"],
"properties": {
"name": {
"type": "string",
"description": "The name of a property"
},
"value": {
"type": ["string", "boolean", "number", "null"],
"description": "The name of a property"
}
}
}
},
"examples": [
{
"jmsConnectionFactory": "org.apache.activemq.ActiveMQConnectionFactory",
"properties": [
{
"name": "disableTimeStampsByDefault",
"value": false
}
],
"clientID": "my-application-1",
"bindingVersion": "0.0.1"
}
]
}

Empty file removed bindings/sns/.keep
Empty file.
Loading

0 comments on commit 4a6cb55

Please sign in to comment.