Skip to content

Commit

Permalink
Merge branch 'release/1.2.0'
Browse files Browse the repository at this point in the history
  • Loading branch information
@fmvilas
fmvilas committed Apr 13, 2018
2 parents 802c556 + 3334e84 commit 4ddb7fd
Show file tree
Hide file tree
Showing 5 changed files with 1,300 additions and 8 deletions.
134 changes: 131 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,6 @@ The AsyncAPI Specification is a project used to describe and document Asynchrono
The AsyncAPI Specification defines a set of files required to describe such an API.
These files can then be used to create utilities, such as documentation, integration and/or testing tools.

The AsyncAPI Specification is often used to describe the inter-process communication (IPC) in distributed systems built using a broker-centric architecture. In such cases, it's very easy to get confused with what the AsyncAPI files must describe. **It's RECOMMENDED to create a single file describing the whole system instead of creating a file for each [process](#definitionsProcess).** Otherwise, you will end up having lots of interdependent files.

The file(s) MUST describe the operations a new [process](#definitionsProcess) can perform. For instance:

```yaml
Expand Down Expand Up @@ -53,6 +51,8 @@ It means [processes](#definitionsProcess) can subscribe to `event.user.signup` t
- [Servers Object](#A2SServers)
- [Topics Object](#topicsObject)
- [Topic Item Object](#topicItemObject)
- [Stream Object](#streamObject)
- [Events Object](#eventsObject)
- [Message Object](#messageObject)
- [Tag Object](#tagObject)
- [External Documentation Object](#externalDocumentationObject)
Expand Down Expand Up @@ -140,7 +140,9 @@ Field Name | Type | Description
<a name="A2SInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed.
<a name="A2SBaseTopic"></a>baseTopic | [BaseTopic String](#baseTopicString) | The base topic to the API.
<a name="A2SServers"></a>servers | [Server Object](#serverObject) | An array of [Server Objects](#serverObject), which provide connectivity information to a target server.
<a name="A2STopics"></a>topics | [Topics Object](#topicsObject) | **Required.** The available topics and messages for the API.
<a name="A2STopics"></a>topics | [Topics Object](#topicsObject) | **Required unless [Stream Object](#streamObject) or [Events Object](#eventsObject) is provided.** The available topics and messages for the API.
<a name="A2SStream"></a>stream | [Stream Object](#streamObject) | **Required unless [Topics Object](#topicsObject) or [Events Object](#eventsObject) is provided.** The messages and configuration for the streaming API.
<a name="A2SEvents"></a>events | [Events Object](#eventsObject) | **Required unless [Topics Object](#topicsObject) or [Stream Object](#streamObject) is provided.** The messages and configuration for the events API.
<a name="A2SComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
<a name="A2SSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation.
<a name="A2STags"></a>tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique.
Expand Down Expand Up @@ -597,6 +599,132 @@ user.{userId}.signup:



#### <a name="streamObject"></a>Stream Object

Holds the framing configuration and the read/write operations for the streaming API.

##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="streamObjectFraming"></a>framing | [Stream Framing Object](#streamFramingObject) | **Required.** The framing configuration for the streaming API, i.e., whether is `chunked` or `sse` and the frame delimiter.
<a name="streamObjectRead"></a>read | [[Message Object](#messageObject)] | A list of messages a consumer can read from the API.
<a name="streamObjectWrite"></a>write | [[Message Object](#messageObject)] | A list of messages a consumer can send to the API.

Either `read` or `write` MUST be provided.

This object can be extended with [Specification Extensions](#specificationExtensions).

##### Stream Object Example

```json
{
"stream": {
"framing": {
"type": "chunked",
"delimiter": "\r\n"
},
"read": [
{ "$ref": "#/components/messages/chatMessage" },
{ "$ref": "#/components/messages/heartbeat" }
]
}
}
```

```yaml
stream:
framing:
type: 'chunked'
delimiter: '\r\n'
read:
- $ref: '#/components/messages/chatMessage'
- $ref: '#/components/messages/heartbeat'
```









#### <a name="streamFramingObject"></a>Stream Framing Object

Holds the framing configuration for the streaming API.

##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="streamFramingObjectType"></a>type | `string` | **Required.** The type of streaming API. Allowed values are `chunked` and `sse`.
<a name="streamFramingObjectDelimiter"></a>delimiter | `string` | The string to use as the frame delimiter. Allowed values are `\r\n` and `\n`. Defaults to `\r\n`.

This object can be extended with [Specification Extensions](#specificationExtensions).

##### Stream Framing Object Example

```json
{
"framing": {
"type": "chunked",
"delimiter": "\r\n"
}
}
```

```yaml
framing:
type: 'chunked'
delimiter: '\r\n'
```





#### <a name="eventsObject"></a>Events Object

Holds the send and receive operations for an API based on events but without topics, e.g., a WebSockets API.

##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="eventsObjectRead"></a>receive | [[Message Object](#messageObject)] | A list of messages a consumer can receive from the API.
<a name="eventsObjectWrite"></a>send | [[Message Object](#messageObject)] | A list of messages a consumer can send to the API.

Either `receive` or `send` MUST be provided.

This object can be extended with [Specification Extensions](#specificationExtensions).

##### Events Object Example

```json
{
"events": {
"receive": [
{ "$ref": "#/components/messages/chatMessage" },
{ "$ref": "#/components/messages/heartbeat" }
]
}
}
```

```yaml
events:
receive:
- $ref: '#/components/messages/chatMessage'
- $ref: '#/components/messages/heartbeat'
```







#### <a name="messageObject"></a>Message Object

Describes a message received on a given topic and operation.
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "asyncapi-specification",
"version": "1.1.0",
"version": "1.2.0",
"description": "AsyncAPI specification",
"scripts": {
"test": "node test/index.js"
Expand Down
157 changes: 153 additions & 4 deletions schema/asyncapi.json
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,28 @@
{
"title": "AsyncAPI 1.1.0 schema.",
"title": "AsyncAPI 1.2.0 schema.",
"id": "http://asyncapi.hitchhq.com/v1/schema.json#",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [
"asyncapi",
"info",
"topics"
"info"
],
"oneOf": [
{
"required": [
"topics"
]
},
{
"required": [
"stream"
]
},
{
"required": [
"events"
]
}
],
"additionalProperties": false,
"patternProperties": {
Expand Down Expand Up @@ -43,6 +59,14 @@
"topics": {
"$ref": "#/definitions/topics"
},
"stream": {
"$ref": "#/definitions/stream",
"description": "The list of messages a consumer can read or write from/to a streaming API."
},
"events": {
"$ref": "#/definitions/events",
"description": "The list of messages an events API sends and/or receives."
},
"components": {
"$ref": "#/definitions/components"
},
Expand Down Expand Up @@ -199,7 +223,9 @@
"wss",
"stomp",
"stomps",
"jms"
"jms",
"http",
"https"
]
},
"schemeVersion": {
Expand Down Expand Up @@ -575,6 +601,129 @@
}
]
},
"stream": {
"title": "Stream Object",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"minProperties": 1,
"properties": {
"framing": {
"title": "Stream Framing Object",
"type": "object",
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"minProperties": 1,
"oneOf": [
{
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"chunked"
]
},
"delimiter": {
"type": "string",
"enum": [
"\\r\\n",
"\\n"
],
"default": "\\r\\n"
}
}
},
{
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"sse"
]
},
"delimiter": {
"type": "string",
"enum": [
"\\n\\n"
],
"default": "\\n\\n"
}
}
}
]
},
"read": {
"title": "Stream Read Object",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/definitions/message"
}
},
"write": {
"title": "Stream Write Object",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/definitions/message"
}
}
}
},
"events": {
"title": "Events Object",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-": {
"$ref": "#/definitions/vendorExtension"
}
},
"minProperties": 1,
"anyOf": [
{
"required": [
"receive"
]
},
{
"required": [
"send"
]
}
],
"properties": {
"receive": {
"title": "Events Receive Object",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/definitions/message"
}
},
"send": {
"title": "Events Send Object",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/definitions/message"
}
}
}
},
"message": {
"type": "object",
"additionalProperties": false,
Expand Down
Loading

0 comments on commit 4ddb7fd

Please sign in to comment.