OpenAPI Specification

https://github.com/oai/openapi-specification
Admin
The OpenAPI Specification (OAS) is a standard, programming language-agnostic interface description...
Tokens:118,068
Snippets:859
Trust Score:-
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### YAML Example for application/json with Named Examples

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows how to define multiple examples for the 'application/json' media type using YAML syntax. The 'value' field can be formatted as YAML due to trivial conversion to JSON, avoiding the need to embed JSON as a string. Includes examples for 'cat', 'dog', and a reference to an external example.

```yaml
application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: '#/components/examples/frog-example'
```

--------------------------------

### Paths Object example with /pets

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Example of a Paths Object defining a GET operation for /pets. Shows the structure with responses and schema reference.

```yaml
/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'
```

--------------------------------

### Targeted Overlays Example

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2019-12-24-Overlays.md

A YAML example showing targeted overlays for applying a small number of updates to a large document.

```yaml
overlay: 1.0.0
info:
  title: Targeted Overlays
  version: 1.0.0
updates:
- target: paths."/foo".get
  merge:
    description: This is the new description
- target: paths."/bar".get
  merge:
    description: This is the updated description
- target: paths."/bar"
  merge:
      post:
          description: This is an updated description of a child object
          x-safe: false

```

--------------------------------

### Model with Example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines an object schema with an example value. The example provides concrete data for the id and name properties, which can be used for documentation or testing.

```yaml
type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
  - name
examples:
  - name: Puma
    id: 1
```

--------------------------------

### Example data for form query string

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Sample data used in the examples: an object 'formulas' (exploded) and an array 'words' (not exploded).

```yaml
formulas:
  a: x+y
  b: x/y
  c: x^y
words:
- math
- is
- fun
```

--------------------------------

### Add Array Element Example

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2019-12-24-Overlays.md

A YAML example showing how to add an array element using the add property.

```yaml
overlay: 1.0.0
info:
  title: Add an array element
  version: 1.0.0
updates:
- target: paths.*.get.parameters
  add:
    name: newParam
    in: query

```

--------------------------------

### Traits Example - Overlay Document

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2019-12-24-Overlays.md

A YAML example showing an Overlay document that applies updates based on the x-oai-traits extension.

```yaml
overlay: 1.0.0
info:
  title: Apply Traits
  version: 1.0.0
updates:
- target: $.paths[*].get[?contains(x-traits,'paged')]
  merge:
    parameters:
      - name: top
        in: query
      - name: skip
        in: query

```

--------------------------------

### XML Attribute, Prefix and Namespace example (XML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

The content of './examples/Person.xml' referenced by the previous YAML example. Shows the XML with the attribute, namespace, and prefix.

```xml
<Person id="123">
  <sample:name xmlns:sample="https://example.com/schema/sample">example</sample:name>
</Person>
```

--------------------------------

### XML Name Replacement example (XML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

The content of './examples/pets.xml' for the XML Name Replacement example. Shows the XML with renamed elements.

```xml
<document>
  <animal>dog</animal>
  <animal>cat</animal>
  <animal>hamster</animal>
</document>
```

--------------------------------

### Wildcard Overlays Example

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2019-12-24-Overlays.md

A YAML example showing wildcard overlays to apply updates to multiple target objects using JMESPath wildcards.

```yaml
overlay: 1.0.0
info:
  title: Update many objects at once
  version: 1.0.0
updates:
- target: paths.*.get
  merge:
    x-safe: true
- target: paths.*.get.parameters[?name=='filter' && in=='query']
  merge:
    schema:
      $ref: "/components/schemas/filterSchema"

```

--------------------------------

### Path Item Object Example (YAML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines a path item with a GET operation, a required path parameter, and an additional COPY operation. The GET operation returns an array of Pet objects, while the COPY operation copies pet information. Responses include a 200 success and a default error payload.

