Attribute Reference #

This page is generated automatically from the swagger-php sources.

For improvements head over to GitHub and create a PR 😉

In addition to this page, there are also a number of examples which might help you out.

Attributes #

AdditionalProperties #

Allowed in #

Schema, Property, Items, JsonContent, XmlContent, AdditionalProperties

Nested elements #

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Parameters #

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : string|null

The key into Components->schemas array.

Required:

no

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

Required:

no

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

Required:

no

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

Required:

no

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

Required:

no

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

Required:

no

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

Required:

no

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

Required:

no

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

Required:

no

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

Required:

no

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

Required:

no

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

Required:	no
See:	JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

Required:	no
See:	JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

Required:	no
See:	JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

Required:	no
See:	JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

Required:

no

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

Required:	no
See:	JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

Required:

no

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the 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.

Required:

no

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the 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.

Required:

no

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

Required:

no

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

Required:

no

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

Required:

no

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

Required:

no

allOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

Required:

no

anyOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

Required:

no

oneOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

Required:

no

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Attachable #

Allowed in #

AdditionalProperties, Components, Contact, Delete, Discriminator, Examples, ExternalDocumentation, Flow, Get, Head, Header, Info, Items, JsonContent, License, Link, MediaType, OpenApi, Operation, Options, Parameter, Patch, PathItem, PathParameter, Post, Property, Put, RequestBody, Response, Schema, SecurityScheme, Server, ServerVariable, Tag, Trace, Webhook, Xml, XmlContent

Parameters #

properties : array

No details available.

Required:

no

Components #

Allowed in #

OpenApi

Nested elements #

Response, Parameter, PathParameter, RequestBody, Examples, Header, SecurityScheme, Link, Schema, Attachable

Parameters #

schemas : array<Schema|OA\Schema>|null

Reusable Schemas.

Required:

no

responses : Response[]|null

Reusable Responses.

Required:

no

parameters : Parameter[]|null

Reusable Parameters.

Required:

no

requestBodies : RequestBody[]|null

Reusable Request Bodies.

Required:

no

examples : array<Examples>|null

Reusable Examples.

Required:

no

headers : Header[]|null

Reusable Headers.

Required:

no

securitySchemes : SecurityScheme[]|null

Reusable Security Schemes.

Required:

no

links : Link[]|null

Reusable Links.

Required:

no

callbacks : array|null

Reusable Callbacks.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Contact #

Allowed in #

Info

Nested elements #

Attachable

Parameters #

name : string|null

The identifying name of the contact person/organization.

Required:

no

url : string|null

The URL pointing to the contact information.

Required:

no

email : string|null

The email address of the contact person/organization.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

CookieParameter #

Allowed in #

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements #

Schema, Examples, Attachable

Parameters #

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

Required:

no

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

Required:

yes

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

Required:

no

in : string|null

This takes 'cookie' as the default location.

Required:

yes

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

Required:

no

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

Required:

no

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

Required:

no

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

Required:

no

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

Required:

no

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

Required:

no

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

Required:

no

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

Required:

no

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

Required:

no

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

Required:

no

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

Required:

no

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Delete #

Allowed in #

PathItem

Nested elements #

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters #

path : string|null

Key in the OpenApi "Paths Object" for this operation.

Required:

no

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

Required:

no

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

Required:

no

summary : string|null

A short summary of what the operation does.

Required:

no

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

Required:

no

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

Required:

no

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

Required:

no

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

Required:

no

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

Required:

no

responses : Response[]

The list of possible responses as they are returned from executing this operation.

Required:

yes

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

Required:

no

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Discriminator #

Allowed in #

Schema, Property, AdditionalProperties, Items, JsonContent, XmlContent

Nested elements #

Attachable

Parameters #

propertyName : string|null

The name of the property in the payload that will hold the discriminator value.

Required:

yes

mapping : string[]|null

An object to hold mappings between payload values and schema names or references.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Examples #

Allowed in #

Components, Schema, Parameter, PathParameter, MediaType, JsonContent, XmlContent

Nested elements #

Attachable

Parameters #

example : string|null

The key into `#/components/examples`.

Required:

no

summary : string|null

Short description for the example.

Required:

yes

description : string|null

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

Required:

no

value : array|string|int|null

