Each document in an OADMUST be fully parsed in order to locate possible reference targets.This includes the parsing requirements ofJSON Schema Specification Draft 2020-12, with appropriate modifications regarding base URIs as specified inRelative References In URIs.Reference targets are defined by fields including the OpenAPI Object’s$self field and theSchema Object’s$id,$anchor, and$dynamicAnchor keywords.

ImplementationsMUST NOT treat a reference as unresolvable before completely parsing all documents provided to the implementation as possible parts of the OAD.

If only the referenced part of the document is parsed when resolving a reference, the resulting behavior can be implementation-defined or undefined; seeWarnings Regarding Fragmentary Parsing inAppendix G for details.

URIs used as references within an OpenAPI Description, or to external documentation or other supplementary information such as a license, are resolved asidentifiers, and described by this specification asURIs, in contrast withAPI URLs.Note that some URI fields are namedurl for historical reasons, but the descriptive text for those fields uses the correct “URI” terminology.

As noted underParsing Documents, several fields can be used to associate an OpenAPI document or a Schema Object with a URI, which might not match the document’s or schema’s location.This allows the same references to be used in different deployment environments, including local filesystems or networks restricted by security policies or connectivity limitations.

Unless specified otherwise, all fields that are URIsMAY be relative references as defined by [RFC3986]Section 4.2.

Several features of this specification require resolution of non-URI-based connections to some other part of the OpenAPI Description (OAD).

These connections are unambiguously resolved in single-document OADs, but the resolution process in multi-document OADs isimplementation-defined, within the constraints described in this section.In some cases, an unambiguous URI-based alternative is available, and OAD authors areRECOMMENDED to use the alternative to maximize interoperability.

For resolvingComponents Object andTag Object names from a referenced (non-entry) document, it isRECOMMENDED that tools resolve from the entry document, rather than the current document.For resolving anOperation Object based on anoperationId, it isRECOMMENDED to consider all Operation Objects from all parsed documents.

Note that no aspect of implicit connection resolution changes howURIs are resolved, or restricts their possible targets.

SeeAppendix G: Parsing and Resolution Guidance for more details, including a list of Objects and fields using implicit connections.

Assume a retrieval URI ofhttps://device1.example.com for the following OpenAPI document:

openapi:3.2.0$self:https://apidescriptions.example.com/fooinfo:title:ExampleAPIversion:1.0servers:-url:.description:TheproductionAPIonthisdevice-url:./testdescription:ThetestAPIonthisdevice

For API URLs the$self field, which identifies the OpenAPI document, is ignored and the retrieval URI is used instead. This produces a normalized production URL ofhttps://device1.example.com, and a normalized test URL ofhttps://device1.example.com/test.

Assuming the following paths, the concrete definition,/pets/mine, will be matched first if used:

  /pets/{petId}  /pets/mine

The following paths are considered identical and invalid:

  /pets/{petId}  /pets/{name}

The following may lead to ambiguous resolution:

  /{entity}/me  /books/{id}

These fieldsMAY be used with eithercontent orschema.

Theexample andexamples fields are mutually exclusive; seeWorking with Examples for guidance on validation requirements.

This objectMAY be extended withSpecification Extensions.

Note that while"Cookie" as aname is not forbidden ifin is"header", the effect of defining a cookie parameter that way is undefined; usein: "cookie" instead.

For simpler scenarios, aschema andstyle can describe the structure and syntax of the parameter.

These fieldsMUST NOT be used within: "querystring".

Care is needed for parameters withschema that havein: "header" orin: "cookie", style: "cookie":

• When serializing these values, URI percent-encodingMUST NOT be applied.
• When parsing these parameters, any apparent percent-encodingMUST NOT be decoded.
• If using an RFC6570 implementation that automatically performs encoding or decoding steps, the stepsMUST be undone before use.

In these cases, implementationsMUST pass values through unchanged rather than attempting to quote or escape them, as the quoting rules for headers and escaping conventions for cookies vary too widely to be performed automatically; seeAppendix D for guidance on quoting and escaping.

See alsoAppendix C: Using RFC6570-Based Serialization for additional guidance.

For more complex scenarios, thecontent field can define the media type and schema of the parameter, as well as give examples of its use.

For use within: "querystring" andapplication/x-www-form-urlencoded, seeEncoding thex-www-form-urlencoded Media Type.

The OpenAPI Initiative maintains aMedia Type Registry summarizing media type support expected by this specification and providing an index to which sections address which media types.It also links to IANA registrations (where they exist) and to the most notable specification document(s) related to each media type.Any additional media types added to this registry as extensions or for later versions of this or other OpenAPI specificationsMAY be supported by implementations of this version of the OAS.

Within this specification, asequential media type is defined as any media type that consists of a repeating structure, without any sort of header, footer, envelope, or other metadata in addition to the sequence.

Some examples of sequential media types (including some that are not IANA-registered but are in common use) are:

  application/jsonl  application/x-ndjson  application/json-seq  application/geo+json-seq  text/event-stream  multipart/mixed

In the first three above, the repeating structure is anyJSON value.The fourth repeatsapplication/geo+json-structured values, whiletext/event-stream repeats a custom text format related to Server-Sent Events.The final media type listed above,multipart/mixed, provides an ordered list of documents of any media type, and is sometimes streamed.Note that whilemultipart formats technically allow a preamble and an epilogue, the RFC directs that they are to be ignored, making them effectively comments, and this specification does not model them.

ImplementationsMUST support mapping sequential media types into the JSON Schema data model by treating them as if the values were in an array in the same order.

SeeComplete vs Streaming Content for more information on handling sequential media types in a streaming context, including special considerations fortext/event-stream content.Formultipart types, see alsoEncoding By Position.