```yaml
get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*':
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        text/html:
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
  - name: id
    in: path
    description: ID of pet to use
    required: true
    schema:
      type: array
      items:
        type: string
    style: simple
additionalOperations:
  COPY:
    description: Copies pet information based on ID
    summary: Copies pets by ID
    operationId: copyPetsById
    responses:
      '200':
        description: pet response
        content:
          '*/*':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Pet'
      default:
        description: error payload
        content:
          text/html:
            schema:
              $ref: '#/components/schemas/ErrorModel'
```

--------------------------------

### External XML file for array example (XML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

The content of './examples/pets.xml' referenced by the previous YAML example. Shows the expected XML structure for the array of animals.

```xml
<document>
  <animals>dog</animals>
  <animals>cat</animals>
  <animals>hamster</animals>
</document>
```

--------------------------------

### Structured Overlay Example

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2019-12-24-Overlays.md

A YAML example showing a structured overlay that mirrors the target document structure to apply multiple updates efficiently.

```yaml
overlay: 1.0.0
info:
  title: Structured Overlay
  version: 1.0.0
updates:
- target: "@"
  merge:
    info:
      x-overlay-applied: structured-overlay
    paths:
      "/":
        summary: "The root resource"
        get:
          summary: "Retrieve the root resource"
          x-rate-limit: 100
      "/pets":
        get:
          summary: "Retrieve a list of pets"
          x-rate-limit: 100
    components:
    tags:

```

--------------------------------

### YAML example

Source: https://github.com/oai/openapi-specification/blob/main/tests/md2html/fixtures/basic-new.md

A YAML mapping with a single key-value pair. This is a minimal example of a YAML document.

```yaml
foo: true
```

--------------------------------

### Components Object Example (YAML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Complete YAML example of a Components Object defining reusable schemas, parameters, responses, and security schemes. Demonstrates how to structure components for later reference via $ref.

```yaml
components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api-key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets
```

--------------------------------

### JSON Lines example

Source: https://github.com/oai/openapi-specification/blob/main/tests/md2html/fixtures/basic-new.md

Three JSON Lines records representing the same events as the event stream example.

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

--------------------------------

### Traits Example - OpenAPI Description

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2019-12-24-Overlays.md

A YAML example showing an OpenAPI description with x-oai-traits extension to identify where overlay updates should be applied.

```yaml
openapi: 3.1.0
info:
  title: Api with a paged collection
  version: 1.0.0
paths:
  /items:
    get:
      x-oai-traits: ["paged"]
      responses:
        200:
          description: OK

```

--------------------------------

### Multiple servers example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows how to describe multiple servers in the OpenAPI Object's servers field, each with url, description, and name.

```yaml
servers:
  - url: https://development.gigantic-server.com/v1
    description: Development server
    name: dev
  - url: https://staging.gigantic-server.com/v1
    description: Staging server
    name: staging
  - url: https://api.gigantic-server.com/v1
    description: Production server
    name: prod
```

--------------------------------

### URI example

Source: https://github.com/oai/openapi-specification/blob/main/tests/md2html/fixtures/basic-new.md

A URI with query parameters and a fragment.

```uri
https://foo.com/bar?baz=qux&fred=waldo#fragment
```

--------------------------------

### Header Object Example: ETag with pattern

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Requires an ETag header with a value starting with a double quote. The pattern ^" enforces the format, and the example shows the quoted value.

```yaml
ETag:
  required: true
  schema:
    type: string
    # Note that quotation marks are part of the
    # ETag value, unlike many other headers that
    # use a quoted string purely for managing
    # reserved characters.
    pattern: ^"
  example: '"xyzzy"'
```

--------------------------------

### Single server example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Describes a single server with url, description, and name fields. The url is required; description and name are optional.

```yaml
url: https://development.gigantic-server.com/v1
description: Development server
name: dev
```

--------------------------------

### Define CDATA Schema and Response Example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines a component schema with a CDATA node type and a response example that references it. The schema uses contentMediaType text/html and the example provides an externalValue pointing to an XML file.

```yaml
components:
  schemas:
    Documentation:
      type: object
      properties:
        content:
          type: string
          contentMediaType: text/html
          xml:
            nodeType: cdata
  responses:
    AwesomeDocs:
      content:
        application/xml:
          schema:
            $ref: "#/components/schemas/Documentation"
          examples:
            docs:
              dataValue:
                content: <html><head><title>Awesome Docs</title></head><body></body><html>
              externalValue: ./examples/docs.xml
```

--------------------------------

### Tag Object Example with parent and kind fields (JSON and YAML)

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2024-09-01-Tags-Improvement.md

Shows the Tag Object example in JSON and YAML, demonstrating the new fields: summary, parent, and kind. The example includes three tags: account-updates, partner, and external, with partner nested under external via the parent field.

```json
{
  "name": "account-updates",
  "summary": "Account Updates",
  "description": "Account update operations",
  "kind": "nav"
},
{
  "name": "partner",
  "summary": "Partner",
  "description": "Operations available to the partners network",
  "parent": "external",
  "kind": "audience"
},
{
  "name": "external",
  "summary": "External",
  "description": "Operations available to external consumers",
  "kind": "audience"
}
```

```yaml
- name: account-updates
  summary: Account Updates
  description: Account update operations
  kind: nav

- name: partner
  summary: Partner
  description: Operations available to the partners network
  parent: external
  kind: audience

- name: external
  summary: External
  description: Operations available to external consumers
  kind: audience
```

--------------------------------

### Request body with referenced schema and multiple media types

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

A request body example that references a schema definition and provides examples for multiple media types: application/json, application/xml, text/plain, and */*. Each example uses an externalValue to point to an external file.

```yaml
description: user to add to the system
content:
  application/json:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example
        externalValue: https://foo.bar/examples/user-example.json
  application/xml:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example in XML
        externalValue: https://foo.bar/examples/user-example.xml
  text/plain:
    examples:
      user:
        summary: User example in plain text
        externalValue: https://foo.bar/examples/user-example.txt
  '*/*':
    examples:
      user:
        summary: User example in other format
        externalValue: https://foo.bar/examples/user-example.whatever
```

--------------------------------

### Webhook Object example (YAML)

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2019-07-17-Webhooks.md

Example of a webhook definition in YAML, showing a status update webhook with request body and response.

```yaml
webhooks:
  statusUpdate:
    requestBody:
      description: Status updates on an item. You can set the URL for these updates in your example.com dashboard.
      content: 
        'application/json':
          schema:
              type: object
              required:
                - item_id
                - status
              properties:
                item_id:
                  type: string
                  description: The ID of the item
                  example: 0a000000012345678
                status:
                  type: integer
                  description: The status of this message, zero for success
                  example: 14
    responses:
      '200':
        description: webhook successfully processed and no retries will be performed
```

--------------------------------

### Querystring parameter with JSONPath example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines a querystring parameter named 'selector' with a content type of application/jsonpath. The example uses the shorthand 'example' because the value is a string serialized as-is. The serializedValue is a URL-encoded JSONPath expression.

```yaml
in: querystring
name: selector
content:
  application/jsonpath:
    schema:
      type: string
    example: $.a.b[1:1]
examples:
  Selector:
    serializedValue: "%24.a.b%5B1%3A1%5D"
```

--------------------------------

### Field Name Examples for Components Object

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows valid keys for the fixed fields of the Components Object, matching the regular expression ^[a-zA-Z0-9\.\-_]+$. These examples illustrate acceptable naming conventions for component keys.

```text
User
User_1
User_Name
user-name
my.org.User
```

--------------------------------

### Response Object Example: Plain Text with Headers

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows a plain text response with an example value and custom headers for rate limiting. Headers include X-Rate-Limit-Limit, X-Rate-Limit-Remaining, and X-Rate-Limit-Reset, each with a description and schema.

```yaml
description: A simple string response
content:
  text/plain:
    schema:
      type: string
    example: 'whoa!'
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    schema:
      type: integer
```

--------------------------------

### Example XML with CDATA Section

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows the expected XML output for the response example, where the content is wrapped in a CDATA section inside the root element.

```xml
<Documentation>
  <![CDATA[<html><head><title>Awesome Docs</title></head><body></body><html>]]>
</Documentation>
```

--------------------------------

### XML example for ordered elements with text (Report.xml)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Corresponding XML serialization of the Report example. Shows the mixed content with preamble text, the data element, and postamble text.

```xml
<Report>Some preamble text.<data>42</data>Some postamble text.</Report>
```

--------------------------------

### Install dependencies with Yarn

Source: https://github.com/oai/openapi-specification/blob/main/CONTRIBUTING.md

Install project dependencies using the immutable flag to ensure reproducibility. Repeat after merging upstream changes.

```bash
yarn install --immutable
```

--------------------------------

### Path parameter with multiple examples and percent-encoding

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines a required path parameter with three examples, each showing dataValue and serializedValue with percent-encoding for non-ASCII characters.

```yaml
name: username
in: path
description: username to fetch
required: true
schema:
  type: string
examples:
  "Edsger Dijkstra":
    dataValue: edijkstra
    serializedValue: edijkstra
  Diṅnāga:
    dataValue: diṅnāga
    serializedValue: di%E1%B9%85n%C4%81ga
  Al-Khwarizmi:
    dataValue: "الخوارزميّ"
    serializedValue: "%D8%A7%D9%84%D8%AE%D9%88%D8%A7%D8%B1%D8%B2%D9%85%D9%8A%D9%91"
```

--------------------------------

### Info Object Example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Example of the Info Object in YAML, showing required fields like title and version, along with optional fields such as summary, description, termsOfService, contact, and license.

```yaml
title: Example Pet Store App
summary: A pet store manager.
description: This is an example server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
```

--------------------------------

### JSON Syntax within YAML for application/json Examples

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Demonstrates using JSON syntax within a YAML document for the 'value' field, since all JSON is valid YAML. Provides the same examples as the YAML version but with JSON formatting for the values.

```yaml
application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value: {
        "name": "Fluffy",
        "petType": "Cat",
        "color": "White",
        "gender": "male",
        "breed": "Persian"
      }
    dog:
      summary: An example of a dog with a cat's name
      value: {
        "name": "Puma",
        "petType": "Dog",
        "color": "Black",
        "gender": "Female",
        "breed": "Mixed"
      }
    frog:
      $ref: '#/components/examples/frog-example'
```

--------------------------------

### Binary Example with externalValue

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Uses externalValue to reference a binary PNG file for the image/png media type. The schema is empty, and the example is named 'Red'.

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

--------------------------------

### XML example for ordered elements (OneTwoThree.xml)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Corresponding XML serialization of the OneTwoThree example. Shows the sequence of elements and the xsi:nil="true" representation for null.

```xml
<OneTwoThree>
  <One>Some text</One>
  <Two unit="cubits">42</Two>
  <Three xsi:nil="true" />
</OneTwoThree>
```

--------------------------------

### HTTP Serialized Set-Cookie Example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows the serialized HTTP response with three Set-Cookie lines, each corresponding to a cookie value from the example.

```http
Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT
Set-Cookie: foo=bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT
Set-Cookie: urlSafeData=Hello%2C%20world%21
```

--------------------------------

### JSON example

Source: https://github.com/oai/openapi-specification/blob/main/tests/md2html/fixtures/basic-new.md

A JSON object with a single boolean property. This is a minimal example of a JSON document.

```json
{
  "foo": true
}
```

--------------------------------

### Remove Array Element Example

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2019-12-24-Overlays.md

A YAML example showing how to remove an array element using the remove property.

```yaml
overlay: 1.0.0
info:
  title: Remove a array element
  version: 1.0.0
updates:
- target: paths[*].get.parameters[? name == 'dummy']
  remove: true

```

--------------------------------

### Primitive Schema Example (YAML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

A simple Schema Object example showing a string with an email format. Use this as a template for defining primitive data types in OpenAPI.

```yaml
type: string
format: email
```

--------------------------------

### Example text/event-stream document

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

A valid request body example for the SSE schema above, showing events with string, int64, and JSON data. Unknown fields and comments are ignored.

```eventstream
event: addString
data: This data is formatted
data: across two lines
retry: 5

event: addInt64
data: 1234
unknownField: this is ignored

: This is a comment
event: addJSON
data: {"foo": 42}
```

--------------------------------

### Example XML for Updated Document

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows the expected XML output for the updated document example, with the root element named UpdatedDocument and content in a CDATA section.

```xml
<UpdatedDocument>
  <![CDATA[<html><head><title>Awesome Docs</title></head><body></body><html>]]>
</UpdatedDocument>
```

--------------------------------

### JSON Examples with dataValue and serializedValue

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows two examples within a single content block: 'noRating' uses only dataValue, while 'withRating' includes both dataValue and serializedValue to illustrate JSON serialization. The schema defines author, title, and rating properties with constraints.

```yaml
content:
  application/json:
    schema:
      type: object
      required:
      - author
      - title
      properties:
        author:
          type: string
        title:
          type: string
        rating:
          type: number
          minimum: 1
          maximum: 5
          multipleOf: 0.5
    examples:
      noRating:
        summary: A not-yet-rated work
        dataValue:
          author: A. Writer
          title: The Newest Book
      withRating:
        summary: A work with an average rating of 4.5 stars
        dataValue:
          author: A. Writer
          title: An Older Book
          rating: 4.5
        serializedValue: |
          {
            "author": "A. Writer",
            "title": "An Older Book",
            "rating": 4.5
          }
```

--------------------------------

### URI template example

Source: https://github.com/oai/openapi-specification/blob/main/tests/md2html/fixtures/basic-new.md

A URI template with variable expansion.

```uritemplate
https://foo.com/bar{?baz*,qux}
```

--------------------------------

### Multiple form-style parameters example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows how multiple parameters with style: form and explode: true map to a single RFC6570 variable list using the ? prefix operator. The example is equivalent to {?foo*,bar} and not {?foo*}{&bar}, because the latter can produce an invalid URI if foo is undefined.

```yaml
parameters:
- name: foo
  in: query
  schema:
    type: object
  explode: true
- name: bar
  in: query
  schema:
    type: string

```

--------------------------------

### License Object Example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Example of the License Object in YAML, showing the name and identifier fields. The identifier field is mutually exclusive with the url field.

```yaml
name: Apache 2.0
identifier: Apache-2.0
```

--------------------------------

### Querystring parameter with serialized JSON example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines a querystring parameter named 'json' with a content type of application/json. The example shows a schema with an array of integers and a nullable boolean, and includes an example with serializedValue. The full URL is constructed by appending the serialized value to the server path.

```yaml
in: querystring
name: json
content:
  application/json:
    schema:
      type: object
      properties:
        numbers:
          type: array
          items:
            type: integer
        flag:
          type: [boolean, "null"]
    examples:
      TwoNoFlag:
        description: Serialize with minimized whitespace
        dataValue:
          numbers:
            - 1
            - 2
          flag: null
        serializedValue: '{"numbers":[1,2],"flag":null}'
examples:
  TwoNoFlag:
    dataValue:
      numbers:
        - 1
        - 2
      flag: null
    serializedValue: "%7B%22numbers%22%3A%5B1%2C2%5D%2C%22flag%22%3Anull%7D"
```

--------------------------------

### Binary content examples (image/png, octet-stream, application/json)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows how to describe binary or unconstrained content in OAS 3.1. The schema may be omitted for binary data.

```yaml
# a PNG image as a binary file:
content:
  image/png: {}
```

```yaml
# an arbitrary binary file:
content:
  application/octet-stream: {}
```

```yaml
# arbitrary JSON without constraints beyond being syntactically valid:
content:
  application/json: {}
```

--------------------------------

### Full URL with serialized querystring parameter

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

The full URL incorporating the serializedValue from the previous example, assuming a path of /foo and a server of https://example.com.

```uri
https://example.com/foo?%7B%22numbers%22%3A%5B1%2C2%5D%2C%22flag%22%3Anull%7D
```

--------------------------------

### Example XML for Stored Document

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows the expected XML output for the stored document example, with the root element named StoredDocument and content in a CDATA section.

```xml
<StoredDocument>
  <![CDATA[<html><head><title>Awesome Docs</title></head><body></body><html>]]>
</StoredDocument>
```

--------------------------------

### openapi.yaml: Reference tag and paths from customers.yaml

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2025-03-20-URIs-for-Tags.md

Example main OpenAPI file that uses $ref with JSON Pointers to include the Tag Object and endpoint paths from customers.yaml. Demonstrates the user's proposed approach to reuse tag declarations.

```YAML
info:
...
tags:
  - $ref: "./customers.yaml#/tags/0"
  
paths:
  /customers/{id}/:
    $ref: "./customers.yaml#/paths/~customers~1{id}~1"
  /customers/:
    $ref: "./customers.yaml#/paths/~customers~1"
```

--------------------------------

### Boolean Query Parameter Example with dataValue and serializedValue

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows how boolean query parameters are serialized for a parameter named 'flag'. Two examples ('true' and 'false') demonstrate the dataValue and serializedValue forms, with serializedValue showing the query string representation.

```yaml
name: flag
in: query
required: true
schema:
  type: boolean
examples:
  "true":
    dataValue: true
    serializedValue: flag=true
  "false":
    dataValue: false
    serializedValue: flag=false
```

--------------------------------

### Path templating matching examples

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows three sets of path templates: concrete path matched first, identical invalid paths, and ambiguous paths. Use these to understand matching precedence and potential conflicts.

```text
  /pets/{petId}
  /pets/mine
```

```text
  /pets/{petId}
  /pets/{name}
```

```text
  /{entity}/me
  /books/{id}
```

--------------------------------

### Complex parameter with content and multiple example levels

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows a query parameter using content to define serialization, with examples at both media type and parameter levels, illustrating different serializedValue forms.

```yaml
in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number
    examples:
      'New York':
        dataValue:
          lat: 40.6
          long: -73.9
        serializedValue: '{"lat":40.6,"long":-73.9}'
examples:
  'New York':
    dataValue:
      lat: 40.6
      long: -73.9
    serializedValue: coordinates=%7B%22lat%22%3A40.6%2C%22long%22%3A-73.9%7D
```

--------------------------------

### YAML example: Collection pagination linkset for Link header and JSON content

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines schemas for a simple link context and collection links, then uses them in responses for both application/json content and an application/linkset header, as well as an application/linkset+json content. The example shows how the same data model can be serialized in both formats.

```yaml
components:
  schemas:
    SimpleLinkContext:
      type: array
      items:
        type: object
        required:
        - href
        properties:
          href:
            type: string
            format: uri-reference
    CollectionLinks:
      type: object
      required:
      - linkset
      properties:
        linkset:
          type: array
          items:
            type: object
            required: [first, prev, next, last]
            properties:
              anchor:
                type: string
                format: uri
            additionalProperties:
              $ref: '#/components/schemas/SimpleLinkContext'
  responses:
    CollectionWithLinks:
      content:
        application/json:
          schema:
            type: array
      headers:
        Link:
          required: true
          content:
            application/linkset:
              schema:
                $ref: '#/components/schemas/CollectionLinks'
    StandaloneJsonLinkset:
      content:
        application/linkset+json:
          schema:
            $ref: '#/components/schemas/CollectionLinks'
```

--------------------------------

### Undefined values example data

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Example data with an empty 'formulas' object and a 'words' array. This data is used to illustrate how undefined values are handled in manual URI Template construction.

```yaml
formulas: {}
words:
- hello
- world
```

--------------------------------

### External Documentation Object Example (YAML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows an external documentation reference with a description and URL. The url field is required and must be a URI.

```yaml
description: Find more info here
url: https://example.com
```

--------------------------------

### Sequential Media Type Examples

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Lists example sequential media types that repeat a structure without headers or footers. These are used to identify content types that can be streamed and mapped to an array in the JSON Schema data model.

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

--------------------------------

### Tag Object Example: tags list

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows a list of tags with metadata including name, summary, description, and custom fields like kind and parent. The example includes three tags: account-updates, partner, and external.

```yaml
tags:
  - name: account-updates
    summary: Account Updates
    description: Account update operations
    kind: nav

  - name: partner
    summary: Partner
    description: Operations available to the partners network
    parent: external
    kind: audience

  - name: external
    summary: External
    description: Operations available to external consumers
    kind: audience
