From a54f085deee4e7b579cfe020abce136d51b90aa4 Mon Sep 17 00:00:00 2001 From: fmvilas Date: Thu, 8 Aug 2019 19:08:56 +0200 Subject: [PATCH 1/3] Make Schema a superset of JSON Schema Draft 07 --- versions/next/asyncapi.md | 395 ++------------------------------------ versions/next/schema.json | 269 +++++++------------------- 2 files changed, 90 insertions(+), 574 deletions(-) diff --git a/versions/next/asyncapi.md b/versions/next/asyncapi.md index 6b7b5a6e..708ae58c 100644 --- a/versions/next/asyncapi.md +++ b/versions/next/asyncapi.md @@ -59,7 +59,6 @@ Means that the [application](#definitionsApplication) is a [consumer](#definitio - [Components Object](#componentsObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - - [XML Object](#xmlObject) - [Security Scheme Object](#securitySchemeObject) - [Parameter Object](#parameterObject) - [Protocol Info Object](#protocolInfoObject) @@ -931,9 +930,9 @@ The following table contains a set of values that every implementation MUST supp Name | Allowed values | Notes ---|:---:|--- -[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` | This is the equivalent of the [AsyncAPI Schema Object](#schemaObject) and it's the default when a `schemaFormat` is not provided. +[AsyncAPI 2.0.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.0.0`, `application/vnd.aai.asyncapi+json;version=2.0.0`, `application/vnd.aai.asyncapi+yaml;version=2.0.0` | This is the default when a `schemaFormat` is not provided. +[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` | [JSON Schema Draft 07](http://json-schema.org/specification-links.html#draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | -[JSON Schema Draft 04](http://json-schema.org/specification-links.html#draft-4) | `application/schema+json;version=draft-04`, `application/schema+yaml;version=draft-04` | [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` | @@ -1382,16 +1381,18 @@ components: The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. -This object is an extended subset of the [JSON Schema Specification Wright Draft 00](http://json-schema.org/). +This object is an superset of the [JSON Schema Specification Draft 07](http://json-schema.org/). -Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-wright-json-schema-00) and [JSON Schema Validation](https://tools.ietf.org/html/draft-wright-json-schema-validation-00). +Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. ##### Properties -The following properties are taken directly from the JSON Schema definition and follow the same specifications: +The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: - title +- type +- required - multipleOf - maximum - exclusiveMaximum @@ -1405,40 +1406,35 @@ The following properties are taken directly from the JSON Schema definition and - uniqueItems - maxProperties - minProperties -- required - enum +- propertyNames +- contains +- const +- examples +- if / then / else +- additionalItems +- readOnly +- writeOnly The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. -- type - Value MUST be a string. Multiple types via an array are not supported. - allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. `items` MUST be present if the `type` is `array`. -- properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). -- additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - description - [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. - format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. - default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`. Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions in place of defining them inline. -Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported. - -Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation: +In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`. discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#schemaComposition) for more details. -readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. -writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". This means that it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. -xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. -example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. -examples | [Any] | An array of free-form properties to include examples of instances for this schema. To represent examples that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1457,11 +1453,6 @@ There are are two ways to define the value of a discriminator for an inheriting - Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. -###### XML Modeling - -The [xml](#schemaObjectXml) property allows extra definitions when translating the JSON definition to XML. -The [XML Object](#xmlObject) contains additional information about the available options. - ##### Schema Object Examples ###### Primitive Sample @@ -1778,360 +1769,6 @@ schemas: - packSize ``` -#### XML Object - -A metadata object that allows for more fine-tuned XML model definitions. - -When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. -See examples for expected behavior. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. -namespace | `string` | The URL of the namespace definition. Value SHOULD be in the form of a URL. -prefix | `string` | The prefix to be used for the [name](#xmlObjectName). -attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. -wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### XML Object Examples - -The examples of the XML object definitions are included inside a property definition of a [Schema Object](#schemaObject) with a sample of the XML representation of it. - -###### No XML Element - -Basic string property: - -```json -{ - "animals": { - "type": "string" - } -} -``` - -```yaml -animals: - type: string -``` - -```xml -... -``` - -Basic string array property ([`wrapped`](#xmlObjectWrapped) is `false` by default): - -```json -{ - "animals": { - "type": "array", - "items": { - "type": "string" - } - } -} -``` - -```yaml -animals: - type: array - items: - type: string -``` - -```xml -... -... -... -``` - -###### XML Name Replacement - -```json -{ - "animals": { - "type": "string", - "xml": { - "name": "animal" - } - } -} -``` - -```yaml -animals: - type: string - xml: - name: animal -``` - -```xml -... -``` - - -###### XML Attribute, Prefix and Namespace - -In this example, a full model definition is shown. - -```json -{ - "Person": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int32", - "xml": { - "attribute": true - } - }, - "name": { - "type": "string", - "xml": { - "namespace": "http://example.com/schema/sample", - "prefix": "sample" - } - } - } - } -} -``` - -```yaml -Person: - type: object - properties: - id: - type: integer - format: int32 - xml: - attribute: true - name: - type: string - xml: - namespace: http://example.com/schema/sample - prefix: sample -``` - -```xml - - example - -``` - -###### XML Arrays - -Changing the element names: - -```json -{ - "animals": { - "type": "array", - "items": { - "type": "string", - "xml": { - "name": "animal" - } - } - } -} -``` - -```yaml -animals: - type: array - items: - type: string - xml: - name: animal -``` - -```xml -value -value -``` - -The external `name` property has no effect on the XML: - -```json -{ - "animals": { - "type": "array", - "items": { - "type": "string", - "xml": { - "name": "animal" - } - }, - "xml": { - "name": "aliens" - } - } -} -``` - -```yaml -animals: - type: array - items: - type: string - xml: - name: animal - xml: - name: aliens -``` - -```xml -value -value -``` - -Even when the array is wrapped, if no name is explicitly defined, the same name will be used both internally and externally: - -```json -{ - "animals": { - "type": "array", - "items": { - "type": "string" - }, - "xml": { - "wrapped": true - } - } -} -``` - -```yaml -animals: - type: array - items: - type: string - xml: - wrapped: true -``` - -```xml - - value - value - -``` - -To overcome the above example, the following definition can be used: - -```json -{ - "animals": { - "type": "array", - "items": { - "type": "string", - "xml": { - "name": "animal" - } - }, - "xml": { - "wrapped": true - } - } -} -``` - -```yaml -animals: - type: array - items: - type: string - xml: - name: animal - xml: - wrapped: true -``` - -```xml - - value - value - -``` - -Affecting both internal and external names: - -```json -{ - "animals": { - "type": "array", - "items": { - "type": "string", - "xml": { - "name": "animal" - } - }, - "xml": { - "name": "aliens", - "wrapped": true - } - } -} -``` - -```yaml -animals: - type: array - items: - type: string - xml: - name: animal - xml: - name: aliens - wrapped: true -``` - -```xml - - value - value - -``` - -If we change the external element but not the internal ones: - -```json -{ - "animals": { - "type": "array", - "items": { - "type": "string" - }, - "xml": { - "name": "aliens", - "wrapped": true - } - } -} -``` - -```yaml -animals: - type: array - items: - type: string - xml: - name: aliens - wrapped: true -``` - -```xml - - value - value - -``` - - diff --git a/versions/next/schema.json b/versions/next/schema.json index 29a3641d..19a060ea 100644 --- a/versions/next/schema.json +++ b/versions/next/schema.json @@ -326,214 +326,93 @@ "description": "JSON objects describing re-usable channel parameters." }, "schema": { - "type": "object", - "description": "A deterministic version of a JSON Schema object.", - "patternProperties": { - "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "#/definitions/specificationExtension" - } - }, - "properties": { - "$ref": { - "$ref": "#/definitions/ReferenceObject" - }, - "nullable": { - "type": "boolean", - "default": false - }, - "format": { - "type": "string" - }, - "title": { - "type": "string" - }, - "description": { - "type": "string" - }, - "default": {}, - "multipleOf": { - "type": "number", - "minimum": 0, - "exclusiveMinimum": 0 - }, - "maximum": { - "type": "number" - }, - "exclusiveMaximum": { - "type": "boolean", - "default": false - }, - "minimum": { - "type": "number" - }, - "exclusiveMinimum": { - "type": "boolean", - "default": false - }, - "maxLength": { - "type": "integer", - "minimum": 0 - }, - "minLength": { - "type": "integer", - "minimum": 0, - "default": 0 - }, - "pattern": { - "type": "string", - "format": "regex" - }, - "maxItems": { - "type": "integer", - "minimum": 0 - }, - "minItems": { - "type": "integer", - "minimum": 0, - "default": 0 - }, - "uniqueItems": { - "type": "boolean", - "default": false - }, - "maxProperties": { - "type": "integer", - "minimum": 0 - }, - "minProperties": { - "type": "integer", - "minimum": 0, - "default": 0 + "allOf": [ + { + "$ref": "http://json-schema.org/draft-07/schema#" }, - "required": { - "type": "array", - "items": { - "type": "string" + { + "type": "object", + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "#/definitions/specificationExtension" + } }, - "minItems": 1, - "uniqueItems": true - }, - "enum": { - "type": "array", - "minItems": 1, - "uniqueItems": true - }, - "deprecated": { - "type": "boolean", - "default": false - }, - "additionalProperties": { - "anyOf": [ - { + "properties": { + "additionalProperties": { "$ref": "#/definitions/schema" }, - { - "type": "boolean" - } - ], - "default": {} - }, - "type": { - "type": "string", - "enum": [ - "array", - "boolean", - "integer", - "null", - "number", - "object", - "string" - ] - }, - "items": { - "anyOf": [ - { - "$ref": "#/definitions/schema" + "items": { + "anyOf": [ + { + "$ref": "#/definitions/schema" + }, + { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/definitions/schema" + } + } + ], + "default": {} }, - { + "allOf": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/schema" } + }, + "oneOf": { + "type": "array", + "minItems": 2, + "items": { + "$ref": "#/definitions/schema" + } + }, + "anyOf": { + "type": "array", + "minItems": 2, + "items": { + "$ref": "#/definitions/schema" + } + }, + "not": { + "$ref": "#/definitions/schema" + }, + "properties": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/schema" + }, + "default": {} + }, + "patternProperties": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/schema" + }, + "default": {} + }, + "propertyNames": { + "$ref": "#/definitions/schema" + }, + "contains": { + "$ref": "#/definitions/schema" + }, + "discriminator": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/definitions/externalDocs" + }, + "deprecated": { + "type": "boolean", + "default": false } - ], - "default": {} - }, - "allOf": { - "type": "array", - "minItems": 1, - "items": { - "$ref": "#/definitions/schema" - } - }, - "oneOf": { - "type": "array", - "minItems": 2, - "items": { - "$ref": "#/definitions/schema" } - }, - "anyOf": { - "type": "array", - "minItems": 2, - "items": { - "$ref": "#/definitions/schema" - } - }, - "not": { - "$ref": "#/definitions/schema" - }, - "properties": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/schema" - }, - "default": {} - }, - "discriminator": { - "type": "string" - }, - "readOnly": { - "type": "boolean", - "default": false - }, - "xml": { - "$ref": "#/definitions/xml" - }, - "externalDocs": { - "$ref": "#/definitions/externalDocs" - }, - "example": {}, - "examples": { - "type": "array", - "items": {} } - }, - "additionalProperties": false - }, - "xml": { - "type": "object", - "additionalProperties": false, - "properties": { - "name": { - "type": "string" - }, - "namespace": { - "type": "string" - }, - "prefix": { - "type": "string" - }, - "attribute": { - "type": "boolean", - "default": false - }, - "wrapped": { - "type": "boolean", - "default": false - } - } + ] }, "externalDocs": { "type": "object", From 4dff1daff6cd842a5d4571aa4a29e1147671048c Mon Sep 17 00:00:00 2001 From: fmvilas Date: Thu, 8 Aug 2019 19:21:24 +0200 Subject: [PATCH 2/3] Increase the list of adjusted definitions --- versions/next/asyncapi.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/versions/next/asyncapi.md b/versions/next/asyncapi.md index 708ae58c..ebe40c4b 100644 --- a/versions/next/asyncapi.md +++ b/versions/next/asyncapi.md @@ -1407,17 +1407,21 @@ The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema - maxProperties - minProperties - enum -- propertyNames -- contains - const - examples - if / then / else -- additionalItems - readOnly - writeOnly The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. +- properties - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. +- patternProperties - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. +- additionalProperties - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. +- additionalItems - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. +- items - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. +- propertyNames - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. +- contains - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. From 1e80c7c001e64bdf3a70c5fe92bee773431a52ad Mon Sep 17 00:00:00 2001 From: fmvilas Date: Tue, 13 Aug 2019 15:28:41 +0200 Subject: [PATCH 3/3] Fix typo and remove wrong clarifications on all schema-related properties --- versions/next/asyncapi.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/versions/next/asyncapi.md b/versions/next/asyncapi.md index ebe40c4b..cf881fc3 100644 --- a/versions/next/asyncapi.md +++ b/versions/next/asyncapi.md @@ -1381,14 +1381,14 @@ components: The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. -This object is an superset of the [JSON Schema Specification Draft 07](http://json-schema.org/). +This object is a superset of the [JSON Schema Specification Draft 07](http://json-schema.org/). Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. ##### Properties -The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: +The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: - title - type @@ -1412,20 +1412,20 @@ The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema - if / then / else - readOnly - writeOnly +- properties +- patternProperties +- additionalProperties +- additionalItems +- items +- propertyNames +- contains +- allOf +- oneOf +- anyOf +- not The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. -- properties - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- patternProperties - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- additionalProperties - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- additionalItems - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- items - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- propertyNames - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- contains - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. -- not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - description - [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. - format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. - default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`.