ThemaxLength keywordMAY be used to set an expected upper bound on the length of a streaming payload that consists of either string data, including encoded binary data, or unencoded binary data.For unencoded binary data, the length is the number of octets.For this use case,maxLengthMAY be implemented outside of regular JSON Schema evaluation as JSON Schema does not directly apply to binary data, and an encoded binary stream may be impractical to store in memory in its entirety.

The behavior of theencoding field is designed to support web forms, and is therefore only defined for media types structured as name-value pairs that allow repeat values, most notablyapplication/x-www-form-urlencoded andmultipart/form-data.

To use theencoding field, each key under the fieldMUST exist as a property;encoding entries with no corresponding propertySHALL be ignored.Array propertiesMUST be handled by applying the given Encoding Object to produce one encoded value per array item, each with the samename, as is recommended by [RFC7578]Section 4.3 for supplying multiple values per form field.For all other value types for both top-level non-array properties and for values, including array values, within a top-level array, the Encoding ObjectMUST be applied to the entire value.The order of these name-value pairs in the target media type is implementation-defined.

Forapplication/x-www-form-urlencoded, the encoding keysMUST map to parameter names, with the values produced according to the rules of theEncoding Object.SeeEncoding thex-www-form-urlencoded Media Type for guidance and examples, both with and without theencoding field.

Formultipart, the encoding keysMUST map to thename parameter of theContent-Disposition: form-data header of each part, as is defined formultipart/form-data in [RFC7578].See [RFC7578]Section 5 for guidance regarding non-ASCII part names.

SeeEncodingmultipart Media Types for further guidance and examples, both with and without theencoding field.

Mostmultipart media types, includingmultipart/mixed which defines the underlying rules for parsing allmultipart types, do not have named parts.Data for these media types are modeled as an array, with one item per part, in order.

To use theprefixEncoding and/oritemEncoding fields, eitheritemSchema or an arrayschemaMUST be present.These fields are analogous to theprefixItems anditems JSON Schema keywords, withprefixEncoding (if present) providing an array of Encoding Objects that are each applied to the value at the same position in the data array, anditemEncoding applying its single Encoding Object to all remaining items in the array.As withprefixItems, it isnot an error if the instance array is shorter than theprefixEncoding array; the additional Encoding ObjectsSHALL be ignored.

TheitemEncoding field can also be used withitemSchema to support streamingmultipart content.

TheprefixEncoding field can be used with anymultipart content to require a fixed part order.This includesmultipart/form-data, for which the Encoding Object’sheaders fieldMUST be used to provide theContent-Disposition and part name, as no property names exist to provide the names automatically.

Prior versions of this specification advised using thename parameter of theContent-Disposition: form-data header of each part withmultipart media types other thanmultipart/form-data in order to work around the limitations of theencoding field.ImplementationsMAY choose to support this workaround, but as this usage is not common, implementations of non-form-datamultipart media types are unlikely to support it.

Note that since this example is written in YAML, the Example Object’svalue field can be formatted as YAML due to the trivial conversion to JSON.This avoids needing to embed JSON as a string.

application/json:schema:$ref:'#/components/schemas/Pet'examples:cat:summary:Anexampleofacatvalue:name:FluffypetType:Catcolor:Whitegender:malebreed:Persiandog:summary:Anexampleofadogwithacat'snamevalue:name:PumapetType:Dogcolor:Blackgender:Femalebreed:Mixedfrog:$ref:'#/components/examples/frog-example'

Alternatively, since all JSON is valid YAML, the example value can use JSON syntax within a YAML document:

application/json:schema:$ref:'#/components/schemas/Pet'examples:cat:summary:Anexampleofacatvalue: {"name":"Fluffy","petType":"Cat","color":"White","gender":"male","breed":"Persian"      }dog:summary:Anexampleofadogwithacat'snamevalue: {"name":"Puma","petType":"Dog","color":"Black","gender":"Female","breed":"Mixed"      }frog:$ref:'#/components/examples/frog-example'

For anysequential media type where the items in the sequence are JSON values, no conversion of each value is required.JSON Text Sequences ([RFC7464]application/json-seq and [RFC8091] the+json-seq structured suffix),JSON Lines (application/jsonl), andNDJSON (application/x-ndjson) are all in this category.Note that the media types for JSON Lines and NDJSON are not registered with the IANA, but are in common use.

The following example shows Media Type Objects for both streaming log entries and returning a fixed-length set in response to a query.This shows the relationship betweenschema anditemSchema, and when to use each even though theexamples field is the same either way.

components:schemas:LogEntry:type:objectproperties:timestamp:type:stringformat:date-timelevel:type:integerminimum:0message:type:stringLog:type:arrayitems:$ref:"#/components/schemas/LogEntry"maxItems:100examples:LogJSONSeq:summary:Logentriesinapplication/json-seq# JSON Text Sequences require an unprintable character# that cannot be escaped in a YAML string, and therefore# must be placed in an external document shown belowexternalValue:examples/log.json-seqLogJSONPerLine:summary:Logentriesinapplication/jsonlorapplication/x-ndjsondescription:JSONLandNDJSONareidenticalforthisexample# Note that the value must be written as a string with newlines,# as JSONL and NDJSON are not valid YAMLvalue:|        {"timestamp": "1985-04-12T23:20:50.52Z", "level": 1, "message": "Hi!"}        {"timestamp": "1985-04-12T23:20:51.37Z", "level": 1, "message": "Bye!"}responses:LogStream:description:|        A stream of JSON-format log messages that can be read        for as long as the application is running, and is available        in any of the sequential JSON media types.content:application/json-seq:itemSchema:$ref:"#/components/schemas/LogEntry"examples:JSON-SEQ:$ref:"#/components/examples/LogJSONSeq"application/jsonl:itemSchema:$ref:"#/components/schemas/LogEntry"examples:JSONL:$ref:"#/components/examples/LogJSONPerLine"application/x-ndjson:itemSchema:$ref:"#/components/schemas/LogEntry"examples:NDJSON:$ref:"#/components/examples/LogJSONPerLine"LogExcerpt:description:|        A response consisting of no more than 100 log records,        generally as a result of a query of the historical log,        available in any of the sequential JSON media types.content:application/json-seq:schema:$ref:"#/components/schemas/Log"examples:JSON-SEQ:$ref:"#/components/examples/LogJSONSeq"application/jsonl:schema:$ref:"#/components/schemas/Log"examples:JSONL:$ref:"#/components/examples/LogJSONPerLine"application/x-ndjson:schema:$ref:"#/components/schemas/Log"examples:NDJSON:$ref:"#/components/examples/LogJSONPerLine"

Ourapplication/json-seq example has to be an external document because of the use of both newlines and of the unprintable Record Separator (0x1E) character, which cannot be escaped in YAML block literals:

0x1E{"timestamp":"1985-04-12T23:20:50.52Z","level":1,"message":"Hi!"}0x1E{"timestamp":"1985-04-12T23:20:51.37Z","level":1,"message":"Bye!"}

For this example, assume that the generic event schema provided in theSpecial Considerations for Server-Sent Events section is available at#/components/schemas/Event:

description:Arequestbodytoaddastreamoftypeddata.required:truecontent:text/event-stream:itemSchema:$ref:"#/components/schemas/Event"required: [event]oneOf:-properties:event:const:addString-properties:event:const:addInt64data:$comment:|              Since the `data` field is a string,              we need a format to signal that it              should be handled as a 64-bit integer.format:int64-properties:event:const:addJsondata:$comment:|              These content fields indicate              that the string value should              be parsed and validated as a              JSON document (since JSON is not              a binary format, `contentEncoding`              is not needed)contentMediaType:application/jsoncontentSchema:type:objectrequired: [foo]properties:foo:type:integer

The followingtext/event-stream document is an example of a valid request body for the above example:

event: addStringdata: This data is formatteddata: across two linesretry: 5event: addInt64data: 1234.5678unknownField: this is ignored: This is a commentevent: addJSONdata: {"foo": 42}

To more clearly see how this stream is handled, the following is the equivalent JSON Lines document, which shows how the numeric and JSON data are handled as strings, and how unknown fields and comments are ignored and not passed to schema validation:

{"event":"addString","data":"This data is formatted\nacross two lines","retry":5}{"event":"addInt64","data":"1234.5678"}{"event":"addJSON","data":"{\"foo\": 42}"}

These fieldsMAY be used either with or without the RFC6570-style serialization fields defined in the next section below.

This objectMAY be extended withSpecification Extensions.

The default values forcontentType are as follows, where ann/a in thecontentEncoding column means that the presence or value ofcontentEncoding is irrelevant.This table is based on the value to which the Encoding Object is being applied as defined underEncoding Usage and Restrictions.Note that in the case ofEncoding By Name, this value is the array item for properties of type"array", and the entire value for all other types.Therefore thearray row in this table applies only to array values inside of a top-level array when encoding by name.

Determining how to handle atype value ofnull depends on hownull values are being serialized.Ifnull values are entirely omitted, then thecontentType is irrelevant.SeeAppendix B for a discussion of data type conversion options.

When using RFC6570-style serialization formultipart/form-data, URI percent-encodingMUST NOT be applied, and the value ofallowReserved has no effect.See alsoAppendix C: Using RFC6570 Implementations for additional guidance.

Note that the presence of at least one ofstyle,explode, orallowReserved with an explicit value is equivalent to usingschema within: "query" Parameter Objects.The absence of all three of those fields is the equivalent of usingcontent, but with the media type specified incontentType rather than through a Media Type Object.

When there is noencoding field, the serialization strategy is based on the Encoding Object’s default values:

requestBody:content:application/x-www-form-urlencoded:schema:type:objectproperties:id:type:stringformat:uuidaddress:type:objectproperties: {}

With this example, consider anid off81d4fae-7dec-11d0-a765-00a0c91e6bf6 and a US-style address (with ZIP+4) as follows:

{"streetAddress":"123 Example Dr.","city":"Somewhere","state":"CA","zip":"99999+1234"}

Assuming the most compact representation of the JSON value (with unnecessary whitespace removed), we would expect to see the following request body, where space characters have been replaced with+ and+,",:,,,{, and} have been percent-encoded to%2B,%22,%3A,%2C,%7B, and%7D, respectively:

id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6&address=%7B%22streetAddress%22%3A%22123+Example+Dr.%22%2C%22city%22%3A%22Somewhere%22%2C%22state%22%3A%22CA%22%2C%22zip%22%3A%2299999%2B1234%22%7D

Note that theid keyword is treated astext/plain per theEncoding Object’s default behavior, and is serialized as-is.If it were treated asapplication/json, then the serialized value would be a JSON string including quotation marks, which would be percent-encoded as%22.

Here is theid parameter (withoutaddress) serialized asapplication/json instead oftext/plain, and then encoded per [WHATWG-URL]'sform-urlencoded rules:

id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22

Note thatapplication/x-www-form-urlencoded is a text format, which requires base64-encoding any binary data:

requestBody:content:application/x-www-form-urlencoded:schema:type:objectproperties:name:type:stringicon:# The default content type with `contentEncoding` present# is `application/octet-stream`, so we need to set the correct# image media type(s) in the Encoding Object.type:stringcontentEncoding:base64urlencoding:icon:contentType:image/png,image/jpeg

Given a name ofexample and a solid red 2x2-pixel PNG foricon, thiswould produce a request body of:

name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAADO0J6QAAAAEElEQVQIHWP8zwACTGCSAQANHQEDqtPptQAAAABJRU5ErkJggg%3D%3D

Note that the= padding characters at the end need to be percent-encoded, even with the “URL safe”contentEncoding: base64url.Some base64-decoding implementations may be able to use the string without the padding per [RFC4648]Section 3.2.However, this is not guaranteed, so it may be more interoperable to keep the padding and rely on percent-decoding.

When multiple values are provided forcontentType, parsing remains straightforward as the part’s actualContent-Type is included in the document.

For encoding and serialization, implementationsMUST provide a mechanism for applications to indicate which media type is intended.ImplementationsMAY choose to offer media type sniffing ([SNIFF]) as an alternative, but thisMUST NOT be the default behavior due to the security risks inherent in the process.

UsingcontentEncoding for a multipart field is equivalent to specifying anEncoding Object with aheaders field containingContent-Transfer-Encoding with a schema that requires the value used incontentEncoding.IfcontentEncoding is used for a multipart field that has an Encoding Object with aheaders field containingContent-Transfer-Encoding with a schema that disallows the value fromcontentEncoding, the result is undefined for serialization and parsing.

Note that as stated inWorking with Binary Data, if the Encoding Object’scontentType, whether set explicitly or implicitly through its default value rules, disagrees with thecontentMediaType in a Schema Object, thecontentMediaTypeSHALL be ignored.Because of this, and because the Encoding Object’scontentType defaulting rules do not take the Schema Object’scontentMediaType into account, the use ofcontentMediaType with an Encoding Object isNOT RECOMMENDED.

Note also thatContent-Transfer-Encoding is deprecated formultipart/form-data ([RFC7578]Section 4.7) where binary data is supported, as it is in HTTP.

SeeAppendix E for a detailed examination of percent-encoding concerns for form media types.

When theencoding field isnot used, the encoding is determined by the Encoding Object’s defaults:

requestBody:content:multipart/form-data:schema:type:objectproperties:# default content type for a string without `contentEncoding`# is `text/plain`id:type:stringformat:uuid# default content type for a schema without `type`# is `application/octet-stream`profileImage: {}# for arrays, the `encoding` field applies the Encoding Object# to each item individually and determines the default content type# based on the type in the `items` subschema, which in this example# is an object, so the default content type for each item is# `application/json`addresses:type:arrayitems:$ref:'#/components/schemas/Address'

Usingencoding, we can set more specific types for binary data, or non-JSON formats for complex values.We can also describe headers for each part:

requestBody:content:multipart/form-data:schema:type:objectproperties:# No Encoding Object, so use default `text/plain`id:type:stringformat:uuid# Encoding Object overrides the default `application/json` content type# for each item in the array with `application/xml; charset=utf-8`addresses:description:addressesinXMLformattype:arrayitems:$ref:'#/components/schemas/Address'# Encoding Object accepts only PNG or JPEG, and also describes# a custom header for just this part in the multipart formatprofileImage: {}encoding:addresses:contentType:application/xml;charset=utf-8profileImage:contentType:image/png,image/jpegheaders:X-Rate-Limit-Limit:description:Thenumberofallowedrequestsinthecurrentperiodschema:type:integer

In accordance with [RFC7578]Section 4.3, multiple files for a single form field are uploaded using the same name (file in this example) for each file’s part:

requestBody:content:multipart/form-data:schema:properties:# The property name `file` will be used for all files.file:type:arrayitems: {}

As seen in theEncoding Object’scontentType field documentation, the empty schema foritems indicates a media type ofapplication/octet-stream.

Amultipart/mixed payload consisting of a JSON metadata document followed by an image which the metadata describes:

multipart/mixed:schema:type:arrayprefixItems:-# default content type for objects# is `application/json`type:objectproperties:author:type:stringcreated:type:stringformat:datetimecopyright:type:stringlicense:type:string-# default content type for a schema without `type`# is `application/octet-stream`, which we need# to override.      {}prefixEncoding:-# Encoding Object defaults are correct for JSON    {}-contentType:image/*

As described in [RFC2557], a set of resources making up a web page can be sent in amultipart/related payload, preserving links from thetext/html document to subsidiary resources such as scripts, style sheets, and images by defining aContent-Location header for each page.The first part is used as the root resource (unless usingContent-ID, which RFC2557 advises against and is forbidden in this example), so we useprefixItems andprefixEncoding to define that it must be an HTML resource, and then allow any of several different types of resources in any order to follow.

TheContent-Location header is defined usingcontent: {text/plain: {...}} to avoid percent-encoding its URI value; seeAppendix D for further details.