Embedded literal example.

The value field and externalValue field are mutually exclusive.

To represent examples of media types that cannot naturally be represented
in JSON or YAML, use a string value to contain the example, escaping where necessary.

Required:

no

externalValue : string|null

An 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.

Required:

no

ref : string|class-string|object|null

The relative or absolute path to an example.

Required:	no
See:	Using refs

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

ExternalDocumentation #

Allowed in #

OpenApi, Tag, Schema, AdditionalProperties, Property, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace, Items, JsonContent, XmlContent

Nested elements #

Attachable

Parameters #

description : string|null

A short description of the target documentation. GFM syntax can be used for rich text representation.

Required:

no

url : string|null

The URL for the target documentation.

Required:

yes

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Flow #

Allowed in #

SecurityScheme

Nested elements #

Attachable

Parameters #

authorizationUrl : string|null

The authorization url to be used for this flow.

This must be in the form of an url.

Required:

no

tokenUrl : string|null

The token URL to be used for this flow.

This must be in the form of an url.

Required:

no

refreshUrl : string|null

The URL to be used for obtaining refresh tokens.

This must be in the form of an url.

Required:

no

flow : string|null

Flow name.

One of ['implicit', 'password', 'authorizationCode', 'clientCredentials'].

Required:

yes

scopes : array|null

The available scopes for the OAuth2 security scheme.

A map between the scope name and a short description for it.

Required:

yes

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Get #

Allowed in #

PathItem

Nested elements #

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters #

path : string|null

Key in the OpenApi "Paths Object" for this operation.

Required:

no

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

Required:

no

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

Required:

no

summary : string|null

A short summary of what the operation does.

Required:

no

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

Required:

no

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

Required:

no

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

Required:

no

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

Required:

no

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

Required:

no

responses : Response[]

The list of possible responses as they are returned from executing this operation.

Required:

yes

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

Required:

no

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Head #

Allowed in #

PathItem

Nested elements #

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters #

path : string|null

Key in the OpenApi "Paths Object" for this operation.

Required:

no

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

Required:

no

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

Required:

no

summary : string|null

A short summary of what the operation does.

Required:

no

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

Required:

no

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

Required:

no

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

Required:

no

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

Required:

no

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

Required:

no

responses : Response[]

The list of possible responses as they are returned from executing this operation.

Required:

yes

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

Required:

no

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Header #

Allowed in #

Components, Response

Nested elements #

Schema, Attachable

Parameters #

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

header : string|null

No details available.

Required:

yes

description : string|null

A brief description of the parameter.

This could contain examples of use.
CommonMark syntax MAY be used for rich text representation.

Required:

no

required : bool|null

No details available.

Required:

no

schema : OpenApi\Attributes\Schema|null

Schema object.

Required:

yes

deprecated : bool|null

Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.

Required:

no

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

HeaderParameter #

Allowed in #

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements #

Schema, Examples, Attachable

Parameters #

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

Required:

no

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

Required:

yes

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

Required:

no

in : string|null

This takes 'header' as the default location.

Required:

yes

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

Required:

no

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

Required:

no

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

Required:

no

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

Required:

no

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

Required:

no

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

Required:

no

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

Required:

no

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

Required:

no

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

Required:

no

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

Required:

no

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

Required:

no

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Info #

Allowed in #

OpenApi

Nested elements #

Contact, License, Attachable

Parameters #

version : string|null

The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

Required:

yes

description : string|null

A short description of the application.

CommonMark syntax may be used for rich text representation.

Required:

no

title : string|null

The title of the application.

Required:

yes

termsOfService : string|null

An URL to the Terms of Service for the API.

Must be in the format of an url.

Required:

no

contact : OpenApi\Attributes\Contact|null

The contact information for the exposed API.

Required:

no

license : OpenApi\Attributes\License|null

The license information for the exposed API.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Items #

Allowed in #

Property, AdditionalProperties, Schema, JsonContent, XmlContent, Items

Nested elements #

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Parameters #

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : string|null

The key into Components->schemas array.

Required:

no

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

Required:

no

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

Required:

no

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

Required:

no

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

Required:

no

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

Required:

no

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

Required:

no

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

Required:

no

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

Required:

no

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

Required:

no

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

Required:

no

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

Required:	no
See:	JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

Required:	no
See:	JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

Required:	no
See:	JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

Required:	no
See:	JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

Required:

no

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

Required:	no
See:	JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

Required:

no

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the 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.

Required:

no

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the 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.

Required:

no

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

Required:

no

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

Required:

no

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

Required:

no

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

Required:

no

allOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

Required:

no

anyOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

Required:

no

oneOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

Required:

no

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

JsonContent #

Nested elements #

Discriminator, Items, Property, ExternalDocumentation, AdditionalProperties, Examples, Attachable

Parameters #

examples : array<Examples>

Examples of the schema.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

Required:

no

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : string|null

The key into Components->schemas array.

Required:

no

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

Required:

no

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

Required:

no

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

Required:

no

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

Required:

no

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

Required:

no

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

Required:

no

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

Required:

no

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

Required:

no

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

Required:

no

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

Required:

no

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

Required:	no
See:	JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

Required:	no
See:	JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

Required:	no
See:	JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

Required:	no
See:	JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

Required:

no

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

Required:	no
See:	JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

Required:

no

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the 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.

Required:

no

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the 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.

Required:

no

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

Required:

no

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

Required:

no

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

Required:

no

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

Required:

no

allOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

Required:

no

anyOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

Required:

no

oneOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

Required:

no

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

License #

Allowed in #

Info

Nested elements #

Attachable

Parameters #

name : string|null

The license name used for the API.

Required:

yes

identifier : string|null

An SPDX license expression for the API. The `identifier` field is mutually exclusive of the `url` field.

Required:

no

url : string|null

An URL to the license used for the API. This MUST be in the form of a URL.

The `url` field is mutually exclusive of the `identifier` field.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Link #

Allowed in #

Components, Response

Nested elements #

Server, Attachable

Parameters #

link : string|null

The key into MediaType->links array.

Required:

no

operationRef : string|null

A relative or absolute reference to an OA operation.

This field is mutually exclusive of the operationId field, and must point to an Operation object.

Relative values may be used to locate an existing Operation object in the OpenAPI definition.

Required:

no

ref : string|class-string|object|null

No details available.

Required:	no
See:	Using refs

operationId : string|null

The name of an existing, resolvable OA operation, as defined with a unique operationId.

This field is mutually exclusive of the operationRef field.

Required:

no

parameters : array<string,mixed>

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 [{in}.]{name} for operations
that use the same parameter name in different locations (e.g. path.id).

Required:

no

requestBody : mixed|null

A literal value or {expression} to use as a request body when calling the target operation.

Required:

no

description : string|null

A description of the link.

CommonMark syntax may be used for rich text representation.

Required:

no

server : OpenApi\Attributes\Server|null

A server object to be used by the target operation.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

MediaType #

Allowed in #

Response, RequestBody

Nested elements #

Schema, Examples, Attachable

Parameters #

mediaType : string|null

The key into Operation->content array.

Required:

no

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the request body.

Required:

no

example : mixed|null

Example of the media type.

The example object should be in the correct format as specified by the media type.
The example object is mutually exclusive of the examples object.

Furthermore, if referencing a schema which contains an example,
the example value shall override the example provided by the schema.

Required:

no

examples : array<Examples>

Examples of the media type.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

Required:

no

encoding : array<string,mixed>

A map between a property name and its encoding information.

The key, being the property name, must exist in the schema as a property.

The encoding object shall only apply to requestBody objects when the media type is multipart or
application/x-www-form-urlencoded.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

OpenApi #

Nested elements #

Info, Server, PathItem, Components, Tag, ExternalDocumentation, Webhook, Attachable

Parameters #

openapi : string

The semantic version number of the OpenAPI Specification version that the OpenAPI document uses.

The openapi field should be used by tooling specifications and clients to interpret the OpenAPI document.

A version specified via `Generator::setVersion()` will overwrite this value.

This is not related to the API info::version string.

Required:

yes

info : OpenApi\Attributes\Info|null

Provides metadata about the API. The metadata may be used by tooling as required.

Required:

yes

servers : Server[]|null

An array of @Server objects, which provide connectivity information to a target server.

If not provided, or is an empty array, the default value would be a Server Object with an url value of /.

Required:

no

security : array|null

A declaration of which security mechanisms can be used across the API.

The list of values includes alternative security requirement objects that can be used.
Only one of the security requirement objects need to be satisfied to authorize a request.
Individual operations can override this definition.
To make security optional, an empty security requirement `({})` can be included in the array.

Required:

no

tags : Tag[]|null

A list of tags used by the specification with additional metadata.

The order of the tags can be used to reflect on their order by the parsing tools.
Not all tags that are used by the Operation Object must be declared.
The tags that are not declared may be organized randomly or based on the tools' logic.
Each tag name in the list must be unique.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation.

Required:

no

paths : PathItem[]|null

The available paths and operations for the API.

Required:

no

components : OpenApi\Attributes\Components|null

An element to hold various components for the specification.

Required:

no

webhooks : Webhook[]|null

The available webhooks for the API.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Options #

Allowed in #

PathItem

Nested elements #

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters #

path : string|null

Key in the OpenApi "Paths Object" for this operation.

Required:

no

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

Required:

no

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

Required:

no

summary : string|null

A short summary of what the operation does.

Required:

no

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

Required:

no

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

Required:

no

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

Required:

no

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

Required:

no

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

Required:

no

responses : Response[]

The list of possible responses as they are returned from executing this operation.

Required:

yes

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

Required:

no

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Parameter #

Allowed in #

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements #

Schema, Examples, Attachable

Parameters #

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

Required:

no

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

Required:

yes

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

Required:

no

in : string|null

The location of the parameter.

Possible values are "query", "header", "path" or "cookie".

Required:

yes

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

Required:

no

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

Required:

no

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

Required:

no

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

Required:

no

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

Required:

no

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

Required:

no

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

Required:

no

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

Required:

no

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

Required:

no

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

Required:

no

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

Required:

no

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Patch #

Allowed in #

PathItem

Nested elements #

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters #

path : string|null

Key in the OpenApi "Paths Object" for this operation.

Required:

no

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

Required:

no

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

Required:

no

summary : string|null

A short summary of what the operation does.

Required:

no

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

Required:

no

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

Required:

no

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

Required:

no

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

Required:

no

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

Required:

no

responses : Response[]

The list of possible responses as they are returned from executing this operation.

Required:

yes

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

Required:

no

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

PathItem #

Allowed in #

OpenApi

Nested elements #

Get, Post, Put, Delete, Patch, Trace, Head, Options, Parameter, PathParameter, Server, Attachable

Parameters #

path : string|null

Key for the Path Object (OpenApi->paths array).

Required:

no

ref : string|class-string|object|null

No details available.

Required:	no
See:	Using refs

summary : string|null

An optional, string summary, intended to apply to all operations in this path.

Required:

no

description : string|null

An optional, string description, intended to apply to all operations in this path.

Required:

no

get : OpenApi\Attributes\Get|null

A definition of a GET operation on this path.

Required:

no

put : OpenApi\Attributes\Put|null

A definition of a PUT operation on this path.

Required:

no

post : OpenApi\Attributes\Post|null

A definition of a POST operation on this path.

Required:

no

delete : OpenApi\Attributes\Delete|null

A definition of a DELETE operation on this path.

Required:

no

options : OpenApi\Attributes\Options|null

A definition of a OPTIONS operation on this path.

Required:

no

head : OpenApi\Attributes\Head|null

A definition of a HEAD operation on this path.

Required:

no

patch : OpenApi\Attributes\Patch|null

A definition of a PATCH operation on this path.

Required:

no

trace : OpenApi\Attributes\Trace|null

A definition of a TRACE operation on this path.

Required:

no

servers : Server[]|null

An alternative server array to service all operations in this path.

Required:

no

parameters : Parameter[]|null

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 and location.
The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

PathParameter #

Allowed in #

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements #

Schema, Examples, Attachable

Parameters #

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

Required:

no

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

Required:

yes

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

Required:

no

in : string|null

This takes 'path' as the default location.

Required:

no

required : bool|null

No details available.

Required:

no

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

Required:

no

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

Required:

no

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

Required:

no

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

Required:

no

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

Required:

no

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

Required:

no

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

Required:

no

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

Required:

no

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

Required:

no

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

Required:

no

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Post #

Allowed in #

PathItem

Nested elements #

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters #

path : string|null

