diff --git a/schemas/v3.1/meta-openapi.json b/schemas/v3.1/meta-openapi.json deleted file mode 100644 index 2da0487404..0000000000 --- a/schemas/v3.1/meta-openapi.json +++ /dev/null @@ -1,100 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft/2019-WIP/schema#", - "$id": "https://spec.openapis.org/oas/3.1/meta", - "$vocabulary": { - "https://specs.openapis.org/oas/3.1/vocab/openapi": true - }, - "$recursiveAnchor": true, - "title": "OpenAPI Vocabulary Schema", - "type": ["object", "boolean"], - "allOf": [ - { - "$ref": "http://json-schema.org/draft/2019-WIP/schema" - }, - { - "properties": { - "nullable": { - "type": "boolean", - "default": false, - "deprecated": true - }, - "discriminator": { - "$ref": "#/$defs/Discriminator" - }, - "example": { - "deprecated": true - }, - "externalDocs": { - "$ref": "#/$defs/ExternalDocumentation" // how to reference this from openapi-vocabulary.json - }, - "xml": { - "$ref": "#/$defs/XML" - } - } - } - ], - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false, - "$defs": { - "AllowedTypes": { - "type": "string", - "enum": [ - "array", - "boolean", - "integer", - "number", - "object", - "string", - "null" - ] - }, - "Discriminator": { - "type": "object", - "required": [ - "propertyName" - ], - "properties": { - "propertyName": { - "type": "string" - }, - "mapping": { - "type": "object", - "additionalProperties": { - "type": "string" - } - } - } - }, - "XML": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "namespace": { - "type": "string", - "format": "uri" - }, - "prefix": { - "type": "string" - }, - "attribute": { - "type": "boolean", - "default": false - }, - "wrapped": { - "type": "boolean", - "default": false - } - }, - "patternProperties": { - "^x-": { - } - }, - "unevaluatedProperties": false - } - } -} diff --git a/schemas/v3.1/meta/oas.json b/schemas/v3.1/meta/oas.json new file mode 100644 index 0000000000..5c4ec595fc --- /dev/null +++ b/schemas/v3.1/meta/oas.json @@ -0,0 +1,1424 @@ +{ + "$schema": "http://json-schema.org/draft/2019-WIP/schema#", + "$id": "https://spec.openapis.org/oas/3.1/meta/oas", + "$vocabulary": { + "https://specs.openapis.org/oas/3.1/vocab/oas": true + }, + "$recursiveAnchor": true, + "title": "OpenAPI Schema Object Vocabulary Schema", + "type": ["object", "boolean"], + "properties": { + "nullable": { + "type": "boolean", + "default": false, + "deprecated": true + }, + "discriminator": { + "$ref": "#/$defs/Discriminator" + }, + "example": { + "deprecated": true + }, + "externalDocs": { + "$ref": "#/$defs/ExternalDocumentation" + }, + "xml": { + "$ref": "#/$defs/XML" + } + }, + "patternProperties": { + "^x-": { + } + }, + "unevaluatedProperties": false, + "$defs": { + "Discriminator": { + "type": "object", + "required": [ + "propertyName" + ], + "properties": { + "propertyName": { + "type": "string" + }, + "mapping": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "XML": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "namespace": { + "type": "string", + "format": "uri" + }, + "prefix": { + "type": "string" + }, + "attribute": { + "type": "boolean", + "default": false + }, + "wrapped": { + "type": "boolean", + "default": false + } + }, + "patternProperties": { + "^x-": { + } + }, + "unevaluatedProperties": false + } + }, + "Reference": { + "type": "object", + "required": [ + "$ref" + ], + "patternProperties": { + "^\\$ref$": { + "type": "string", + "format": "uri-reference" + } + } + }, + "Info": { + "type": "object", + "required": [ + "title", + "version" + ], + "properties": { + "title": { + "type": "string" + }, + "description": { + "type": "string" + }, + "termsOfService": { + "type": "string", + "format": "uri-reference" + }, + "contact": { + "$ref": "#/$defs/Contact" + }, + "license": { + "$ref": "#/$defs/License" + }, + "version": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Contact": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + }, + "email": { + "type": "string", + "format": "email" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "License": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Server": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string" + }, + "description": { + "type": "string" + }, + "variables": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/ServerVariable" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ServerVariable": { + "type": "object", + "required": [ + "default" + ], + "properties": { + "enum": { + "type": "array", + "items": { + "type": "string" + } + }, + "default": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Components": { + "type": "object", + "properties": { + "schemas": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/$defs/Schema" + }, + { + "$ref": "#/$defs/Reference" + } + ] + } + } + }, + "responses": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/$defs/Reference" + }, + { + "$ref": "#/$defs/Response" + } + ] + } + } + }, + "parameters": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/$defs/Reference" + }, + { + "$ref": "#/$defs/Parameter" + } + ] + } + } + }, + "examples": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/$defs/Reference" + }, + { + "$ref": "#/$defs/Example" + } + ] + } + } + }, + "requestBodies": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/$defs/Reference" + }, + { + "$ref": "#/$defs/RequestBody" + } + ] + } + } + }, + "headers": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/$defs/Reference" + }, + { + "$ref": "#/$defs/Header" + } + ] + } + } + }, + "securitySchemes": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/$defs/Reference" + }, + { + "$ref": "#/$defs/SecurityScheme" + } + ] + } + } + }, + "links": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/$defs/Reference" + }, + { + "$ref": "#/$defs/Link" + } + ] + } + } + }, + "callbacks": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/$defs/Reference" + }, + { + "$ref": "#/$defs/Callback" + } + ] + } + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Schema": { + "$ref": "meta/schema" + }, + "Response": { + "type": "object", + "required": [ + "description" + ], + "properties": { + "description": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/$defs/Header" + }, + { + "$ref": "#/$defs/Reference" + } + ] + } + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/MediaType" + } + }, + "links": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/$defs/Link" + }, + { + "$ref": "#/$defs/Reference" + } + ] + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "MediaType": { + "type": "object", + "properties": { + "schema": { + "oneOf": [ + { + "$ref": "#/$defs/Schema" + }, + { + "$ref": "#/$defs/Reference" + } + ] + }, + "example": { + }, + "examples": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/$defs/Example" + }, + { + "$ref": "#/$defs/Reference" + } + ] + } + }, + "encoding": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/Encoding" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "allOf": [ + { + "$ref": "#/$defs/ExampleXORExamples" + } + ] + }, + "Example": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "value": { + }, + "externalValue": { + "type": "string", + "format": "uri-reference" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Header": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "required": { + "type": "boolean", + "default": false + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "allowEmptyValue": { + "type": "boolean", + "default": false + }, + "style": { + "type": "string", + "enum": [ + "simple" + ], + "default": "simple" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean", + "default": false + }, + "schema": { + "oneOf": [ + { + "$ref": "#/$defs/Schema" + }, + { + "$ref": "#/$defs/Reference" + } + ] + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/MediaType" + }, + "minProperties": 1, + "maxProperties": 1 + }, + "example": { + }, + "examples": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/$defs/Example" + }, + { + "$ref": "#/$defs/Reference" + } + ] + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "allOf": [ + { + "$ref": "#/$defs/ExampleXORExamples" + }, + { + "$ref": "#/$defs/SchemaXORContent" + } + ] + }, + "Paths": { + "type": "object", + "patternProperties": { + "^\\/": { + "$ref": "#/$defs/PathItem" + }, + "^x-": { + } + }, + "additionalProperties": false + }, + "PathItem": { + "type": "object", + "properties": { + "$ref": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/Server" + } + }, + "parameters": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/$defs/Parameter" + }, + { + "$ref": "#/$defs/Reference" + } + ] + }, + "uniqueItems": true + } + }, + "patternProperties": { + "^(get|put|post|delete|options|head|patch|trace)$": { + "$ref": "#/$defs/Operation" + }, + "^x-": { + } + }, + "additionalProperties": false + }, + "Operation": { + "type": "object", + "required": [ + "responses" + ], + "properties": { + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/ExternalDocumentation" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/$defs/Parameter" + }, + { + "$ref": "#/$defs/Reference" + } + ] + }, + "uniqueItems": true + }, + "requestBody": { + "oneOf": [ + { + "$ref": "#/$defs/RequestBody" + }, + { + "$ref": "#/$defs/Reference" + } + ] + }, + "responses": { + "$ref": "#/$defs/Responses" + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/$defs/Callback" + }, + { + "$ref": "#/$defs/Reference" + } + ] + } + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "security": { + "type": "array", + "items": { + "$ref": "#/$defs/SecurityRequirement" + } + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/Server" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Responses": { + "type": "object", + "properties": { + "default": { + "oneOf": [ + { + "$ref": "#/$defs/Response" + }, + { + "$ref": "#/$defs/Reference" + } + ] + } + }, + "patternProperties": { + "^[1-5](?:\\d{2}|XX)$": { + "oneOf": [ + { + "$ref": "#/$defs/Response" + }, + { + "$ref": "#/$defs/Reference" + } + ] + }, + "^x-": { + } + }, + "minProperties": 1, + "additionalProperties": false + }, + "SecurityRequirement": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "Tag": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/ExternalDocumentation" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ExternalDocumentation": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "description": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ExampleXORExamples": { + "description": "Example and examples are mutually exclusive", + "not": { + "required": [ + "example", + "examples" + ] + } + }, + "SchemaXORContent": { + "description": "Schema and content are mutually exclusive, at least one is required", + "not": { + "required": [ + "schema", + "content" + ] + }, + "oneOf": [ + { + "required": [ + "schema" + ] + }, + { + "required": [ + "content" + ], + "description": "Some properties are not allowed if content is present", + "allOf": [ + { + "not": { + "required": [ + "style" + ] + } + }, + { + "not": { + "required": [ + "explode" + ] + } + }, + { + "not": { + "required": [ + "allowReserved" + ] + } + }, + { + "not": { + "required": [ + "example" + ] + } + }, + { + "not": { + "required": [ + "examples" + ] + } + } + ] + } + ] + }, + "Parameter": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "in": { + "type": "string" + }, + "description": { + "type": "string" + }, + "required": { + "type": "boolean", + "default": false + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "allowEmptyValue": { + "type": "boolean", + "default": false + }, + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean", + "default": false + }, + "schema": { + "oneOf": [ + { + "$ref": "#/$defs/Schema" + }, + { + "$ref": "#/$defs/Reference" + } + ] + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/MediaType" + }, + "minProperties": 1, + "maxProperties": 1 + }, + "example": { + }, + "examples": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/$defs/Example" + }, + { + "$ref": "#/$defs/Reference" + } + ] + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "required": [ + "name", + "in" + ], + "allOf": [ + { + "$ref": "#/$defs/ExampleXORExamples" + }, + { + "$ref": "#/$defs/SchemaXORContent" + }, + { + "$ref": "#/$defs/ParameterLocation" + } + ] + }, + "ParameterLocation": { + "description": "Parameter location", + "oneOf": [ + { + "description": "Parameter in path", + "required": [ + "required" + ], + "properties": { + "in": { + "enum": [ + "path" + ] + }, + "style": { + "enum": [ + "matrix", + "label", + "simple" + ], + "default": "simple" + }, + "required": { + "enum": [ + true + ] + } + } + }, + { + "description": "Parameter in query", + "properties": { + "in": { + "enum": [ + "query" + ] + }, + "style": { + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ], + "default": "form" + } + } + }, + { + "description": "Parameter in header", + "properties": { + "in": { + "enum": [ + "header" + ] + }, + "style": { + "enum": [ + "simple" + ], + "default": "simple" + } + } + }, + { + "description": "Parameter in cookie", + "properties": { + "in": { + "enum": [ + "cookie" + ] + }, + "style": { + "enum": [ + "form" + ], + "default": "form" + } + } + } + ] + }, + "RequestBody": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "description": { + "type": "string" + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/MediaType" + } + }, + "required": { + "type": "boolean", + "default": false + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "SecurityScheme": { + "oneOf": [ + { + "$ref": "#/$defs/APIKeySecurityScheme" + }, + { + "$ref": "#/$defs/HTTPSecurityScheme" + }, + { + "$ref": "#/$defs/OAuth2SecurityScheme" + }, + { + "$ref": "#/$defs/OpenIdConnectSecurityScheme" + } + ] + }, + "APIKeySecurityScheme": { + "type": "object", + "required": [ + "type", + "name", + "in" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "apiKey" + ] + }, + "name": { + "type": "string" + }, + "in": { + "type": "string", + "enum": [ + "header", + "query", + "cookie" + ] + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "HTTPSecurityScheme": { + "type": "object", + "required": [ + "scheme", + "type" + ], + "properties": { + "scheme": { + "type": "string" + }, + "bearerFormat": { + "type": "string" + }, + "description": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "http" + ] + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "oneOf": [ + { + "description": "Bearer", + "properties": { + "scheme": { + "enum": [ + "bearer" + ] + } + } + }, + { + "description": "Non Bearer", + "not": { + "required": [ + "bearerFormat" + ] + }, + "properties": { + "scheme": { + "not": { + "enum": [ + "bearer" + ] + } + } + } + } + ] + }, + "OAuth2SecurityScheme": { + "type": "object", + "required": [ + "type", + "flows" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "oauth2" + ] + }, + "flows": { + "$ref": "#/$defs/OAuthFlows" + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "OpenIdConnectSecurityScheme": { + "type": "object", + "required": [ + "type", + "openIdConnectUrl" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "openIdConnect" + ] + }, + "openIdConnectUrl": { + "type": "string", + "format": "uri-reference" + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "OAuthFlows": { + "type": "object", + "properties": { + "implicit": { + "$ref": "#/$defs/ImplicitOAuthFlow" + }, + "password": { + "$ref": "#/$defs/PasswordOAuthFlow" + }, + "clientCredentials": { + "$ref": "#/$defs/ClientCredentialsFlow" + }, + "authorizationCode": { + "$ref": "#/$defs/AuthorizationCodeOAuthFlow" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ImplicitOAuthFlow": { + "type": "object", + "required": [ + "authorizationUrl", + "scopes" + ], + "properties": { + "authorizationUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "PasswordOAuthFlow": { + "type": "object", + "required": [ + "tokenUrl" + ], + "properties": { + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ClientCredentialsFlow": { + "type": "object", + "required": [ + "tokenUrl" + ], + "properties": { + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "AuthorizationCodeOAuthFlow": { + "type": "object", + "required": [ + "authorizationUrl", + "tokenUrl" + ], + "properties": { + "authorizationUrl": { + "type": "string", + "format": "uri-reference" + }, + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Link": { + "type": "object", + "properties": { + "operationId": { + "type": "string" + }, + "operationRef": { + "type": "string", + "format": "uri-reference" + }, + "parameters": { + "type": "object", + "additionalProperties": { + } + }, + "requestBody": { + }, + "description": { + "type": "string" + }, + "server": { + "$ref": "#/$defs/Server" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "not": { + "description": "Operation Id and Operation Ref are mutually exclusive", + "required": [ + "operationId", + "operationRef" + ] + } + }, + "Callback": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/PathItem" + }, + "patternProperties": { + "^x-": { + } + } + }, + "Encoding": { + "type": "object", + "properties": { + "contentType": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/Header" + } + }, + "style": { + "type": "string", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean", + "default": false + } + }, + "additionalProperties": false + } +} diff --git a/schemas/v3.1/meta/schema.json b/schemas/v3.1/meta/schema.json new file mode 100644 index 0000000000..89de673c05 --- /dev/null +++ b/schemas/v3.1/meta/schema.json @@ -0,0 +1,26 @@ +{ + "$schema": "http://json-schema.org/draft/2019-WIP/schema#", + "$id": "https://spec.openapis.org/oas/3.1/meta/schema#", + "$vocabulary": { + "https://json-schema.org/draft/2019-WIP/vocab/core": true, + "https://json-schema.org/draft/2019-WIP/vocab/applicator": true, + "https://json-schema.org/draft/2019-WIP/vocab/validation": true, + "https://json-schema.org/draft/2019-WIP/vocab/meta-data": true, + "https://json-schema.org/draft/2019-WIP/vocab/format": true, + "https://json-schema.org/draft/2019-WIP/vocab/content": true, + "https://spec.openapis.org/oas/3.1/vocab/oas ": true + }, + "$recursiveAnchor": true, + + "title": "OpenAPI Schema Object meta-schema", + "allOf": [ + {"$ref": "http://json-schema.org/draft/2019-WIP/meta/core"}, + {"$ref": "http://json-schema.org/draft/2019-WIP/meta/applicator"}, + {"$ref": "http://json-schema.org/draft/2019-WIP/meta/validation"}, + {"$ref": "http://json-schema.org/draft/2019-WIP/meta/meta-data"}, + {"$ref": "http://json-schema.org/draft/2019-WIP/meta/format"}, + {"$ref": "http://json-schema.org/draft/2019-WIP/meta/content"}, + {"$ref": "meta/oas"} + ], + "type": ["object", "boolean"] +} diff --git a/schemas/v3.1/openapi-vocabulary.json b/schemas/v3.1/openapi-vocabulary.json deleted file mode 100644 index 985219ab92..0000000000 --- a/schemas/v3.1/openapi-vocabulary.json +++ /dev/null @@ -1,1409 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft/2019-WIP/schema#", - "$id": "https://spec.openapis.org/oas/3.1/schema", - "$vocabulary": { - "https://json-schema.org/draft/2019-WIP/vocab/core": true, - "https://json-schema.org/draft/2019-WIP/vocab/applicator": true, - "https://json-schema.org/draft/2019-WIP/vocab/validation": true, - "https://json-schema.org/draft/2019-WIP/vocab/meta-data": true, - "https://json-schema.org/draft/2019-WIP/vocab/format": true, - "https://json-schema.org/draft/2019-WIP/vocab/content": true, - "https://specs.openapis.org/oas/3.1/vocab/openapi": true - }, - "$recursiveAnchor": true, - - "description": "Validation schema for OpenAPI Specification 3.0.X.", - "type": "object", - "required": [ - "openapi", - "info", - "paths" - ], - "properties": { - "openapi": { - "type": "string", - "pattern": "^3\\.0\\.\\d(-.+)?$" - }, - "info": { - "$ref": "#/$defs/Info" - }, - "externalDocs": { - "$ref": "#/$defs/ExternalDocumentation" - }, - "servers": { - "type": "array", - "items": { - "$ref": "#/$defs/Server" - } - }, - "security": { - "type": "array", - "items": { - "$ref": "#/$defs/SecurityRequirement" - } - }, - "tags": { - "type": "array", - "items": { - "$ref": "#/$defs/Tag" - }, - "uniqueItems": true - }, - "paths": { - "$ref": "#/$defs/Paths" - }, - "components": { - "$ref": "#/$defs/Components" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false, - "$defs": { - "Reference": { - "type": "object", - "required": [ - "$ref" - ], - "patternProperties": { - "^\\$ref$": { - "type": "string", - "format": "uri-reference" - } - } - }, - "Info": { - "type": "object", - "required": [ - "title", - "version" - ], - "properties": { - "title": { - "type": "string" - }, - "description": { - "type": "string" - }, - "termsOfService": { - "type": "string", - "format": "uri-reference" - }, - "contact": { - "$ref": "#/$defs/Contact" - }, - "license": { - "$ref": "#/$defs/License" - }, - "version": { - "type": "string" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "Contact": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri-reference" - }, - "email": { - "type": "string", - "format": "email" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "License": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri-reference" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "Server": { - "type": "object", - "required": [ - "url" - ], - "properties": { - "url": { - "type": "string" - }, - "description": { - "type": "string" - }, - "variables": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/ServerVariable" - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "ServerVariable": { - "type": "object", - "required": [ - "default" - ], - "properties": { - "enum": { - "type": "array", - "items": { - "type": "string" - } - }, - "default": { - "type": "string" - }, - "description": { - "type": "string" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "Components": { - "type": "object", - "properties": { - "schemas": { - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "oneOf": [ - { - "$ref": "#/$defs/Schema" - }, - { - "$ref": "#/$defs/Reference" - } - ] - } - } - }, - "responses": { - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "oneOf": [ - { - "$ref": "#/$defs/Reference" - }, - { - "$ref": "#/$defs/Response" - } - ] - } - } - }, - "parameters": { - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "oneOf": [ - { - "$ref": "#/$defs/Reference" - }, - { - "$ref": "#/$defs/Parameter" - } - ] - } - } - }, - "examples": { - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "oneOf": [ - { - "$ref": "#/$defs/Reference" - }, - { - "$ref": "#/$defs/Example" - } - ] - } - } - }, - "requestBodies": { - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "oneOf": [ - { - "$ref": "#/$defs/Reference" - }, - { - "$ref": "#/$defs/RequestBody" - } - ] - } - } - }, - "headers": { - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "oneOf": [ - { - "$ref": "#/$defs/Reference" - }, - { - "$ref": "#/$defs/Header" - } - ] - } - } - }, - "securitySchemes": { - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "oneOf": [ - { - "$ref": "#/$defs/Reference" - }, - { - "$ref": "#/$defs/SecurityScheme" - } - ] - } - } - }, - "links": { - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "oneOf": [ - { - "$ref": "#/$defs/Reference" - }, - { - "$ref": "#/$defs/Link" - } - ] - } - } - }, - "callbacks": { - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "oneOf": [ - { - "$ref": "#/$defs/Reference" - }, - { - "$ref": "#/$defs/Callback" - } - ] - } - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "Schema": { - "$ref": "https://spec.openapis.org/oas/3.1/meta" - }, - "Response": { - "type": "object", - "required": [ - "description" - ], - "properties": { - "description": { - "type": "string" - }, - "headers": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/$defs/Header" - }, - { - "$ref": "#/$defs/Reference" - } - ] - } - }, - "content": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/MediaType" - } - }, - "links": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/$defs/Link" - }, - { - "$ref": "#/$defs/Reference" - } - ] - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "MediaType": { - "type": "object", - "properties": { - "schema": { - "oneOf": [ - { - "$ref": "#/$defs/Schema" - }, - { - "$ref": "#/$defs/Reference" - } - ] - }, - "example": { - }, - "examples": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/$defs/Example" - }, - { - "$ref": "#/$defs/Reference" - } - ] - } - }, - "encoding": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/Encoding" - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false, - "allOf": [ - { - "$ref": "#/$defs/ExampleXORExamples" - } - ] - }, - "Example": { - "type": "object", - "properties": { - "summary": { - "type": "string" - }, - "description": { - "type": "string" - }, - "value": { - }, - "externalValue": { - "type": "string", - "format": "uri-reference" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "Header": { - "type": "object", - "properties": { - "description": { - "type": "string" - }, - "required": { - "type": "boolean", - "default": false - }, - "deprecated": { - "type": "boolean", - "default": false - }, - "allowEmptyValue": { - "type": "boolean", - "default": false - }, - "style": { - "type": "string", - "enum": [ - "simple" - ], - "default": "simple" - }, - "explode": { - "type": "boolean" - }, - "allowReserved": { - "type": "boolean", - "default": false - }, - "schema": { - "oneOf": [ - { - "$ref": "#/$defs/Schema" - }, - { - "$ref": "#/$defs/Reference" - } - ] - }, - "content": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/MediaType" - }, - "minProperties": 1, - "maxProperties": 1 - }, - "example": { - }, - "examples": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/$defs/Example" - }, - { - "$ref": "#/$defs/Reference" - } - ] - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false, - "allOf": [ - { - "$ref": "#/$defs/ExampleXORExamples" - }, - { - "$ref": "#/$defs/SchemaXORContent" - } - ] - }, - "Paths": { - "type": "object", - "patternProperties": { - "^\\/": { - "$ref": "#/$defs/PathItem" - }, - "^x-": { - } - }, - "additionalProperties": false - }, - "PathItem": { - "type": "object", - "properties": { - "$ref": { - "type": "string" - }, - "summary": { - "type": "string" - }, - "description": { - "type": "string" - }, - "servers": { - "type": "array", - "items": { - "$ref": "#/$defs/Server" - } - }, - "parameters": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/$defs/Parameter" - }, - { - "$ref": "#/$defs/Reference" - } - ] - }, - "uniqueItems": true - } - }, - "patternProperties": { - "^(get|put|post|delete|options|head|patch|trace)$": { - "$ref": "#/$defs/Operation" - }, - "^x-": { - } - }, - "additionalProperties": false - }, - "Operation": { - "type": "object", - "required": [ - "responses" - ], - "properties": { - "tags": { - "type": "array", - "items": { - "type": "string" - } - }, - "summary": { - "type": "string" - }, - "description": { - "type": "string" - }, - "externalDocs": { - "$ref": "#/$defs/ExternalDocumentation" - }, - "operationId": { - "type": "string" - }, - "parameters": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/$defs/Parameter" - }, - { - "$ref": "#/$defs/Reference" - } - ] - }, - "uniqueItems": true - }, - "requestBody": { - "oneOf": [ - { - "$ref": "#/$defs/RequestBody" - }, - { - "$ref": "#/$defs/Reference" - } - ] - }, - "responses": { - "$ref": "#/$defs/Responses" - }, - "callbacks": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/$defs/Callback" - }, - { - "$ref": "#/$defs/Reference" - } - ] - } - }, - "deprecated": { - "type": "boolean", - "default": false - }, - "security": { - "type": "array", - "items": { - "$ref": "#/$defs/SecurityRequirement" - } - }, - "servers": { - "type": "array", - "items": { - "$ref": "#/$defs/Server" - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "Responses": { - "type": "object", - "properties": { - "default": { - "oneOf": [ - { - "$ref": "#/$defs/Response" - }, - { - "$ref": "#/$defs/Reference" - } - ] - } - }, - "patternProperties": { - "^[1-5](?:\\d{2}|XX)$": { - "oneOf": [ - { - "$ref": "#/$defs/Response" - }, - { - "$ref": "#/$defs/Reference" - } - ] - }, - "^x-": { - } - }, - "minProperties": 1, - "additionalProperties": false - }, - "SecurityRequirement": { - "type": "object", - "additionalProperties": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "Tag": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "externalDocs": { - "$ref": "#/$defs/ExternalDocumentation" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "ExternalDocumentation": { - "type": "object", - "required": [ - "url" - ], - "properties": { - "description": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri-reference" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "ExampleXORExamples": { - "description": "Example and examples are mutually exclusive", - "not": { - "required": [ - "example", - "examples" - ] - } - }, - "SchemaXORContent": { - "description": "Schema and content are mutually exclusive, at least one is required", - "not": { - "required": [ - "schema", - "content" - ] - }, - "oneOf": [ - { - "required": [ - "schema" - ] - }, - { - "required": [ - "content" - ], - "description": "Some properties are not allowed if content is present", - "allOf": [ - { - "not": { - "required": [ - "style" - ] - } - }, - { - "not": { - "required": [ - "explode" - ] - } - }, - { - "not": { - "required": [ - "allowReserved" - ] - } - }, - { - "not": { - "required": [ - "example" - ] - } - }, - { - "not": { - "required": [ - "examples" - ] - } - } - ] - } - ] - }, - "Parameter": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "in": { - "type": "string" - }, - "description": { - "type": "string" - }, - "required": { - "type": "boolean", - "default": false - }, - "deprecated": { - "type": "boolean", - "default": false - }, - "allowEmptyValue": { - "type": "boolean", - "default": false - }, - "style": { - "type": "string" - }, - "explode": { - "type": "boolean" - }, - "allowReserved": { - "type": "boolean", - "default": false - }, - "schema": { - "oneOf": [ - { - "$ref": "#/$defs/Schema" - }, - { - "$ref": "#/$defs/Reference" - } - ] - }, - "content": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/MediaType" - }, - "minProperties": 1, - "maxProperties": 1 - }, - "example": { - }, - "examples": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/$defs/Example" - }, - { - "$ref": "#/$defs/Reference" - } - ] - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false, - "required": [ - "name", - "in" - ], - "allOf": [ - { - "$ref": "#/$defs/ExampleXORExamples" - }, - { - "$ref": "#/$defs/SchemaXORContent" - }, - { - "$ref": "#/$defs/ParameterLocation" - } - ] - }, - "ParameterLocation": { - "description": "Parameter location", - "oneOf": [ - { - "description": "Parameter in path", - "required": [ - "required" - ], - "properties": { - "in": { - "enum": [ - "path" - ] - }, - "style": { - "enum": [ - "matrix", - "label", - "simple" - ], - "default": "simple" - }, - "required": { - "enum": [ - true - ] - } - } - }, - { - "description": "Parameter in query", - "properties": { - "in": { - "enum": [ - "query" - ] - }, - "style": { - "enum": [ - "form", - "spaceDelimited", - "pipeDelimited", - "deepObject" - ], - "default": "form" - } - } - }, - { - "description": "Parameter in header", - "properties": { - "in": { - "enum": [ - "header" - ] - }, - "style": { - "enum": [ - "simple" - ], - "default": "simple" - } - } - }, - { - "description": "Parameter in cookie", - "properties": { - "in": { - "enum": [ - "cookie" - ] - }, - "style": { - "enum": [ - "form" - ], - "default": "form" - } - } - } - ] - }, - "RequestBody": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "description": { - "type": "string" - }, - "content": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/MediaType" - } - }, - "required": { - "type": "boolean", - "default": false - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "SecurityScheme": { - "oneOf": [ - { - "$ref": "#/$defs/APIKeySecurityScheme" - }, - { - "$ref": "#/$defs/HTTPSecurityScheme" - }, - { - "$ref": "#/$defs/OAuth2SecurityScheme" - }, - { - "$ref": "#/$defs/OpenIdConnectSecurityScheme" - } - ] - }, - "APIKeySecurityScheme": { - "type": "object", - "required": [ - "type", - "name", - "in" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "apiKey" - ] - }, - "name": { - "type": "string" - }, - "in": { - "type": "string", - "enum": [ - "header", - "query", - "cookie" - ] - }, - "description": { - "type": "string" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "HTTPSecurityScheme": { - "type": "object", - "required": [ - "scheme", - "type" - ], - "properties": { - "scheme": { - "type": "string" - }, - "bearerFormat": { - "type": "string" - }, - "description": { - "type": "string" - }, - "type": { - "type": "string", - "enum": [ - "http" - ] - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false, - "oneOf": [ - { - "description": "Bearer", - "properties": { - "scheme": { - "enum": [ - "bearer" - ] - } - } - }, - { - "description": "Non Bearer", - "not": { - "required": [ - "bearerFormat" - ] - }, - "properties": { - "scheme": { - "not": { - "enum": [ - "bearer" - ] - } - } - } - } - ] - }, - "OAuth2SecurityScheme": { - "type": "object", - "required": [ - "type", - "flows" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "oauth2" - ] - }, - "flows": { - "$ref": "#/$defs/OAuthFlows" - }, - "description": { - "type": "string" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "OpenIdConnectSecurityScheme": { - "type": "object", - "required": [ - "type", - "openIdConnectUrl" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "openIdConnect" - ] - }, - "openIdConnectUrl": { - "type": "string", - "format": "uri-reference" - }, - "description": { - "type": "string" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "OAuthFlows": { - "type": "object", - "properties": { - "implicit": { - "$ref": "#/$defs/ImplicitOAuthFlow" - }, - "password": { - "$ref": "#/$defs/PasswordOAuthFlow" - }, - "clientCredentials": { - "$ref": "#/$defs/ClientCredentialsFlow" - }, - "authorizationCode": { - "$ref": "#/$defs/AuthorizationCodeOAuthFlow" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "ImplicitOAuthFlow": { - "type": "object", - "required": [ - "authorizationUrl", - "scopes" - ], - "properties": { - "authorizationUrl": { - "type": "string", - "format": "uri-reference" - }, - "refreshUrl": { - "type": "string", - "format": "uri-reference" - }, - "scopes": { - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "PasswordOAuthFlow": { - "type": "object", - "required": [ - "tokenUrl" - ], - "properties": { - "tokenUrl": { - "type": "string", - "format": "uri-reference" - }, - "refreshUrl": { - "type": "string", - "format": "uri-reference" - }, - "scopes": { - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "ClientCredentialsFlow": { - "type": "object", - "required": [ - "tokenUrl" - ], - "properties": { - "tokenUrl": { - "type": "string", - "format": "uri-reference" - }, - "refreshUrl": { - "type": "string", - "format": "uri-reference" - }, - "scopes": { - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "AuthorizationCodeOAuthFlow": { - "type": "object", - "required": [ - "authorizationUrl", - "tokenUrl" - ], - "properties": { - "authorizationUrl": { - "type": "string", - "format": "uri-reference" - }, - "tokenUrl": { - "type": "string", - "format": "uri-reference" - }, - "refreshUrl": { - "type": "string", - "format": "uri-reference" - }, - "scopes": { - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false - }, - "Link": { - "type": "object", - "properties": { - "operationId": { - "type": "string" - }, - "operationRef": { - "type": "string", - "format": "uri-reference" - }, - "parameters": { - "type": "object", - "additionalProperties": { - } - }, - "requestBody": { - }, - "description": { - "type": "string" - }, - "server": { - "$ref": "#/$defs/Server" - } - }, - "patternProperties": { - "^x-": { - } - }, - "additionalProperties": false, - "not": { - "description": "Operation Id and Operation Ref are mutually exclusive", - "required": [ - "operationId", - "operationRef" - ] - } - }, - "Callback": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/PathItem" - }, - "patternProperties": { - "^x-": { - } - } - }, - "Encoding": { - "type": "object", - "properties": { - "contentType": { - "type": "string" - }, - "headers": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/Header" - } - }, - "style": { - "type": "string", - "enum": [ - "form", - "spaceDelimited", - "pipeDelimited", - "deepObject" - ] - }, - "explode": { - "type": "boolean" - }, - "allowReserved": { - "type": "boolean", - "default": false - } - }, - "additionalProperties": false - } - } -} diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json new file mode 100644 index 0000000000..4e257517e4 --- /dev/null +++ b/schemas/v3.1/schema.json @@ -0,0 +1,60 @@ +{ + "$schema": "http://json-schema.org/draft/2019-WIP/schema#", + "$id": "https://spec.openapis.org/oas/3.1/schema", + "$vocabulary": { + "https://json-schema.org/draft/2019-WIP/vocab/core": true, + "https://json-schema.org/draft/2019-WIP/vocab/applicator": true, + "https://json-schema.org/draft/2019-WIP/vocab/validation": true, + "https://json-schema.org/draft/2019-WIP/vocab/meta-data": true, + "https://json-schema.org/draft/2019-WIP/vocab/format": true, + "https://json-schema.org/draft/2019-WIP/vocab/content": true, + "https://specs.openapis.org/oas/3.1/vocab/openapi": true + }, + "$recursiveAnchor": true, + + "description": "OpenAPI Specification 3.1.X.", + "type": "object", + + "properties": { + "openapi": { + "type": "string", + "pattern": "^3\\.0\\.\\d(-.+)?$" + }, + "info": { + "$ref": "meta/oas#/$defs/Info" + }, + "externalDocs": { + "$ref": "meta/oas#/$defs/ExternalDocumentation" + }, + "servers": { + "type": "array", + "items": { + "$ref": "meta/oas#/$defs/Server" + } + }, + "security": { + "type": "array", + "items": { + "$ref": "meta/oas#/$defs/SecurityRequirement" + } + }, + "tags": { + "type": "array", + "items": { + "$ref": "meta/oas#/$defs/Tag" + }, + "uniqueItems": true + }, + "paths": { + "$ref": "meta/oas#/$defs/Paths" + }, + "components": { + "$ref": "meta/oas#/$defs/Components" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false +} diff --git a/versions/3.1.0.md b/versions/3.1.0.md index c4aca7efdd..a523b52ae8 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -61,7 +61,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp - [Specification Extensions](#specificationExtensions) - [Security Filtering](#securityFiltering) - [Appendix A: Revision History](#revisionHistory) - + @@ -91,7 +91,7 @@ Some examples of possible media type definitions: application/vnd.github.v3.patch ``` ##### HTTP Status Codes -The HTTP Status Codes are used to indicate the status of the executed operation. +The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). ## Specification @@ -122,7 +122,7 @@ This includes all fields that are used as keys in a map, except where explicitly The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. -Patterned fields MUST have unique names within the containing object. +Patterned fields MUST have unique names within the containing object. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: @@ -139,8 +139,8 @@ It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `op ### Data Types -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. +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 type (see [`nullable`](#schemaNullable) for an alternative solution). Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. @@ -169,7 +169,7 @@ The formats defined by the OAS are: ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. -Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](http://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. +Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](http://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. ### Relative References in URLs @@ -638,7 +638,7 @@ components: in: header petstore_auth: type: oauth2 - flows: + flows: implicit: authorizationUrl: http://example.org/api/oauth/dialog scopes: @@ -691,7 +691,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": { @@ -747,7 +747,7 @@ Field Name | Type | Description patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path. trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path. servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path. -parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). +parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -833,7 +833,7 @@ parameters: type: array style: simple items: - type: string + type: string ``` #### Operation Object @@ -885,7 +885,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "schema": { "type": "object", "properties": { - "name": { + "name": { "description": "Updated name of the pet", "type": "string" }, @@ -894,7 +894,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "type": "string" } }, - "required": ["status"] + "required": ["status"] } } } @@ -943,7 +943,7 @@ requestBody: 'application/x-www-form-urlencoded': schema: properties: - name: + name: description: Updated name of the pet type: string status: @@ -954,12 +954,12 @@ requestBody: responses: '200': description: Pet updated. - content: + content: 'application/json': {} 'application/xml': {} '405': description: Method Not Allowed - content: + content: 'application/json': {} 'application/xml': {} security: @@ -1047,11 +1047,11 @@ In order to support common ways of serializing simple parameters, a set of `styl `style` | [`type`](#dataTypes) | `in` | Comments ----------- | ------ | -------- | -------- -matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) +matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) form | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0. simple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0. -spaceDelimited | `array` | `query` | Space separated array values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0. +spaceDelimited | `array` | `query` | Space separated array values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0. pipeDelimited | `array` | `query` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0. deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. @@ -1267,9 +1267,9 @@ A request body with a referenced model definition. }, "examples": { "user" : { - "summary": "User Example", + "summary": "User Example", "externalValue": "http://foo.bar/examples/user-example.json" - } + } } }, "application/xml": { @@ -1287,9 +1287,9 @@ A request body with a referenced model definition. "examples": { "user" : { "summary": "User example in Plain text", - "externalValue": "http://foo.bar/examples/user-example.txt" + "externalValue": "http://foo.bar/examples/user-example.txt" } - } + } }, "*/*": { "examples": { @@ -1305,7 +1305,7 @@ A request body with a referenced model definition. ```yaml description: user to add to the system -content: +content: 'application/json': schema: $ref: '#/components/schemas/User' @@ -1327,7 +1327,7 @@ content: externalValue: 'http://foo.bar/examples/user-example.txt' '*/*': examples: - user: + user: summary: User example in other format externalValue: 'http://foo.bar/examples/user-example.whatever' ``` @@ -1385,7 +1385,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "examples": { "cat" : { "summary": "An example of a cat", - "value": + "value": { "name": "Fluffy", "petType": "Cat", @@ -1396,7 +1396,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens }, "dog": { "summary": "An example of a dog with a cat's name", - "value" : { + "value" : { "name": "Puma", "petType": "Dog", "color": "Black", @@ -1413,7 +1413,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ``` ```yaml -application/json: +application/json: schema: $ref: "#/components/schemas/Pet" examples: @@ -1484,7 +1484,7 @@ requestBody: 'image/png': schema: type: string - format: binary + format: binary ``` To upload multiple files, a `multipart` media type MUST be used: @@ -1637,10 +1637,10 @@ The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. -The `default` MAY be used as a default response object for all HTTP codes +The `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. -The `Responses Object` MUST contain at least one response code, and it +The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call. ##### Fixed Fields @@ -1688,7 +1688,7 @@ A 200 response for a successful operation and a default response for others (imp ```yaml '200': description: a pet to be returned - content: + content: application/json: schema: $ref: '#/components/schemas/Pet' @@ -1701,7 +1701,7 @@ default: ``` #### Response Object -Describes a single response from an API Operation, including design-time, static +Describes a single response from an API Operation, including design-time, static `links` to operations based on the response. ##### Fixed Fields @@ -1710,7 +1710,7 @@ Field Name | Type | Description description | `string` | **REQUIRED**. A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* -links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). +links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1736,9 +1736,9 @@ Response of an array of a complex type: ```yaml description: A complex object array response -content: +content: application/json: - schema: + schema: type: array items: $ref: '#/components/schemas/VeryComplexType' @@ -1855,7 +1855,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens The key that identifies the [Path Item Object](#pathItemObject) is a [runtime expression](#runtimeExpression) that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request. A simple example might be `$request.body#/url`. However, using a [runtime expression](#runtimeExpression) the complete HTTP message can be accessed. -This includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference. +This includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference. For example, given the following HTTP request: @@ -1871,7 +1871,7 @@ Content-Length: 187 "http://clientdomain.com/fast", "http://clientdomain.com/medium", "http://clientdomain.com/slow" - ] + ] } 201 Created @@ -1880,7 +1880,7 @@ Location: http://example.org/subscription/1 The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`. -Expression | Value +Expression | Value ---|:--- $url | http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning $method | POST @@ -1902,7 +1902,7 @@ myWebhook: post: requestBody: description: Callback payload - content: + content: 'application/json': schema: $ref: '#/components/schemas/SomePayload' @@ -1920,12 +1920,12 @@ Field Name | Type | Description summary | `string` | Short description for the example. description | `string` | Long description for the example. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. -externalValue | `string` | A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive. +externalValue | `string` | A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive. This object MAY be extended with [Specification Extensions](#specificationExtensions). -In all cases, the example value is expected to be compatible with the type schema -of its associated value. Tooling implementations MAY choose to +In all cases, the example value is expected to be compatible with the type schema +of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. ##### Example Object Examples @@ -1950,7 +1950,7 @@ requestBody: 'application/json': schema: $ref: '#/components/schemas/Address' - examples: + examples: foo: summary: A foo example value: {"foo": "bar"} @@ -1958,13 +1958,13 @@ requestBody: summary: A bar example value: {"bar": "baz"} 'application/xml': - examples: + examples: xmlExample: summary: This is an example in XML externalValue: 'http://example.org/examples/address-example.xml' 'text/plain': examples: - textExample: + textExample: summary: This is a text example externalValue: 'http://foo.bar/examples/address-example.txt' ``` @@ -1979,7 +1979,7 @@ parameters: type: 'string' format: 'zip-code' examples: - zip-example: + zip-example: $ref: '#/components/examples/zip-example' ``` @@ -1989,7 +1989,7 @@ In a response: responses: '200': description: your car appointment has been booked - content: + content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' @@ -2006,14 +2006,14 @@ The presence of a link does not guarantee the caller's ability to successfully i Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response. -For computing links, and providing instructions to execute them, a [runtime expression](#runtimeExpression) is used for accessing values in an operation and using them as parameters while invoking the linked operation. +For computing links, and providing instructions to execute them, a [runtime expression](#runtimeExpression) is used for accessing values in an operation and using them as parameters while invoking the linked operation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- operationRef | `string` | A relative or absolute reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operationObject). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OpenAPI definition. -operationId | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive of the `operationRef` field. +operationId | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive of the `operationRef` field. parameters | Map[`string`, Any \| [{expression}](#runtimeExpression)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path.id). requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation. description | `string` | A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. @@ -2023,7 +2023,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens A linked operation MUST be identified using either an `operationRef` or `operationId`. In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document. -Because of the potential for name clashes, the `operationRef` syntax is preferred +Because of the potential for name clashes, the `operationRef` syntax is preferred for specifications with external references. ##### Examples @@ -2037,7 +2037,7 @@ paths: - name: id in: path required: true - description: the user identifier, as userId + description: the user identifier, as userId schema: type: string get: @@ -2065,7 +2065,7 @@ paths: - name: userid in: path required: true - description: the user identifier, as userId + description: the user identifier, as userId schema: type: string # linked operation @@ -2089,14 +2089,14 @@ links: userUuid: $response.body#/uuid ``` -Clients follow all links at their discretion. -Neither permissions, nor the capability to make a successful call to that link, is guaranteed +Clients follow all links at their discretion. +Neither permissions, nor the capability to make a successful call to that link, is guaranteed solely by the existence of a relationship. ##### OperationRef Examples -As references to `operationId` MAY NOT be possible (the `operationId` is an optional +As references to `operationId` MAY NOT be possible (the `operationId` is an optional value), references MAY also be made through a relative `operationRef`: ```yaml @@ -2119,7 +2119,7 @@ links: username: $response.body#/username ``` -Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when +Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when using JSON references. @@ -2132,18 +2132,18 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org ``` expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source ) - source = ( header-reference | query-reference | path-reference | body-reference ) + source = ( header-reference | query-reference | path-reference | body-reference ) header-reference = "header." token - query-reference = "query." name + query-reference = "query." name path-reference = "path." name body-reference = "body" ["#" fragment] - fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) + fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) name = *( char ) char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7) token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6) ``` -The `name` identifier is case-sensitive, whereas `token` is not. +The `name` identifier is case-sensitive, whereas `token` is not. The table below provides examples of runtime expressions and examples of their use in a value: @@ -2152,10 +2152,10 @@ The table below provides examples of runtime expressions and examples of their u Source Location | example expression | notes ---|:---|:---| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. -Requested media type | `$request.header.accept` | +Requested media type | `$request.header.accept` | Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers. Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. -Request URL | `$url` | +Request URL | `$url` | Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. Response header | `$response.header.Server` | Single header values only are available @@ -2222,7 +2222,7 @@ description: Pets operations A simple object to allow referencing other components 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 accomplished as defined by the JSON Reference specification and not by the JSON Schema specification. @@ -2278,22 +2278,27 @@ Unless stated otherwise, the property definitions follow the JSON Schema. ##### Properties -OpenAPI v3.1 is a JSON Schema vocabulary which cetends JSON Schema Core and Validation vocabularies. As such any keyword available for those vocabularies is by definition available in OpenAPI, and will work the exact same way, including but not limited to: +OpenAPI v3.1 is a JSON Schema vocabulary which eetends JSON Schema Core and Validation vocabularies. As such any keyword available for those vocabularies is by definition available in OpenAPI, and will work the exact same way, including but not limited to: - title - type - required -- allOf / oneOf / andOf +- allOf +- oneOf +- andOf - multipleOf - maximum - exclusiveMaximum - minimum - exclusiveMinimum -- maxLength / minLength +- maxLength +- minLength - pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#sec-7.8.5) dialect) -- maxItems / minItems +- maxItems +- minItems - uniqueItems -- maxProperties / minProperties +- maxProperties +- minProperties - enum - propertyNames - contains @@ -2302,10 +2307,14 @@ OpenAPI v3.1 is a JSON Schema vocabulary which cetends JSON Schema Core and Vali - if / then / else - dependentRequired / dependentSchemas - deprecated -- additionalItems / additionalProperties -- unevaluatedItems / unevaluatedProperties -- max Contains / minContains -- readOnly / writeOnly +- additionalItems +- additionalProperties +- unevaluatedItems +- unevaluatedProperties +- maxContains +- minContains +- readOnly +- writeOnly The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. @@ -3251,7 +3260,7 @@ bearerFormat: JWT ```yaml type: oauth2 -flows: +flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: @@ -3266,8 +3275,8 @@ Allows configuration of the supported OAuth Flows. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow -password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow +implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow +password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. @@ -3314,7 +3323,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```yaml type: oauth2 -flows: +flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: @@ -3325,7 +3334,7 @@ flows: tokenUrl: https://example.com/api/oauth/token scopes: write:pets: modify pets in your account - read:pets: read your pets + read:pets: read your pets ``` @@ -3390,7 +3399,7 @@ The extensions may or may not be supported by the available tooling, but those m ### Security Filtering -Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation. +Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation. The reasoning is to allow an additional layer of access control over the documentation. While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization.