Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Schema Object #894

Merged
merged 6 commits into from
Feb 22, 2017
Merged

Update Schema Object #894

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
61ac60c
Updated Schema Object
webron Feb 21, 2017
7648c72
MOAR updates
webron Feb 21, 2017
f459807
MOAR updates
webron Feb 22, 2017
3fc3a6c
Complete rework of JSON Reference
webron Feb 22, 2017
7d0ae2d
Even MOAR changes
webron Feb 22, 2017
5b64060
Hopefully last updates
webron Feb 22, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 41 additions & 37 deletions versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it read better using "JSON-Schema Draft Wright 00" here since that is what you mentioned prior? Also, was hyphenating JSON Schema to JSON-Schema intentional in the link text? If so, what's the rules behind when we hyphenate and when we do not?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The hyphen is a mistake. Will fix.

I can change it to JSON Schema Draft Wright 00 everywhere, but it's not the exact name. The exact name is draft-wright-json-schema-00 which is awkward to write across the doc.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense. I trust your judgement.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.


<a name="dataTypeFormat"></a>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:


Expand Down Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I understand what's being said here. Is the Reference Object only for local references, as in references within the same document? If that's the case, the value is itself a JSON Pointer as a JSON Reference allows both local and remote references.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reference Object is for all references whether local or remote.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's what I was hoping for. So in that case, the "that uses a JSON Pointer as its value" is not accurate is it? The JSON Pointer version of a $ref value is for local only and since a Reference Object is for local and remote references, isn't the Reference Object's $ref just a URI per the JSON References spec.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, @whitlockjc. The indication of JSON Pointer here is not needed. It was added in 2.0, back in the days where things were still unclear to us all. We now know better - A JSON References, is a JSON Reference, and in some cases the value is a JSON Pointer. The actual explanation here is wrong and unneeded. Will remove.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Completely reworked JSON Reference, see main comment.

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
Expand Down Expand Up @@ -2260,18 +2261,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 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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here you call it "JSON Schema Core" but you reference it earlier as "JSON Schema Specification Wright Draft 00". Make a decision and use it in both places.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

JSON Schema is split into two specifications - Core and Validation. Can't keep it as one, and shouldn't reference both every single time.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough.

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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove parens here (not used elsewhere in OAS when describing CommonMark)

- exclusiveMaximum
Expand All @@ -2287,25 +2284,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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be:
"MUST be of a Schema Object or Schema Reference" ? (Ditto on the other items in the list.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please elaborate on what "not a standard JSON Schema." means. However, if it means "not a full JSON Schema but the OpenAPI Specification schema", I think we should just drop this since you already refer explicitly to [Schema Object](#schemaObject)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be the Schema Object, not Schema Reference (which I assume you meant JSON Reference). The Schema Object contains the JSON Reference in it.

The 'standard JSON Schema' is in reference to the initial point that the Schema Object is an extended subset of JSON Schema. I'd rather keep this explicit here due to questions raised in the past.

Copy link
Member

@whitlockjc whitlockjc Feb 22, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@DavidBiesack I almost responded with a "+1" to your comment but I think the "Inline or referenced schema" as to being either a Schema Object or a JSON Reference to a Schema Object defined elsewhere. @webron's wording seem fine to me.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still think "not a standard JSON Schema" may be confusing and not needed -- it just raises questions and distracts from the spec. Better IMHO would be to remove it or as @whitlockjc suggests, add "or a or a JSON Reference to a Schema Object" (I don't thing "defined elsewhere" is needed; that is implicit in being a JSON References - concise is better)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is useful to remind people that even when embedding schema objects in allOf what is being embedded is not a regular JSON Schema. I suspect many people don't realize that the schemas inside OpenAPI are not regular JSON Schemas.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't linking to a Schema Object do this?

- 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. If object, definition MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced).
Copy link
Member

@whitlockjc whitlockjc Feb 22, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can it be a JSON Reference to a Schema Object? If so, you might want to use similar wording like you did elsewhere.

- $ref - A [Reference Object](#referenceObject).
Copy link
Member

@whitlockjc whitlockjc Feb 22, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me, any place you could have a Schema Object you would allow a JSON Reference to a Schema Object but it is an either/or, as in you cannot mix a JSON Reference and a Schema Object in the same object. I think we could have some extra wording here making sure this is known to be the case, much like we document the items property as being applicable and required only when type: array.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about defining a section for OpenAPI Schema Definition and cite that in all these places where an inline or ref is allowed, and then define OpenAPI Schema Definition as exactly one of (inline) Schema Object or a JSON reference to a Schema Object

- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't specifically tell what the type is, or its purpose. Would it make sense to do this and then throw the existing content into a "(Note: ...)"?


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
---|:---:|---
<a name="schemaDiscriminator"></a>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.
<a name="schemaReadOnly"></a>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`.
<a name="schemaNullable"></a>nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.
<a name="schemaDiscriminator"></a>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.
<a name="schemaReadOnly"></a>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`.
<a name="schemaWriteOnly"></a>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`.
<a name="schemaXml"></a>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.
<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema.
<a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema.
Expand All @@ -2314,7 +2318,7 @@ Field Name | Type | Description

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

###### Composition and Inheritance (Polymorphism)
###### <a name="schemaComposition"></a>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.
Expand All @@ -2323,7 +2327,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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Without an example, this portion is unclear to me.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, I might get this. Are you saying that the value of the discriminator field must match the name of a definition? Does this mean you can only use values that match keys of #/components/definitions?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point -- we rely heavily on external schema files via $ref. For example, if Cat and Dog are defined externally, I should still be able to use them. However for a schema included from an external schema.json there is no name as there is for one defined in /components/definitions. If all three schema (Pet, Cat, Doc) were defined externally (so that they can be used in multiple OpenAPI documents) and there is no single /components/definitions in which they reside, how would this work?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll be handling the discriminator in a separate PR.

- 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what this means. Override which property - the discriminator field (petType in this example)? If so, how is it overridden and specified? Would I do:

  Cat:  ## "Cat" will be used as the discriminator value
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
         petType:
              type: string
              enum:
              - Cat
          huntingSkill:
             ...

An example would help.

As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism.

###### XML Modeling
Expand All @@ -2335,8 +2341,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",
Expand All @@ -2362,7 +2366,7 @@ format: email
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
"$ref": "#/components/definitions/Address"
},
"age": {
"type": "integer",
Expand All @@ -2381,7 +2385,7 @@ properties:
name:
type: string
address:
$ref: '#/definitions/Address'
$ref: '#/components/definitions/Address'
age:
type: integer
format: int32
Expand Down Expand Up @@ -2413,15 +2417,15 @@ For a string to model mapping:
{
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/ComplexModel"
"$ref": "#/components/definitions/ComplexModel"
}
}
```

```yaml
type: object
additionalProperties:
$ref: '#/definitions/ComplexModel'
$ref: '#/components/definitions/ComplexModel'
```

###### Model with Example
Expand Down Expand Up @@ -2599,7 +2603,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.",
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add an example:

Below are examples showing an array of Pet objects using petType as a discriminator:

- name: "Fluffy"
  petType: "Cat"
  huntingSkill: "lazy"
- name: "Rover"
  petType: "Dog"
  packSize: 6
[
  {
    "name" : "Fluffy",
    "petType" : "Cat",
    "huntingSkill" : "lazy"
  },
  {
    "name" : "Rover",
    "petType" : "Dog",
    "packSize" : 6
  }
]

"allOf": [
{
"$ref": "#/definitions/Pet"
Expand All @@ -2626,7 +2630,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"
Expand Down Expand Up @@ -2665,7 +2669,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'
Expand All @@ -2682,7 +2686,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'
Expand Down