Key in the OpenApi "Paths Object" for this operation.

Required:

no

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

Required:

no

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

Required:

no

summary : string|null

A short summary of what the operation does.

Required:

no

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

Required:

no

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

Required:

no

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

Required:

no

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

Required:

no

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

Required:

no

responses : Response[]

The list of possible responses as they are returned from executing this operation.

Required:

yes

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

Required:

no

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Property #

Allowed in #

AdditionalProperties, Schema, JsonContent, XmlContent, Property, Items

Nested elements #

Discriminator, Items, Property, ExternalDocumentation, Xml, AdditionalProperties, Attachable

Parameters #

property : string|null

The key into Schema->properties array.

Required:

no

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : string|null

The key into Components->schemas array.

Required:

no

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

Required:

no

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

Required:

no

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

Required:

no

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

Required:

no

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

Required:

no

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

Required:

no

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

Required:

no

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

Required:

no

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

Required:

no

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

Required:

no

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

Required:	no
See:	JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

Required:	no
See:	JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

Required:	no
See:	JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

Required:	no
See:	JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

Required:

no

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

Required:	no
See:	JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

Required:

no

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the 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.

Required:

no

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the 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.

Required:

no

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

Required:

no

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

Required:

no

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

Required:

no

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

Required:

no

allOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

Required:

no

anyOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

Required:

no

oneOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

Required:

no

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Put #

Allowed in #

PathItem

Nested elements #

Parameter, PathParameter, Response, ExternalDocumentation, Server, RequestBody, Attachable

Parameters #

path : string|null

Key in the OpenApi "Paths Object" for this operation.

Required:

no

operationId : string|null

Unique string used to identify the operation.

The id must be unique among all operations described in the API.
Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
follow common programming naming conventions.

Required:

no

description : string|null

A verbose explanation of the operation behavior.

CommonMark syntax MAY be used for rich text representation.

Required:

no

summary : string|null

A short summary of what the operation does.

Required:

no

security : array|null

A declaration of which security mechanisms can be used for this operation.

The list of values includes alternative security requirement objects that can be used.

Only one of the security requirement objects need to be satisfied to authorize a request.

This definition overrides any declared top-level security.
To remove a top-level security declaration, an empty array can be used.

Required:

no

servers : Server[]

An alternative server array to service this operation.

If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
this value.

Required:

no

requestBody : OpenApi\Attributes\RequestBody|null

The request body applicable for this operation.

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
by consumers.

Required:

no

tags : string[]

A list of tags for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.

Required:

no

parameters : Parameter[]

A list of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
The list must not include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
components/parameters.

Required:

no

responses : Response[]

The list of possible responses as they are returned from executing this operation.

Required:

yes

callbacks : array|null

A map of possible out-of band callbacks related to the parent operation.

The key is a unique identifier for the Callback Object.

Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
and the expected responses. The key value used to identify the callback object is an expression, evaluated at
runtime, that identifies a URL to use for the callback operation.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this operation.

Required:

no

deprecated : bool|null

Declares this operation to be deprecated.

Consumers should refrain from usage of the declared operation.

Default value is false.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

QueryParameter #

Allowed in #

Components, PathItem, Operation, Get, Post, Put, Delete, Patch, Head, Options, Trace

Nested elements #

Schema, Examples, Attachable

Parameters #

parameter : string|null

The key into Components::parameters or PathItem::parameters array.

Required:

no

name : string|null

The (case-sensitive) name of the parameter.

If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
For all other cases, the name corresponds to the parameter name used by the in property.

Required:

yes

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

Required:

no

in : string|null

This takes 'query' as the default location.

Required:

yes

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

Required:

no

deprecated : bool|null

Specifies that a parameter is deprecated and should be transitioned out of usage.

Required:

no

allowEmptyValue : bool|null

Sets the ability to pass empty-valued parameters.

This is valid only for query parameters and allows sending a parameter with an empty value.

Default value is false.

If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

Required:

no

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : OpenApi\Attributes\Schema|null

The schema defining the type used for the parameter.

Required:

no

example : mixed|null

Example of the media type.

The example should match the specified schema and encoding properties if present.
The example object is mutually exclusive of the examples object.
Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

Required:

no

examples : array<Examples>

Examples of the parameter.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

Required:

no

content : array<MediaType>|JsonContent|XmlContent|Attachable|null

A map containing the representations for the parameter.

The key is the media type and the value describes it.
The map must only contain one entry.

Required:

no

style : string|null

Describes how the parameter value will be serialized depending on the type of the parameter value.

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

Required:

no

explode : bool|null

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.

For other types of parameters this property has no effect.

When style is form, the default value is true.
For all other styles, the default value is false.

Required:

no

allowReserved : bool|null

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.

This property only applies to parameters with an in value of query.

The default value is false.

Required:

no

spaceDelimited : array|null

Space separated array values.

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

Required:

no

pipeDelimited : array|null

Pipe separated array values.

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

RequestBody #

Allowed in #

Components, Delete, Get, Head, Operation, Options, Patch, Post, Trace, Put

Nested elements #

MediaType, Attachable

Parameters #

ref : string|class-string|object|null

The relative or absolute path to a request body.

Required:	no
See:	Using refs

request : string|null

The key into Components->requestBodies array.

Required:

no

description : string|null

A brief description of the parameter.

This could contain examples of use.

CommonMark syntax may be used for rich text representation.

Required:

no

required : bool|null

Determines whether this parameter is mandatory.

If the parameter location is "path", this property is required and its value must be true.
Otherwise, the property may be included and its default value is false.

Required:

no

content : array<MediaType|JsonContent|XmlContent>|MediaType|XmlContent|Attachable|null

The content of the request body.

