From 61ac60c9d23852ee50b40ba42434929204c6883a Mon Sep 17 00:00:00 2001 From: Ron Date: Mon, 20 Feb 2017 18:20:55 -0800 Subject: [PATCH 1/6] Updated Schema Object --- versions/3.0.md | 65 ++++++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index fb5e32c04b..5e424bb67b 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2260,18 +2260,14 @@ $ref: 'definitions.yaml#/Pet' 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 based on the [JSON Schema Specification Draft 4](http://json-schema.org/) and uses a predefined subset of it. -On top of this subset, there are extensions provided by this specification to allow for more complete documentation. +This object is an extended subset of the [JSON Schema Specification Draft 4](http://json-schema.org/). Further information about the properties can be found in [JSON Schema Core](http://json-schema.org/latest/json-schema-core.html) and [JSON Schema Validation](http://json-schema.org/latest/json-schema-validation.html). Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. The following properties are taken directly from the JSON Schema definition and follow the same specifications: -- $ref - As a [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) -- format (See [Data Type Formats](#dataTypeFormat) for further details) + - title -- description ([CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation) -- default (Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object) - multipleOf - maximum - exclusiveMaximum @@ -2287,25 +2283,32 @@ The following properties are taken directly from the JSON Schema definition and - minProperties - required - enum -- type - -The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. -Their definition is the same as the one from JSON Schema, only where the original definition references the JSON Schema definition, the [Schema Object](#schemaObject) definition is used instead. -- items -- allOf -- oneOf -- anyOf -- not -- properties -- additionalProperties + +The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI 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 of 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. If object, definition MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). +- $ref - As a [Reference Object](#referenceObject). +- 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 OAS offers a few additional predefined formats. +- default - Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. + +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. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -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. -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 MUST NOT be sent as part of the request. Properties marked as `readOnly` being `true` SHOULD NOT be in the `required` list of the defined schema. Default value is `false`. +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 MUST 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 MUST 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. @@ -2314,7 +2317,7 @@ Field Name | Type | Description This object can be extended with [Specification Extensions](#specificationExtensions). -###### Composition and Inheritance (Polymorphism) +###### Composition and Inheritance (Polymorphism) The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. `allOf` takes in an array of object definitions that are validated *independently* but together compose a single object. @@ -2323,7 +2326,9 @@ While composition offers model extensibility, it does not imply a hierarchy betw To support polymorphism, OpenAPI Specification adds the support of the `discriminator` field. When used, the `discriminator` will be the name of the property used to decide which schema definition is used to validate the structure of the model. As such, the `discriminator` field MUST be a required field. -The value of the chosen property has to be the friendly name given to the model under the `definitions` property. +There are are two ways to define the value of a discriminator for an inheriting instance. +- Use the definition's name. +- Override the definition's name by overriding the property with a new value. If exists, this takes precedence over the definition's name. As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. ###### XML Modeling @@ -2335,8 +2340,6 @@ The [XML Object](#xmlObject) contains additional information about the available ###### Primitive Sample -Unlike previous versions of Swagger, OpenAPI Schema definitions can be used to describe primitive and arrays as well. - ```json { "type": "string", @@ -2362,7 +2365,7 @@ format: email "type": "string" }, "address": { - "$ref": "#/definitions/Address" + "$ref": "#/components/definitions/Address" }, "age": { "type": "integer", @@ -2381,7 +2384,7 @@ properties: name: type: string address: - $ref: '#/definitions/Address' + $ref: '#/components/definitions/Address' age: type: integer format: int32 @@ -2413,7 +2416,7 @@ For a string to model mapping: { "type": "object", "additionalProperties": { - "$ref": "#/definitions/ComplexModel" + "$ref": "#/components/definitions/ComplexModel" } } ``` @@ -2421,7 +2424,7 @@ For a string to model mapping: ```yaml type: object additionalProperties: - $ref: '#/definitions/ComplexModel' + $ref: '#/components/definitions/ComplexModel' ``` ###### Model with Example @@ -2599,7 +2602,7 @@ definitions: ] }, "Cat": { - "description": "A representation of a cat", + "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", "allOf": [ { "$ref": "#/definitions/Pet" @@ -2626,7 +2629,7 @@ definitions: ] }, "Dog": { - "description": "A representation of a dog", + "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", "allOf": [ { "$ref": "#/definitions/Pet" @@ -2665,7 +2668,7 @@ definitions: required: - name - petType - Cat: + Cat: ## "Cat" will be used as the discriminator value description: A representation of a cat allOf: - $ref: '#/definitions/Pet' @@ -2682,7 +2685,7 @@ definitions: - aggressive required: - huntingSkill - Dog: + Dog: ## "Dog" will be used as the discriminator value description: A representation of a dog allOf: - $ref: '#/definitions/Pet' From 7648c729cb27e1ad62e8fb2e4b6afe0e2624eb13 Mon Sep 17 00:00:00 2001 From: Ron Date: Tue, 21 Feb 2017 14:41:08 -0800 Subject: [PATCH 2/6] MOAR updates --- versions/3.0.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 5e424bb67b..6a9df2dd73 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -144,14 +144,15 @@ By convention, the OpenAPI Specification (OAS) file is named `openapi.json` or ` ### Data Types -Primitive data types in the OAS are based on the types supported by the [JSON-Schema Draft 4](http://json-schema.org/latest/json-schema-core.html#anchor8). -Models are described using the [Schema Object](#schemaObject) which is a subset of JSON Schema Draft 4. +Primitive data types in the OAS are based on the types supported by the [JSON-Schema Draft Wright 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2) (also known as, JSON Schema Draft 05). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. `null` is not supported as a value. +Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Draft 05. Primitives have an optional modifier property `format`. OAS uses several known formats to more finely define the data type being used. However, the `format` property is an open `string`-valued property, and can have any value to support documentation needs. Formats such as `"email"`, `"uuid"`, etc., can be used even though they are not defined by this specification. -Types that are not accompanied by a `format` property follow their definition from the JSON Schema. +Types that are not accompanied by a `format` property follow their definition from the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` was not specified. + The formats defined by the OAS are: @@ -2214,8 +2215,8 @@ definitions: A simple object to allow referencing other definitions in the specification. It can be used to reference parameters and responses that are defined at the top level for reuse. -The Reference Object is a [JSON Reference](http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-02) that uses a [JSON Pointer](http://tools.ietf.org/html/rfc6901) as its value. -For this specification, only [canonical dereferencing](http://json-schema.org/latest/json-schema-core.html#anchor27) is supported. +The Reference Object is a [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) that uses a [JSON Pointer](http://tools.ietf.org/html/rfc6901) as its value. +For this specification, only [External references](https://tools.ietf.org/html/draft-wright-json-schema-00#section-8.2.2) are supported ([Internal references](https://tools.ietf.org/html/draft-wright-json-schema-00#section-8.2.1) are not supported). ##### Fixed Fields Field Name | Type | Description @@ -2260,9 +2261,9 @@ $ref: 'definitions.yaml#/Pet' 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 Draft 4](http://json-schema.org/). +This object is an extended subset of the [JSON Schema Specification Wright Draft 00](http://json-schema.org/), also known as JSON Schema Draft 05. -Further information about the properties can be found in [JSON Schema Core](http://json-schema.org/latest/json-schema-core.html) and [JSON Schema Validation](http://json-schema.org/latest/json-schema-validation.html). +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). Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. The following properties are taken directly from the JSON Schema definition and follow the same specifications: @@ -2290,11 +2291,11 @@ The following properties are taken from the JSON Schema definition but their def - 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 of the `type` is `array`. +- 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. If object, definition MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). -- $ref - As a [Reference Object](#referenceObject). -- description ([CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation). +- $ref - A [Reference Object](#referenceObject). +- 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 OAS offers a few additional predefined formats. - default - Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. @@ -2307,8 +2308,8 @@ 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 MUST 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 MUST 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`. +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. From f459807ae2b0b3c54e00f393f2e7d5aef0fb96ea Mon Sep 17 00:00:00 2001 From: Ron Date: Tue, 21 Feb 2017 19:14:30 -0800 Subject: [PATCH 3/6] MOAR updates - Removed hyphen - Updated naming convention to reference only Wright Draft 00 - Simplified explanation of JSON Reference resolution --- versions/3.0.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 6a9df2dd73..4b37b71cb6 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -144,8 +144,8 @@ By convention, the OpenAPI Specification (OAS) file is named `openapi.json` or ` ### Data Types -Primitive data types in the OAS are based on the types supported by the [JSON-Schema Draft Wright 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2) (also known as, JSON Schema Draft 05). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. `null` is not supported as a value. -Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Draft 05. +Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. `null` is not supported as a value. +Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Specification Wright Draft 00. Primitives have an optional modifier property `format`. OAS uses several known formats to more finely define the data type being used. @@ -2216,7 +2216,8 @@ A simple object to allow referencing other definitions in the specification. It can be used to reference parameters and responses that are defined at the top level for reuse. The Reference Object is a [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) that uses a [JSON Pointer](http://tools.ietf.org/html/rfc6901) as its value. -For this specification, only [External references](https://tools.ietf.org/html/draft-wright-json-schema-00#section-8.2.2) are supported ([Internal references](https://tools.ietf.org/html/draft-wright-json-schema-00#section-8.2.1) are not supported). + +For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification. ##### Fixed Fields Field Name | Type | Description @@ -2261,7 +2262,7 @@ $ref: 'definitions.yaml#/Pet' 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/), also known as JSON Schema Draft 05. +This object is an extended subset of the [JSON Schema Specification Wright Draft 00](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). Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. From 3fc3a6c648bcb1b347109540aa96e717656e301e Mon Sep 17 00:00:00 2001 From: Ron Date: Tue, 21 Feb 2017 19:20:46 -0800 Subject: [PATCH 4/6] Complete rework of JSON Reference --- versions/3.0.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 4b37b71cb6..eaf87093ae 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2212,10 +2212,9 @@ definitions: #### Reference Object -A simple object to allow referencing other definitions in the specification. -It can be used to reference parameters and responses that are defined at the top level for reuse. +A simple object to allow referencing other definitions in the specification, internally and externally. -The Reference Object is a [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) that uses a [JSON Pointer](http://tools.ietf.org/html/rfc6901) as its value. +The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification. @@ -2228,12 +2227,12 @@ Field Name | Type | Description ```json { - "$ref": "#/definitions/Pet" + "$ref": "#/components/definitions/Pet" } ``` ```yaml -$ref: '#/definitions/Pet' +$ref: '#/components/definitions/Pet' ``` ##### Relative Schema File Example @@ -2244,7 +2243,7 @@ $ref: '#/definitions/Pet' ``` ```yaml -$ref: 'Pet.yaml' +$ref: Pet.yaml ``` ##### Relative Files With Embedded Schema Example @@ -2255,7 +2254,7 @@ $ref: 'Pet.yaml' ``` ```yaml -$ref: 'definitions.yaml#/Pet' +$ref: definitions.yaml#/Pet ``` #### Schema Object From 7d0ae2dd6dbfba5bafd26113e6919468213f875a Mon Sep 17 00:00:00 2001 From: Ron Date: Wed, 22 Feb 2017 11:28:43 -0800 Subject: [PATCH 5/6] Even MOAR changes - clarified additionalProperties - clarified default - changed the definition of $ref --- versions/3.0.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index eaf87093ae..20829a2ed2 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2293,11 +2293,12 @@ The following properties are taken from the JSON Schema definition but their def - 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. If object, definition MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). -- $ref - A [Reference Object](#referenceObject). +- 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 OAS offers a few additional predefined formats. -- default - Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object. +- 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 Scheme Object can be used, a [Reference Object](#referenceObject) can be used in place. This allows referencing definitions in place of defining them inline. Effectively, it is the `$ref` property in JSON Schema but follows the same guidelines and restrictions as the Reference Object. For example, additional properties alongside a `$ref` SHALL be ignored. Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported. From 5b64060c6d6a5a1d445d4c164f51295e277d33e5 Mon Sep 17 00:00:00 2001 From: Ron Date: Wed, 22 Feb 2017 14:35:58 -0800 Subject: [PATCH 6/6] Hopefully last updates --- versions/3.0.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 20829a2ed2..2b9e08a012 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2214,7 +2214,7 @@ definitions: A simple object to allow referencing other definitions in the specification, internally and externally. -The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. +The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification. @@ -2223,6 +2223,8 @@ Field Name | Type | Description ---|:---:|--- $ref | `string` | **Required.** The reference string. +This object cannot be extended with additional properties and any properties added SHALL be ignored. + ##### Reference Object Example ```json @@ -2298,7 +2300,7 @@ The following properties are taken from the JSON Schema definition but their def - format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the OAS 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 Scheme Object can be used, a [Reference Object](#referenceObject) can be used in place. This allows referencing definitions in place of defining them inline. Effectively, it is the `$ref` property in JSON Schema but follows the same guidelines and restrictions as the Reference Object. For example, additional properties alongside a `$ref` SHALL be ignored. +Alternatively, any time a Scheme 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.