diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 1f0830643f..67623f28cb 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -117,7 +117,7 @@ For example, if a field has an array value, the JSON array representation will b ```json { - "field": [ 1, 2, 3 ] + "field": [1, 2, 3] } ``` All field names in the specification are **case sensitive**. @@ -563,7 +563,7 @@ my.org.User "securitySchemes": { "api_key": { "type": "apiKey", - "name": "api_key", + "name": "api-key", "in": "header" }, "petstore_auth": { @@ -640,7 +640,7 @@ components: securitySchemes: api_key: type: apiKey - name: api_key + name: api-key in: header petstore_auth: type: oauth2 @@ -696,7 +696,7 @@ The following may lead to ambiguous resolution: "get": { "description": "Returns all pets from the system that the user has access to", "responses": { - "200": { + "200": { "description": "A list of pets.", "content": { "application/json": { @@ -818,7 +818,7 @@ get: '200': description: pet response content: - '*/*' : + '*/*': schema: type: array items: @@ -826,7 +826,7 @@ get: default: description: error payload content: - 'text/html': + text/html: schema: $ref: '#/components/schemas/ErrorModel' parameters: @@ -837,7 +837,7 @@ parameters: schema: type: array items: - type: string + type: string style: simple ``` @@ -945,7 +945,7 @@ parameters: type: string requestBody: content: - 'application/x-www-form-urlencoded': + application/x-www-form-urlencoded: schema: type: object properties: @@ -961,13 +961,13 @@ responses: '200': description: Pet updated. content: - 'application/json': {} - 'application/xml': {} + application/json: {} + application/xml: {} '405': description: Method Not Allowed content: - 'application/json': {} - 'application/xml': {} + application/json: {} + application/xml: {} security: - petstore_auth: - write:pets @@ -1272,36 +1272,36 @@ A request body with a referenced model definition. "$ref": "#/components/schemas/User" }, "examples": { - "user" : { - "summary": "User Example", - "externalValue": "https://foo.bar/examples/user-example.json" - } + "user" : { + "summary": "User Example", + "externalValue": "https://foo.bar/examples/user-example.json" } + } }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { - "user" : { - "summary": "User example in XML", - "externalValue": "https://foo.bar/examples/user-example.xml" - } + "user" : { + "summary": "User example in XML", + "externalValue": "https://foo.bar/examples/user-example.xml" } + } }, "text/plain": { "examples": { "user" : { - "summary": "User example in Plain text", - "externalValue": "https://foo.bar/examples/user-example.txt" + "summary": "User example in Plain text", + "externalValue": "https://foo.bar/examples/user-example.txt" } } }, "*/*": { "examples": { "user" : { - "summary": "User example in other format", - "externalValue": "https://foo.bar/examples/user-example.whatever" + "summary": "User example in other format", + "externalValue": "https://foo.bar/examples/user-example.whatever" } } } @@ -1312,30 +1312,30 @@ A request body with a referenced model definition. ```yaml description: user to add to the system content: - 'application/json': + application/json: schema: $ref: '#/components/schemas/User' examples: user: summary: User Example - externalValue: 'https://foo.bar/examples/user-example.json' - 'application/xml': + externalValue: https://foo.bar/examples/user-example.json + application/xml: schema: $ref: '#/components/schemas/User' examples: user: summary: User example in XML - externalValue: 'https://foo.bar/examples/user-example.xml' - 'text/plain': + externalValue: https://foo.bar/examples/user-example.xml + text/plain: examples: user: summary: User example in Plain text - externalValue: 'https://foo.bar/examples/user-example.txt' + externalValue: https://foo.bar/examples/user-example.txt '*/*': examples: user: summary: User example in other format - externalValue: 'https://foo.bar/examples/user-example.whatever' + externalValue: https://foo.bar/examples/user-example.whatever ``` A body parameter that is an array of string values: @@ -1387,32 +1387,31 @@ This object MAY be extended with [Specification Extensions](#specification-exten { "application/json": { "schema": { - "$ref": "#/components/schemas/Pet" + "$ref": "#/components/schemas/Pet" }, "examples": { "cat" : { "summary": "An example of a cat", - "value": - { - "name": "Fluffy", - "petType": "Cat", - "color": "White", - "gender": "male", - "breed": "Persian" - } + "value": { + "name": "Fluffy", + "petType": "Cat", + "color": "White", + "gender": "male", + "breed": "Persian" + } }, "dog": { "summary": "An example of a dog with a cat's name", - "value" : { + "value" : { "name": "Puma", "petType": "Dog", "color": "Black", "gender": "Female", "breed": "Mixed" - }, - "frog": { - "$ref": "#/components/examples/frog-example" } + }, + "frog": { + "$ref": "#/components/examples/frog-example" } } } @@ -1459,24 +1458,24 @@ Content transferred in binary (octet-stream) MAY omit `schema`: ```yaml # a PNG image as a binary file: content: - image/png: {} + image/png: {} ``` ```yaml # an arbitrary binary file: content: - application/octet-stream: {} + application/octet-stream: {} ``` Binary content transferred with base64 encoding: ```yaml content: - image/png: - schema: - type: string - contentMediaType: image/png - contentEncoding: base64 + image/png: + schema: + type: string + contentMediaType: image/png + contentEncoding: base64 ``` Note that the `Content-Type` remains `image/png`, describing the semantics of the payload. The JSON Schema `type` and `contentEncoding` fields explain that the payload is transferred as text. The JSON Schema `contentMediaType` is technically redundant, but can be used by JSON Schema tools that may not be aware of the OpenAPI context. @@ -1773,7 +1772,6 @@ Response with a string type: } } } - } ``` @@ -1793,9 +1791,9 @@ Plain text response with headers: "content": { "text/plain": { "schema": { - "type": "string", - "example": "whoa!" - } + "type": "string" + }, + "example": "whoa!" } }, "headers": { @@ -1923,7 +1921,7 @@ myCallback: requestBody: description: Callback payload content: - 'application/json': + application/json: schema: $ref: '#/components/schemas/SomePayload' responses: @@ -1940,7 +1938,7 @@ transactionCallback: requestBody: description: Callback payload content: - 'application/json': + application/json: schema: $ref: '#/components/schemas/SomePayload' responses: @@ -1981,27 +1979,27 @@ requestBody: bar: summary: A bar example value: {"bar": "baz"} - 'application/xml': + application/xml: examples: xmlExample: summary: This is an example in XML - externalValue: 'https://example.org/examples/address-example.xml' - 'text/plain': + externalValue: https://example.org/examples/address-example.xml + text/plain: examples: textExample: summary: This is a text example - externalValue: 'https://foo.bar/examples/address-example.txt' + externalValue: https://foo.bar/examples/address-example.txt ``` In a parameter: ```yaml parameters: - - name: 'zipCode' - in: 'query' + - name: zipCode + in: query schema: - type: 'string' - format: 'zip-code' + type: string + format: zip-code examples: zip-example: $ref: '#/components/examples/zip-example' @@ -2082,7 +2080,7 @@ paths: operationId: getUserAddress parameters: # get the `id` field from the request path parameter named `id` - userId: $request.path.id + userid: $request.path.id # the path item of the linked operation /users/{userid}/address: parameters: @@ -2239,8 +2237,8 @@ This object MAY be extended with [Specification Extensions](#specification-exten ```json { - "name": "pet", - "description": "Pets operations" + "name": "pet", + "description": "Pets operations" } ``` @@ -2273,7 +2271,7 @@ Note that this restriction on additional properties is a difference between Refe ```json { - "$ref": "#/components/schemas/Pet" + "$ref": "#/components/schemas/Pet" } ``` @@ -2664,7 +2662,7 @@ components: required: - name - petType - Cat: ## "Cat" will be used as the discriminator value + Cat: # "Cat" will be used as the discriminator value description: A representation of a cat allOf: - $ref: '#/components/schemas/Pet' @@ -2680,7 +2678,7 @@ components: - aggressive required: - huntingSkill - Dog: ## "Dog" will be used as the discriminator value + Dog: # "Dog" will be used as the discriminator value description: A representation of a dog allOf: - $ref: '#/components/schemas/Pet' @@ -2754,12 +2752,12 @@ MyResponseType: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' - - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' + - $ref: https://gigantic-server.com/schemas/Monster/schema.json discriminator: propertyName: petType mapping: dog: '#/components/schemas/Dog' - monster: 'https://gigantic-server.com/schemas/Monster/schema.json' + monster: https://gigantic-server.com/schemas/Monster/schema.json ``` Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. @@ -2859,9 +2857,9 @@ Basic string property: ```json { - "animals": { - "type": "string" - } + "animals": { + "type": "string" + } } ``` @@ -2878,12 +2876,12 @@ Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): ```json { - "animals": { - "type": "array", - "items": { - "type": "string" - } + "animals": { + "type": "array", + "items": { + "type": "string" } + } } ``` @@ -3226,14 +3224,14 @@ scheme: basic ```json { "type": "apiKey", - "name": "api_key", + "name": "api-key", "in": "header" } ``` ```yaml type: apiKey -name: api_key +name: api-key in: header ``` @@ -3243,7 +3241,7 @@ in: header { "type": "http", "scheme": "bearer", - "bearerFormat": "JWT", + "bearerFormat": "JWT" } ```