```

--------------------------------

### XML Name Replacement example (YAML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows how to use the 'xml' object to rename elements in the XML representation. The 'name' property in the schema's xml object replaces the element name, and the example references an external XML file.

```yaml
application/xml:
  schema:
    type: object
    xml:
      name: document
    properties:
      animals:
        type: string
        xml:
          name: animal
  examples:
    pets:
      dataValue:
        animals:
          - dog
          - cat
          - hamster
      externalValue: ./examples/pets.xml
```

--------------------------------

### OAuth Flow Object Example (YAML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Example of an OAuth2 security scheme with implicit and authorizationCode flows. Shows required authorizationUrl, tokenUrl, and scopes fields. The scopes map includes write and read permissions for pets.

```yaml
type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
```

--------------------------------

### OpenAPI top-level webhooks element with inbound-sms example

Source: https://github.com/oai/openapi-specification/blob/main/proposals/2019-07-17-Webhooks.md

Example OpenAPI specification for a top-level `webhooks` element with a named entry `inbound-sms` containing a Path Item Object. The example defines an incoming webhook for Nexmo SMS, including request body schema and a 200 response. Note that Nexmo will retry messages that are not successfully acknowledged.

```yaml
webhooks:
  inbound-sms:
    post:
      summary: Inbound SMS to your Nexmo number
      operationId: inbound-sms
      description: |
        If you rent one or more virtual numbers from Nexmo, inbound messages to that number are sent to your [webhook endpoint](https://developer.nexmo.com/concepts/guides/webhooks).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - msisdn
                - to
                - messageid
                - text
                - type
                - keyword
                - message-timestamp
              properties:
                msisdn:
                  type: string
                  description: the phone number that this inbound message was sent from. numbers are specified in e.164 format.
                  example: '447700900001'
                to:
                  type: string
                  description: the phone number the message was sent to. **this is your virtual number**. numbers are specified in e.164 format.
                  example: '447700900000'
                messageid:
                  type: string
                  description: the id of the message
                  example: 0a0000000123abcd1
                text:
                  type: string
                  description: The message body for this inbound message.
                  example: Hello world
                type:
                  type: string
                  description: |
                    Possible values are:

                      - `text` - standard text.
                      - `unicode` - URLencoded   unicode  . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.
                      - `binary` - a binary message.
                  example: 'text'
                keyword:
                  type: string
                  description: The first word in the message body. This is typically used with short codes.
                  example: Hello
                message-timestamp:
                  description: The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.
                  type: string
                  example: 2020-01-01 12:00:00
      responses:
        '200':
          description: |
            Your server returns this code if it accepts the callback. Note that
            Nexmo will retry messages that are not successfully acknowledged.
```

--------------------------------

### Media Type Objects for sequential JSON log entries

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines schemas, examples, and responses for streaming log entries in sequential JSON media types. Shows the relationship between schema and itemSchema, and when to use each, even though the examples field is the same either way.

```yaml
components:
  schemas:
    LogEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        level:
          type: integer
          minimum: 0
        message:
          type: string
    Log:
      type: array
      items:
        $ref: "#/components/schemas/LogEntry"
      maxItems: 100
  examples:
    LogJSONSeq:
      summary: Log entries in application/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 below
      externalValue: examples/log.json-seq
    LogJSONPerLine:
      summary: Log entries in application/jsonl or application/x-ndjson
      description: JSONL and NDJSON are identical for this example
      # Note that the value must be written as a string with newlines,
      # as JSONL and NDJSON are not valid YAML
      value: |
        {"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"
```

--------------------------------

### XML Attribute, Prefix and Namespace example (YAML)

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows how to define XML attributes, namespaces, and prefixes in a schema. The 'id' property is serialized as an attribute, and the 'name' property uses a namespace and prefix.

```yaml
components:
  schemas:
    Person:
      type: object
      properties:
        id:
          type: integer
          format: int32
          xml:
            nodeType: attribute
        name:
          type: string
          xml:
            namespace: https://example.com/schema/sample
            prefix: sample
  requestBodies:
    Person:
      content:
        application/xml:
          schema:
            $ref: "#/components/schemas/Person"
          examples:
            Person:
              dataValue:
                id: 123
                name: example
              externalValue: ./examples/Person.xml
```

--------------------------------

### API Key Example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines an API key security scheme located in the header.

```yaml
type: apiKey
name: api-key
in: header
```

--------------------------------

### Basic Authentication Example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines an HTTP basic authentication scheme using the 'type' and 'scheme' fields.

```yaml
type: http
scheme: basic
```

--------------------------------

### HTTP response for callback subscription

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Example HTTP response with status 201 Created and a Location header, shown as the result of the preceding request.

```http
201 Created
Location: https://example.org/subscription/1
```

--------------------------------

### Full build and validation

Source: https://github.com/oai/openapi-specification/blob/main/CONTRIBUTING.md

Run full check: validation, HTML build, schema publish. After this, open deploy-preview/oas.html to review changes.

```bash
yarn build-src
```

--------------------------------

### Enable Corepack for Yarn

Source: https://github.com/oai/openapi-specification/blob/main/CONTRIBUTING.md

Run once to make the repository's pinned Yarn version available after installing Node.js 24.

```bash
corepack enable
```

--------------------------------

### Reference Object Example: $ref to component

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows a Reference Object that references a component schema using a $ref URI.

```yaml
$ref: '#/components/schemas/Pet'
```

--------------------------------

### Responses Object YAML Example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

YAML example of a Responses Object with a 200 response for a successful operation and a default response for errors. The 200 response references the Pet schema, while the default references the ErrorModel schema.

```yaml
'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'
```

--------------------------------

### JavaScript style examples for dataValue

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows how different value types (undefined, string, array, object) are represented in the dataValue field of an Example Object. The arrow indicates the value shown for each type.

```javascript
   undefined -> null
   string -> "blue"
   array -> ["blue", "black", "brown"]
   object -> { "R": 100, "G": 200, "B": 150 }
```

--------------------------------

### Relative Schema Document Example: $ref to Pet.yaml

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows a Reference Object that references a relative schema document.

```yaml
$ref: Pet.yaml
```

--------------------------------

### Implicit OAuth2 Example

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Defines an OAuth2 implicit flow with authorization URL and scopes.

```yaml
type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
```

--------------------------------

### Set up local respec build for viewing fixtures

Source: https://github.com/oai/openapi-specification/blob/main/tests/md2html/README.md

Run these shell commands from the project root to copy the respec-w3c.js build into a local 'js' folder and create a .gitignore file. After running them, open the HTML files in the 'fixtures' folder in a local browser.

```shell
mkdir js
cp ../../node_modules/respec/builds/respec-w3c.js js/
echo "*" > js/.gitignore
```

--------------------------------

### Full URL with serialized JSONPath parameter

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

The full URL incorporating the serializedValue from the JSONPath example, assuming a path of /foo and a server of https://example.com.

```uri
https://example.com/foo?%24.a.b%5B1%3A1%5D
```

--------------------------------

### Response Object Example: No Return Value

Source: https://github.com/oai/openapi-specification/blob/main/versions/3.2.1.md

Shows a response with no return value, containing only a description. This is used when the operation returns no content.

```yaml
description: object created
```

--------------------------------

### Run repository tests

Source: https://github.com/oai/openapi-specification/blob/main/CONTRIBUTING.md

Runs the repository's JSON Schema and Markdown rendering fixture tests.

```bash
yarn test
```
Tokens:
Raw