The key is a media type or media type range and the value describes it. For requests that match multiple keys,
only the most specific key is applicable. e.g. text/plain overrides text/*.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Response #

Allowed in #

Components, Operation, Get, Post, Put, Patch, Delete, Head, Options, Trace

Nested elements #

MediaType, Header, Link, Attachable

Parameters #

ref : string|class-string|object|null

The relative or absolute path to a response.

Required:	no
See:	Using refs

response : string|int|null

The key into Operations->responses array.

A HTTP status code or default.

Required:

no

description : string|null

A short description of the response.

CommonMark syntax may be used for rich text representation.

Required:

no

headers : Header[]

Maps a header name to its definition.

RFC7230 states header names are case insensitive.

If a response header is defined with the name "Content-Type", it shall be ignored.

Required:	no
See:	RFC7230

content : MediaType|JsonContent|XmlContent|Attachable|array<MediaType|Attachable>

A map containing descriptions of potential response payloads.

The key is a media type or media type range and the value describes it.

For responses that match multiple keys, only the most specific key is applicable;
e.g. text/plain overrides text/*.

Required:

no

links : Link[]

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.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no

Schema #

Allowed in #

Components, Parameter, PathParameter, MediaType, Header

Nested elements #

Discriminator, Items, Property, ExternalDocumentation, Examples, Xml, AdditionalProperties, Attachable

Parameters #

ref : string|class-string|object|null

The relative or absolute path to the endpoint.

Required:	no
See:	Using refs

schema : string|null

The key into Components->schemas array.

Required:

no

title : string|null

Can be used to decorate a user interface with information about the data produced by this user interface.

Preferably short; use description for more details.

Required:

no

description : string|null

A description will provide explanation about the purpose of the instance described by this schema.

Required:

no

maxProperties : int|null

The maximum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is less than, or equal to, the
value of this attribute.

Required:

no

minProperties : int|null

The minimum number of properties allowed in an object instance.
An object instance is valid against this property if its number of properties is greater than, or equal to, the
value of this attribute.

Required:

no

required : string[]

An object instance is valid against this property if its property set contains all elements in this property's
array value.

Required:

no

properties : Property[]

A collection of properties to define for an object.

Each property is represented as an instance of the Property class.

Required:

no

type : string|non-empty-array<string>|null

The type of the schema/property.

OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

Since OpenApi v3.1 an array of types may be used.

Required:

no

format : string|null

The extending format for the previously mentioned type. See Data Type Formats for further details.

Required:

no

items : OpenApi\Attributes\Items|null

Required if type is "array". Describes the type of items in the array.

Required:

no

collectionFormat : string|null

Determines the format of the array if type array is used.

Possible values are:
- csv: comma separated values foo,bar.
- ssv: space separated values foo bar.
- tsv: tab separated values foo\tbar.
- pipes: pipe separated values foo|bar.
- multi: corresponds to multiple parameter instances instead of multiple values for a single instance
foo=bar&foo=baz. This is valid only for parameters of type query or formData. Default
value is csv.

Required:

no

default : mixed|null

Sets a default value to the parameter. The type of the value depends on the defined type.

Required:	no
See:	JSON schema validation

maximum : int|float

The maximum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMaximum : int|float|bool|null

A boolean indicating whether the maximum value is excluded from the set of valid values.

When set to true, the maximum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

minimum : int|float

The minimum value allowed for a numeric property. This value must be a number.

Required:	no
See:	JSON schema validation

exclusiveMinimum : int|float|bool|null

A boolean indicating whether the minimum value is excluded from the set of valid values.

When set to true, the minimum value is excluded, and when false or not specified, it is included.

Required:	no
See:	JSON schema validation

maxLength : int|null

The maximum length of a string property.

A string instance is valid against this property if its length is less than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

minLength : int|null

The minimum length of a string property.

A string instance is valid against this property if its length is greater than, or equal to, the value of this
attribute.

Required:	no
See:	JSON schema validation

maxItems : int|null

The maximum number of items allowed in an array property.

An array instance is valid against this property if its number of items is less than, or equal to, the value of
this attribute.

Required:	no
See:	JSON schema validation

minItems : int|null

The minimum number of items allowed in an array property.

An array instance is valid against this property if its number of items is greater than, or equal to, the value
of this attribute.

Required:	no
See:	JSON schema validation

uniqueItems : bool|null

A boolean value indicating whether all items in an array property must be unique.

If this attribute is set to true, then all items in the array must be unique.

Required:	no
See:	JSON schema validation

pattern : string|null

A string instance is considered valid if the regular expression matches the instance successfully.

Required:

no

enum : array<string|int|float|bool|\UnitEnum|null>|class-string|null

A collection of allowable values for a property.

A property instance is valid against this attribute if its value is one of the values specified in this
collection.

Required:	no
See:	JSON schema validation

discriminator : OpenApi\Attributes\Discriminator|null

Adds support for polymorphism.

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
payload description. See Composition and Inheritance for more details.

Required:

no

readOnly : bool|null

Declares the property as "read only".

Relevant only for Schema "properties" definitions.

This means that it may be sent as part of a response but should not be sent as part of the request.
If the 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.

Required:

no

writeOnly : bool|null

Declares the property as "write only".

Relevant only for Schema "properties" definitions.
Therefore, it may be sent as part of a request but should not be sent as part of the response.
If the 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.

Required:

no

xml : OpenApi\Attributes\Xml|null

This may be used only on properties schemas.

It has no effect on root schemas.
Adds additional metadata to describe the XML representation of this property.

Required:

no

externalDocs : OpenApi\Attributes\ExternalDocumentation|null

Additional external documentation for this schema.

Required:

no

example : mixed|null

A free-form property to include an example of an instance for this schema.

To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
contain the example with escaping where necessary.

Required:

no

examples : array<Examples>

Examples of the schema.

Each example should contain a value in the correct format as specified in the parameter encoding.
The examples object is mutually exclusive of the example object.
Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

Required:

no

nullable : bool|null

Allows sending a null value for the defined schema.
Default value is false.

This must not be used when using OpenApi version 3.1,
instead make the "type" property an array and add "null" as a possible type.

Required:

no

deprecated : bool|null

Specifies that a schema is deprecated and should be transitioned out of usage.
Default value is false.

Required:

no

allOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against all schemas
defined by this property's value.

Required:

no

anyOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against at least one
schema defined by this property's value.

Required:

no

oneOf : array<Schema|OA\Schema>

An instance validates successfully against this property if it validates successfully against exactly one schema
defined by this property's value.

Required:

no

additionalProperties : OpenApi\Attributes\AdditionalProperties|bool|null

http://json-schema.org/latest/json-schema-validation.html#anchor64.

Required:

no

const : mixed|null

http://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.3.

Required:

no

x : array<string,mixed>|null

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
For further details see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions
The keys inside the array will be prefixed with `x-`.

Required:

no

attachables : Attachable[]|null

Arbitrary attachables for this annotation.
These will be ignored but can be used for custom processing.

Required:

no