components:headers:RFC2557NoContentId:description:UseContent-LocationinsteadofContent-IDschema:falseRFC2557ContentLocation:required:truecontent:text/plain:schema:$comment:UseafullURI(notarelativereference)type:stringformat:urirequestBodies:RFC2557:content:multipart/related;type=text/html:schema:prefixItems:-type:stringitems:anyOf:-type:string-$comment:Toallowbinary,thismustalwayspassprefixEncoding:-contentType:text/htmlheaders:Content-ID:$ref:'#/components/headers/RFC2557NoContentId'Content-Location:$ref:'#/components/headers/RFC2557ContentLocation'itemEncoding:contentType:text/css,text/javascript,image/*headers:Content-ID:$ref:'#/components/headers/RFC2557NoContentId'Content-Location:$ref:'#/components/headers/RFC2557ContentLocation'

This example assumes a device that takes large sets of pictures and streams them to the caller.Unlike the previous example, we useitemSchema here because the expectation is that each image is processed as it arrives (or in small batches), since we know that buffering the entire stream will take too much memory.

multipart/mixed:itemSchema:$comment:AsingledataimagefromthedeviceitemEncoding:contentType:image/jpg

Formultipart/byteranges [RFC9110]Section 14.6, aContent-Range header is required:

SeeAppendix D for an explanation of whycontent: {text/plain: {...}} is used to describe the header value.

multipart/byteranges:itemSchema:$comment:AsinglerangeofbytesfromavideoitemEncoding:contentType:video/mp4headers:Content-Range:required:truecontent:text/plain:schema:# The `pattern` regular expression that would# be included in practice is omitted for simplicitytype:string

This defines a two-partmultipart/mixed where the first part is a JSON array and the second part is a nestedmultipart/mixed document.The nested parts are XML, plain text, and a PNG image.

multipart/mixed:schema:type:arrayprefixItems:-type:array-type:arrayprefixItems:-type:object-type:string- {}prefixEncoding:- {}# Accept the default application/json-contentType:multipart/mixedprefixEncoding:-contentType:application/xml- {}# Accept the default text/plain-contentType:image/png

Thevalue and the shorthandexample field are intended to have the samesemantics asserializedValue (orexternalValue), while allowing a more convenientsyntax when there is no difference between a JSON (orJSON-compatible YAML) representation and the final serialized form.When using this syntax forapplication/json or any+json media type, these fields effectively behave likedataValue, as the serialization is trivial, and they are safe to use.

For data that consists of a single string, and a serialization target such astext/plain where the string is guaranteed to be serialized without any further escaping, these fields are also safe to use.

For other serialization targets, the ambiguity of the phrase “naturally be represented in JSON or YAML,” as well as past errors in the parameter style examples table, have resulted in inconsistencies in the support and usage of these fields.In practice, this has resulted in thevalue and shorthandexample fields having implementation-defined behavior for non-JSON targets; OAD authorsSHOULD use other fields to ensure interoperability.

Keeping in mind the caveats from the previous section, and that the shorthandexample can be used in place ofvalue if there is only one Example Object involved, use the following guidelines to determine which field to use.

To show an example as it would be validated by a Schema Object:

• Use the Schema Object’sexamples array (from JSON Schema draft 2020-12) if the intent is to keep the example with the validating schema.
  • Use the Schema Object’sexample (singular) only if compatibility with OAS v3.0 or earlier is required.
• Use the Example Object’sdataValue field if the intent is to associate the example with an example of its serialization, or if it is desirable to maintain it separately from the schema.
  • Use the Example Object’svalue field only if compatibility with OAS v3.1 or earlier is needed and the value can be “naturally represented in JSON or YAML” without any changes (such as percent-encoding) between the validation-ready value and the serialized representation.

To show an example as it would be serialized in order to construct an HTTP/1.1 message:

• Use the Example Object’sserializedValue if the serialization can be represented as a valid Unicode string, and there is no need to demonstrate the exact character encoding to be used.
  • Use the string form ofvalue only if compatibility with OAS v3.1 or earlier is needed.
• Use the Example Object’sexternalValue for all other values, or if it is desirable to maintain the example separately from the OpenAPI document.

TheserializedValue andexternalValue fields bothMUST show the serialized form of the data.For Media Type Objects, this is a document of the appropriate media type, with any Encoding Object effects applied.For Parameter and Header Objects usingschema andstyle rather than a Media Type Object, seeStyle Examples for what constitutes a serialized value.

A serialization can be represented as a valid Unicode string inserializedValue if any of the following are true of the serialization:

• It is for a media type that supports acharset parameter that indicates any Unicode encoding (UTF-8, UTF-16, etc.), or any valid subset of such an encoding, such as US-ASCII.
• It is for a format (such as URIs or HTTP fields) or character-based media type that requires or defaults to a Unicode encoding, or any valid subset of such an encoding, such as US-ASCII, and this is not overridden bycharset.
• It is for a compound format where all parts meet at least one of the above criteria, e.g. amultipart/mixed media type with parts that areapplication/json (a media type that defaults to UTF-8) andapplication/xml; charset=utf-8 (a media type with an explicitcharset parameter).

In all of these cases, the conversion from the character set of the OAD (presumed to be UTF-8 as the only interoperable character set for JSON, and therefore also for JSON-compatible YAML as noted in [RFC9512]Section 3.4) first to Unicode code points and then to the actual serialization character set is well-defined.

ForexternalValue, if the character set is neither explicitly stated nor determined by the format or media type specification, implementationsSHOULD assume UTF-8.

Tooling implementationsMAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.For examples that are in schema-ready data form, this is straightforward.

With serialized examples, some formats allow multiple possible valid representations of the same data, including in scenarios noted inAppendix B.In some cases, parsing the serialized example and validating the resulting data can eliminate the ambiguity, but in a few cases parsing is also ambiguous.Therefore, OAD authors are cautioned that validation of certain serialized examples is by necessity a best-effort feature.

When writing in YAML, JSON syntax can be used fordataValue (as shown in thenoRating example) but is not required.While this example shows the behavior of bothdataValue andserializedValue for JSON (in the 'withRating` example), in most cases only the data form is needed.

content:application/json:schema:type:objectrequired:-author-titleproperties:author:type:stringtitle:type:stringrating:type:numberminimum:1maximum:5multipleOf:0.5examples:noRating:summary:Anot-yet-ratedworkdataValue:author:A.Writertitle:TheNewestBookwithRating:summary:Aworkwithanaverageratingof4.5starsdataValue:author:A.Writertitle:AnOlderBookrating:4.5serializedValue:|          {            "author": "A. Writer",            "title": "An Older Book",            "rating": 4.5          }

Fully binary data is shown usingexternalValue:

content:image/png:schema: {}examples:Red:externalValue:./examples/2-by-2-red-pixels.png

Since there is no standard for serializing boolean values (as discussed inAppendix B), this example usesdataValue andserializedValue to show how booleans are serialized for this particular parameter:

name:flagin:queryrequired:trueschema:type:booleanexamples:"true":dataValue:trueserializedValue:flag=true"false":dataValue:falseserializedValue:flag=false

As theoperationId is an optional field in anOperation Object, referencesMAY instead be made through a URI reference withoperationRef.Note that both of these examples reference operations that can be identified via thePaths Object to ensure that the operation’s path template is unambiguous.

A relative URI referenceoperationRef:

links:UserRepositories:# returns array of '#/components/schemas/repository'operationRef:'#/paths/~12.0~1repositories~1%7Busername%7D/get'parameters:username:$response.body#/username

A non-relative URIoperationRef:

links:UserRepositories:# returns array of '#/components/schemas/repository'operationRef:https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1%7Busername%7D/getparameters:username:$response.body#/username

Note that in the use ofoperationRef theescaped forward-slash (~1) is necessary whenusing JSON Pointer in URI fragments, and it is necessary to URL-encode{ and} as%7B and%7D, respectively.The unescaped, percent-decoded path template in the above examples would be/2.0/repositories/{username}.

Runtime expressions preserve the type of the referenced value.Expressions can be embedded into string values by surrounding the expression with{} curly braces.

These fieldsMAY be used with eithercontent orschema.

Theexample andexamples fields are mutually exclusive; seeWorking with Examples for guidance on validation requirements.

This objectMAY be extended withSpecification Extensions.

For simpler scenarios, aschema andstyle can describe the structure and syntax of the header.

When serializing headers withschema, URI percent-encodingMUST NOT be applied; if using an RFC6570 implementation that automatically applies it, itMUST be removed before use.ImplementationsMUST pass header values through unchanged rather than attempting to automatically quote header values, as the quoting rules vary too widely among different headers; seeAppendix D for guidance on quoting and escaping.

See alsoAppendix C: Using RFC6570-Based Serialization for additional guidance.

For more complex scenarios, thecontent field can define the media type and schema of the header, as well as give examples of its use.

As defined by theJSON Schema Validation specification, data types can have an optional modifier keyword:format. As described in that specification,format is treated as a non-validating annotation by default; the ability to validateformat varies across implementations.

The OpenAPI Initiative also hosts aFormat Registry for formats defined by OAS users and other specifications. Support for any registered format is strictlyOPTIONAL, and support for one registered format does not imply support for any others.

Types that are not accompanied by aformat keyword follow the type definition in the JSON Schema. Tools that do not recognize a specificformatMAY default back to thetype alone, as if theformat is not specified.For the purpose ofJSON Schema validation, each format should specify the set of JSON data types for which it applies. In this registry, these types are shown in the “JSON Data Type” column.

The formats defined by the OAS are:

As noted underData Type, bothtype: number andtype: integer are considered to be numbers in the data model.

JSON-serialized data is nearly equivalent to the data form because theJSON Schema data model is nearly equivalent to the JSON representation.The serialized UTF-8 JSON string{"when": "1985-04-12T23:20:50.52"} represents an object with one data field, namedwhen, with a string value,1985-04-12T23:20:50.52.

The exact application form is beyond the scope of this specification, as can be shown with the following schema for our JSON instance:

type:objectproperties:when:type:stringformat:date-time

Some applications might leave the string as a string regardless of programming language, while others might notice theformat and use it as adatetime.datetime instance in Python, or ajava.time.ZonedDateTime in Java.This specification only requires that the data is valid according to the schema, and thatannotations such asformat are available in accordance with the JSON Schema specification.

Non-JSON serializations can be substantially different from their corresponding data form, and might require several steps to parse.

To continue our “when” example, if we serialized the object asapplication/x-www-form-urlencoded, it would appear as the ASCII stringwhen=1985-04-12T23%3A20%3A50.52.This example is still straightforward to use as it is all string data, and the only differences from JSON are the URI percent-encoding and the delimiter syntax (= instead of JSON punctuation and quoting).

However, many non-JSON text-based formats can be complex, requiring examination of the appropriate schema(s) in order to correctly parse the text into a schema-ready data structure.Serializing data into such formats requires either examining the schema-validated data or performing the same schema inspections.

When inspecting schemas, given a starting point schema, implementationsMUST examine that schema and all schemas that can be reached from it by following only$ref andallOf keywords.These schemas are guaranteed to apply to any instance.When searching schemas fortype, if thetype keyword’s value is a list of types and the serialized value can be successfully parsed as more than one of the types in the list, and no other findabletype keyword disambiguates the actual required type, the behavior is implementation-defined.Schema Objects that do not containtypeMUST be considered to allow all types, regardless of which other keywords are present (e.g.maximum applies to numbers, butdoes not require the instance to be a number).

ImplementationsMAY inspect subschemas or possible reference targets of other keywords such asoneOf or$dynamicRef, butMUST NOT attempt to resolve ambiguities.For example, if an implementation opts to inspectanyOf, the schema:

anyOf:-type:numberminimum:0-type:numbermaximum:100

unambiguously indicates a numeric type, but the schema:

anyOf:-type:number-maximum:100

does not, because the second subschema allows all types.

Due to these limited requirements for searching schemas, serializers that have access to validated dataMUST inspect the data if possible; implementations that either do not work with runtime data (such as code generators) or cannot access validated data for some reasonMUST fall back to schema inspection.

Recall also that in JSON Schema, keywords that apply to a specific type (e.g.pattern applies to strings,minimum applies to numbers)do not require or imply that the data will actually be of that type.

As an example of these processes, given these OpenAPI components:

components:requestBodies:Form:content:application/x-www-form-urlencoded:schema:$ref:"#/components/schemas/FormData"encoding:extra:contentType:application/xmlschemas:FormData:type:objectproperties:code:allOf:-type: [string,number]pattern:"1"minimum:0-type:stringpattern:"2"count:type:integerextra:type:object

And this request body to parse into its data form:

code=1234&count=42&extra=%3Cinfo%3Eabc%3C/info%3E

We must first search the schema forproperties or other property-defining keywords, and then use each property schema as a starting point for a search for that property’stype keyword, as follows (the exact order is implementation-defined):

• #/components/requestBodies/Form/content/application~1x-www-form-urlencoded/schema (initial starting point schema, only$ref)
• #/components/schemas/FormData (follow$ref, foundproperties)
• #/components/schemas/FormData/properties/code (starting point schema forcode property)
• #/components/schemas/FormData/properties/code/allOf/0 (followallOf, foundtype: [string, number])
• #/components/schemas/FormData/properties/code/allOf/1 (followallOf, foundtype: string)
• #/components/schemas/FormData/properties/count (starting point schema forcount property, foundtype: integer)
• #/components/schemas/FormData/properties/extra (starting point schema forextra property, foundtype: object)

Note that forcode we first found an ambiguoustype, but then found anothertype keyword that ensures only one of the two possibilities is valid.

From this inspection, we determine thatcode is a string that happens to look like a number, whilecount needs to be parsed into a numberprior to schema validation.Furthermore, theextra string is in fact an XML serialization of an object containing aninfo property.This means that the data form of this serialization is equivalent to the following JSON object:

{"code":"1234","count":42"extra":{"info":"abc"}}

Serializing this object also requires correlating properties withEncoding Objects, and may require inspection to determine a default value of thecontentType field.If validated data is not available, the schema inspection process is identical to that shown for parsing.

In this example, bothcode andcount are of primitive type and do not appear in theencoding field, and are therefore serialized as plain text.However, theextra field is an object, which would by default be serialized as JSON, but theextra entry in theencoding field tells use to serialize it as XML instead.

The OAS can describe eitherraw orencoded binary data.

• raw binary is used where unencoded binary data is allowed, such as when sending a binary payload as the entire HTTP message body, or as part of amultipart/* payload that allows binary parts
• encoded binary is used where binary data is embedded in a text-only format such asapplication/json orapplication/x-www-form-urlencoded (either as a message body or in the URL query string).

In the following table showing how to use Schema Object keywords for binary data, we useimage/png as an example binary media type. Any binary media type, includingapplication/octet-stream, is sufficient to indicate binary content.

Note that the encoding indicated bycontentEncoding, which inflates the size of data in order to represent it as 7-bit ASCII text, is unrelated to HTTP’sContent-Encoding header, which indicates whether and how a message body has been compressed and is applied after all content serialization described in this section has occurred. Since HTTP allows unencoded binary message bodies, there is no standardized HTTP header for indicating base64 or similar encoding of an entire message body.

Using acontentEncoding ofbase64url ensures that URL encoding (as required in the query string and in message bodies of typeapplication/x-www-form-urlencoded) does not need to further encode any part of the already-encoded binary data.

ThecontentMediaType keyword is redundant if the media type is already set:

• as the key for aMedia Type Object
• in thecontentType field of anEncoding Object

If theSchema Object will be processed by a non-OAS-aware JSON Schema implementation, it may be useful to includecontentMediaType even if it is redundant. However, ifcontentMediaType contradicts a relevant Media Type Object or Encoding Object, thencontentMediaTypeSHALL be ignored.

SeeComplete vs Streaming Content for guidance on streaming binary payloads.

Theformat keyword (when using default format-annotation vocabulary) and thecontentMediaType,contentEncoding, andcontentSchema keywords define constraints on the data, but are treated as annotations instead of being validated directly.Extended validation is one way that these constraintsMAY be enforced.

ThereadOnly andwriteOnly keywords are annotations, as JSON Schema is not aware of how the data it is validating is being used.Validation of these keywordsMAY be done by checking the annotation, the read or write direction, and (if relevant) the current value of the field.JSON Schema Validation Draft 2020-12 Section 9.4 defines the expectations of these keywords, including that a resource (described as the “owning authority”)MAY either ignore areadOnly field or treat it as an error.

Fields that are both required and read-only are an example of when it is beneficial to ignore areadOnly: true constraint in a PUT, particularly if the value has not been changed.This allows correctly requiring the field on a GET and still using the same representation and schema with PUT.Even when read-only fields are not required, stripping them is burdensome for clients, particularly when the JSON data is complex or deeply nested.

Note that the behavior ofreadOnly in particular differs from that specified by version 3.0 of this specification.

The OpenAPI Specification allows combining and extending model definitions using theallOf keyword of JSON Schema, in effect offering model composition.allOf takes an array of object definitions that are validatedindependently but together compose a single object.

While composition offers model extensibility, it does not imply a hierarchy between the models.

JSON Schema also provides theanyOf andoneOf keywords, which allow defining multiple schemas where at least one or exactly one of them must be valid, respectively.As is the case withallOf, the schemas are validatedindependently.These keywords can be used to describe polymorphism, where a single field can accept multiple types of values.

The OpenAPI specification extends the JSON Schema support for polymorphism by adding thediscriminator field whose value is aDiscriminator Object.When used, the Discriminator Object indicates the name of the property that hints which schema of ananyOf oroneOf is expected to validate the structure of the model.The discriminating propertyMAY be defined as required or optional, but when defined as an optional property the Discriminator ObjectMUST include adefaultMapping field that specifies which schema of theanyOf oroneOf, or which schema that references the current schema in anallOf, is expected to validate the structure of the model when the discriminating property is not present.

There are two ways to define the value of a discriminating property for an inheriting instance.

• Use the schema name.
• Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.

ImplementationsSHOULD support defining generic or template data structures using JSON Schema’s dynamic referencing feature:

• $dynamicAnchor identifies a set of possible schemas (including a default placeholder schema) to which a$dynamicRef can resolve
• $dynamicRef resolves to the first matching$dynamicAnchor encountered on its path from the schema entry point to the reference, as described in the JSON Schema specification

An example is included in theSchema Object Examples section below, and further information can be found on the Learn OpenAPI site’s“Dynamic References” page.

The Schema Object’senum keyword does not allow associating descriptions or other information with individual values.

ImplementationsMAY support recognizing aoneOf oranyOf where each subschema in the keyword’s array consists of aconst keyword and annotations such astitle ordescription as an enumerated type with additional information. The exact behavior of this pattern beyond what is required by JSON Schema is implementation-defined.

Thexml field allows extra definitions when translating the JSON definition to XML.TheXML Object contains additional information about the available options.

type:stringformat:email

type:objectrequired:-nameproperties:name:type:stringaddress:$ref:'#/components/schemas/Address'age:type:integerformat:int32minimum:0

For a simple string to string mapping:

type:objectadditionalProperties:type:string

For a string to model mapping:

type:objectadditionalProperties:$ref:'#/components/schemas/ComplexModel'

oneOf:-const:RGBtitle:Red,Green,Bluedescription:Specifycolorswiththered,green,andblueadditivecolormodel-const:CMYKtitle:Cyan,Magenta,Yellow,Blackdescription:Specifycolorswiththecyan,magenta,yellow,andblacksubtractivecolormodel

type:objectproperties:id:type:integerformat:int64name:type:stringrequired:-nameexamples:-name:Pumaid:1

components:schemas:ErrorModel:type:objectrequired:-message-codeproperties:message:type:stringcode:type:integerminimum:100maximum:600ExtendedErrorModel:allOf:-$ref:'#/components/schemas/ErrorModel'-type:objectrequired:-rootCauseproperties:rootCause:type:string

The following example describes aPet model that can represent either a cat or a dog, as distinguished by thepetType property. Each type of pet has other properties beyond those of the basePet model. An instance without apetType property, or with apetType property that does not match eithercat ordog, is invalid.

components:schemas:Pet:type:objectproperties:name:type:stringrequired:-name-petTypeoneOf:-$ref:'#/components/schemas/Cat'-$ref:'#/components/schemas/Dog'Cat:description:Apetcattype:objectproperties:petType:const:'cat'huntingSkill:type:stringdescription:Themeasuredskillforhuntingenum:-clueless-lazy-adventurous-aggressiverequired:-huntingSkillDog:description:Apetdogtype:objectproperties:petType:const:'dog'packSize:type:integerformat:int32description:thesizeofthepackthedogisfromdefault:0minimum:0required:-packSize

The following example extends the example of the previous section by adding aDiscriminator Object to thePet schema. Note that the Discriminator Object is only a hint to the consumer of the API and does not change the validation outcome of the schema.

components:schemas:Pet:type:objectdiscriminator:propertyName:petTypemapping:cat:'#/components/schemas/Cat'dog:'#/components/schemas/Dog'properties:name:type:stringrequired:-name-petTypeoneOf:-$ref:'#/components/schemas/Cat'-$ref:'#/components/schemas/Dog'Cat:description:Apetcattype:objectproperties:petType:const:'cat'huntingSkill:type:stringdescription:Themeasuredskillforhuntingenum:-clueless-lazy-adventurous-aggressiverequired:-huntingSkillDog:description:Apetdogtype:objectproperties:petType:const:'dog'packSize:type:integerformat:int32description:thesizeofthepackthedogisfromdefault:0minimum:0required:-petType-packSize

It is also possible to describe polymorphic models usingallOf. The following example usesallOf with aDiscriminator Object to describe a polymorphicPet model.

components:schemas:Pet:type:objectdiscriminator:propertyName:petTypeproperties:name:type:stringpetType:type:stringrequired:-name-petTypeCat:# "Cat" will be used as the discriminating valuedescription:ArepresentationofacatallOf:-$ref:'#/components/schemas/Pet'-type:objectproperties:huntingSkill:type:stringdescription:Themeasuredskillforhuntingenum:-clueless-lazy-adventurous-aggressiverequired:-huntingSkillDog:# "Dog" will be used as the discriminating valuedescription:ArepresentationofadogallOf:-$ref:'#/components/schemas/Pet'-type:objectproperties:packSize:type:integerformat:int32description:thesizeofthepackthedogisfromdefault:0minimum:0required:-packSize

components:schemas:genericArrayComponent:$id:fully_generic_arraytype:arrayitems:$dynamicRef:'#generic-array'$defs:allowAll:$dynamicAnchor:generic-arraynumberArray:$id:array_of_numbers$ref:fully_generic_array$defs:numbersOnly:$dynamicAnchor:generic-arraytype:numberstringArray:$id:array_of_strings$ref:fully_generic_array$defs:stringsOnly:$dynamicAnchor:generic-arraytype:stringobjWithTypedArray:$id:obj_with_typed_arraytype:objectrequired:-dataType-dataproperties:dataType:enum:-string-numberoneOf:-properties:dataType:const:stringdata:$ref:array_of_strings-properties:dataType:const:numberdata:$ref:array_of_numbers