schema.yaml

$id: 'https://spec.openapis.org/oas/3.2/schema/WORK-IN-PROGRESS'
$schema: 'https://json-schema.org/draft/2020-12/schema'

description: The description of OpenAPI v3.2.x Documents without Schema Object validation

type: object
properties:
  openapi:
    type: string
    pattern: '^3\.2\.\d+(-.+)?$'
  $self:
    type: string
    $comment: resolved against the retrieval uri
    format: uri-reference
    $comment: MUST NOT contain a fragment
    pattern: '^[^#]*$'
  info:
    $ref: '#/$defs/info'
  jsonSchemaDialect:
    type: string
    $comment: resolved against the resolved version of $self
    format: uri-reference
    default: 'https://spec.openapis.org/oas/3.2/dialect/WORK-IN-PROGRESS'
  servers:
    $comment: server urls are resolved against the HTTP request uri itself (template matching ideally happens first, because of url encoding, but matching the template parts separately may produce ambiguous results, so in my implementation I concatenate the server url template with the path template and then match that against the entire uri)
    type: array
    items:
      $ref: '#/$defs/server'
    default:
      - url: /
  paths:
    $ref: '#/$defs/paths'
  webhooks:
    type: object
    additionalProperties:
      $ref: '#/$defs/path-item'
  components:
    $ref: '#/$defs/components'
  security:
    type: array
    items:
      $ref: '#/$defs/security-requirement'
  tags:
    type: array
    items:
      $ref: '#/$defs/tag'
  externalDocs:
    $ref: '#/$defs/external-documentation'
required:
  - openapi
  - info
anyOf:
  - required:
    - paths
  - required:
    - components
  - required:
    - webhooks
$ref: '#/$defs/specification-extensions'
unevaluatedProperties: false

$defs:
  info:
    $comment: https://spec.openapis.org/oas/v3.2#info-object
    type: object
    properties:
      title:
        type: string
      summary:
        type: string
      description:
        type: string
      termsOfService:
        $comment: resolved against the resolved version of $self
        type: string
        format: uri-reference
      contact:
        $ref: '#/$defs/contact'
      license:
        $ref: '#/$defs/license'
      version:
        type: string
    required:
      - title
      - version
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  contact:
    $comment: https://spec.openapis.org/oas/v3.2#contact-object
    type: object
    properties:
      name:
        type: string
      url:
        $comment: resolved against the resolved version of $self
        type: string
        format: uri-reference
      email:
        type: string
        format: email
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  license:
    $comment: https://spec.openapis.org/oas/v3.2#license-object
    type: object
    properties:
      name:
        type: string
      identifier:
        type: string
      url:
        $comment: resolved against the resolved version of $self
        type: string
        format: uri-reference
    required:
      - name
    dependentSchemas:
      identifier:
        not:
          required:
            - url
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  server:
    $comment: https://spec.openapis.org/oas/v3.2#server-object
    type: object
    properties:
      url:
        type: string
      description:
        type: string
      name:
        type: string
      variables:
        type: object
        additionalProperties:
          $ref: '#/$defs/server-variable'
    required:
      - url
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  server-variable:
    $comment: https://spec.openapis.org/oas/v3.2#server-variable-object
    type: object
    properties:
      enum:
        type: array
        items:
          type: string
        minItems: 1
      default:
        type: string
      description:
        type: string
    required:
      - default
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  components:
    $comment: https://spec.openapis.org/oas/v3.2#components-object
    type: object
    properties:
      schemas:
        type: object
        additionalProperties:
          $dynamicRef: '#meta'
      responses:
        type: object
        additionalProperties:
          $ref: '#/$defs/response-or-reference'
      parameters:
        type: object
        additionalProperties:
          $ref: '#/$defs/parameter-or-reference'
      examples:
        type: object
        additionalProperties:
          $ref: '#/$defs/example-or-reference'
      requestBodies:
        type: object
        additionalProperties:
          $ref: '#/$defs/request-body-or-reference'
      headers:
        type: object
        additionalProperties:
          $ref: '#/$defs/header-or-reference'
      securitySchemes:
        type: object
        additionalProperties:
          $ref: '#/$defs/security-scheme-or-reference'
      links:
        type: object
        additionalProperties:
          $ref: '#/$defs/link-or-reference'
      callbacks:
        type: object
        additionalProperties:
          $ref: '#/$defs/callbacks-or-reference'
      pathItems:
        type: object
        additionalProperties:
          $ref: '#/$defs/path-item'
      mediaTypes:
        type: object
        additionalProperties:
          $ref: '#/$defs/media-type-or-reference'
    patternProperties:
      '^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems|mediaTypes)$':
        $comment: Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected
        propertyNames:
          pattern: '^[a-zA-Z0-9._-]+$'
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  paths:
    $comment: https://spec.openapis.org/oas/v3.2#paths-object
    type: object
    patternProperties:
      '^/':
        $ref: '#/$defs/path-item'
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  path-item:
    $comment: https://spec.openapis.org/oas/v3.2#path-item-object
    type: object
    properties:
      $ref:
        $comment: resolved against the resolved version of $self
        type: string
        format: uri-reference
      summary:
        type: string
      description:
        type: string
      servers:
        type: array
        items:
          $ref: '#/$defs/server'
      parameters:
        type: array
        items:
          $ref: '#/$defs/parameter-or-reference'
      additionalOperations:
        type: object
        additionalProperties:
          $ref: '#/$defs/operation'
        propertyNames:
          $comment: RFC9110 restricts methods to "1*tchar" in ABNF
          pattern: "^[a-zA-Z0-9!#$%&'*+.^_`|~-]+$"
          not:
            enum:
              - GET
              - PUT
              - POST
              - DELETE
              - OPTIONS
              - HEAD
              - PATCH
              - TRACE
              - QUERY
      get:
        $ref: '#/$defs/operation'
      put:
        $ref: '#/$defs/operation'
      post:
        $ref: '#/$defs/operation'
      delete:
        $ref: '#/$defs/operation'
      options:
        $ref: '#/$defs/operation'
      head:
        $ref: '#/$defs/operation'
      patch:
        $ref: '#/$defs/operation'
      trace:
        $ref: '#/$defs/operation'
      query:
        $ref: '#/$defs/operation'
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  operation:
    $comment: https://spec.openapis.org/oas/v3.2#operation-object
    type: object
    properties:
      tags:
        type: array
        items:
          type: string
      summary:
        type: string
      description:
        type: string
      externalDocs:
        $ref: '#/$defs/external-documentation'
      operationId:
        type: string
      parameters:
        type: array
        items:
          $ref: '#/$defs/parameter-or-reference'
      requestBody:
        $ref: '#/$defs/request-body-or-reference'
      responses:
        $ref: '#/$defs/responses'
      callbacks:
        type: object
        additionalProperties:
          $ref: '#/$defs/callbacks-or-reference'
      deprecated:
        default: false
        type: boolean
      security:
        type: array
        items:
          $ref: '#/$defs/security-requirement'
      servers:
        type: array
        items:
          $ref: '#/$defs/server'
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  external-documentation:
    $comment: https://spec.openapis.org/oas/v3.2#external-documentation-object
    type: object
    properties:
      description:
        type: string
      url:
        $comment: resolved against ???
        type: string
        format: uri-reference
    required:
      - url
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  parameter:
    $comment: https://spec.openapis.org/oas/v3.2#parameter-object
    type: object
    properties:
      name:
        type: string
      in:
        enum:
          - query
          - querystring
          - header
          - path
          - cookie
      description:
        type: string
      required:
        default: false
        type: boolean
      deprecated:
        default: false
        type: boolean
      schema:
        $dynamicRef: '#meta'
      content:
        $ref: '#/$defs/content'
        minProperties: 1
        maxProperties: 1
    required:
      - name
      - in
    oneOf:
      - required:
        - schema
      - required:
        - content
    allOf:
      - $ref: '#/$defs/examples'
      - $ref: '#/$defs/specification-extensions'
      - if:
          properties:
            in:
              const: query
          required:
            - in
        then:
          properties:
            allowEmptyValue:
              default: false
              type: boolean
      - if:
          properties:
            in:
              const: querystring
          required:
            - in
        then:
          required:
            - content
    dependentSchemas:
      schema:
        properties:
          style:
            type: string
          explode:
            type: boolean
          allowReserved:
            default: false
            type: boolean
        allOf:
          - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path'
          - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header'
          - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query'
          - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie'
          - $ref: '#/$defs/styles-for-form'

        $defs:
          styles-for-path:
            if:
              properties:
                in:
                  const: path
              required:
                - in
            then:
              properties:
                style:
                  default: simple
                  enum:
                    - matrix
                    - label
                    - simple
                required:
                  const: true
              required:
                - required

          styles-for-header:
            if:
              properties:
                in:
                  const: header
              required:
                - in
            then:
              properties:
                style:
                  default: simple
                  const: simple

          styles-for-query:
            if:
              properties:
                in:
                  const: query
              required:
                - in
            then:
              properties:
                style:
                  default: form
                  enum:
                    - form
                    - spaceDelimited
                    - pipeDelimited
                    - deepObject

          styles-for-cookie:
            if:
              properties:
                in:
                  const: cookie
              required:
                - in
            then:
              properties:
                style:
                  default: form
                  const: form

    unevaluatedProperties: false

  parameter-or-reference:
    if:
      type: object
      required:
        - $ref
    then:
      $ref: '#/$defs/reference'
    else:
      $ref: '#/$defs/parameter'

  request-body:
    $comment: https://spec.openapis.org/oas/v3.2#request-body-object
    type: object
    properties:
      description:
        type: string
      content:
        $ref: '#/$defs/content'
      required:
        default: false
        type: boolean
    required:
      - content
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  request-body-or-reference:
    if:
      type: object
      required:
        - $ref
    then:
      $ref: '#/$defs/reference'
    else:
      $ref: '#/$defs/request-body'

  content:
    $comment: https://spec.openapis.org/oas/v3.2#fixed-fields-10
    type: object
    additionalProperties:
      $ref: '#/$defs/media-type-or-reference'
    propertyNames:
      format: media-range

  media-type:
    $comment: https://spec.openapis.org/oas/v3.2#media-type-object
    type: object
    properties:
      description:
        type: string
      schema:
        $dynamicRef: '#meta'
      itemSchema:
        $dynamicRef: '#meta'
      encoding:
        type: object
        additionalProperties:
          $ref: '#/$defs/encoding'
      prefixEncoding:
        type: array
        items:
          $ref: '#/$defs/encoding'
      itemEncoding:
        $ref: '#/$defs/encoding'
    allOf:
      - $ref: '#/$defs/examples'
      - $ref: '#/$defs/specification-extensions'
      - dependentSchemas:
          encoding:
            properties:
              prefixEncoding: false
              itemEncoding: false
    unevaluatedProperties: false

  media-type-or-reference:
    if:
      type: object
      required:
        - $ref
    then:
      $ref: '#/$defs/reference'
    else:
      $ref: '#/$defs/media-type'

  encoding:
    $comment: https://spec.openapis.org/oas/v3.2#encoding-object
    type: object
    properties:
      contentType:
        type: string
        format: media-range
      headers:
        type: object
        additionalProperties:
          $ref: '#/$defs/header-or-reference'
      style:
        default: form
        enum:
          - form
          - spaceDelimited
          - pipeDelimited
          - deepObject
      explode:
        type: boolean
      allowReserved:
        default: false
        type: boolean
      encoding:
        type: object
        additionalProperties:
          $ref: '#/$defs/encoding'
      prefixEncoding:
        type: array
        items:
          $ref: '#/$defs/encoding'
      itemEncoding:
        $ref: '#/$defs/encoding'
    allOf:
      - $ref: '#/$defs/specification-extensions'
      - $ref: '#/$defs/styles-for-form'
      - dependentSchemas:
          encoding:
            properties:
              prefixEncoding: false
              itemEncoding: false
    unevaluatedProperties: false

  responses:
    $comment: https://spec.openapis.org/oas/v3.2#responses-object
    type: object
    properties:
      default:
        $ref: '#/$defs/response-or-reference'
    patternProperties:
      '^[1-5](?:[0-9]{2}|XX)$':
        $ref: '#/$defs/response-or-reference'
    minProperties: 1
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false
    if:
      $comment: either default, or at least one response code property must exist
      patternProperties:
        '^[1-5](?:[0-9]{2}|XX)$': false
    then:
      required: [default]

  response:
    $comment: https://spec.openapis.org/oas/v3.2#response-object
    type: object
    properties:
      summary:
        type: string
      description:
        type: string
      headers:
        type: object
        additionalProperties:
          $ref: '#/$defs/header-or-reference'
      content:
        $ref: '#/$defs/content'
      links:
        type: object
        additionalProperties:
          $ref: '#/$defs/link-or-reference'
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  response-or-reference:
    if:
      type: object
      required:
        - $ref
    then:
      $ref: '#/$defs/reference'
    else:
      $ref: '#/$defs/response'

  callbacks:
    $comment: https://spec.openapis.org/oas/v3.2#callback-object
    type: object
    $ref: '#/$defs/specification-extensions'
    additionalProperties:
      $ref: '#/$defs/path-item'

  callbacks-or-reference:
    if:
      type: object
      required:
        - $ref
    then:
      $ref: '#/$defs/reference'
    else:
      $ref: '#/$defs/callbacks'

  example:
    $comment: https://spec.openapis.org/oas/v3.2#example-object
    type: object
    properties:
      summary:
        type: string
      description:
        type: string
      dataValue: true
      serializedValue:
        type: string
      value: true
      externalValue:
        $comment: resolved against the resolved version of $self
        type: string
        format: uri-reference
    allOf:
    - not:
        required:
        - value
        - externalValue
    - not:
        required:
        - value
        - dataValue
    - not:
        required:
        - value
        - serializedValue
    - not:
        required:
        - serializedValue
        - externalValue
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  example-or-reference:
    if:
      type: object
      required:
        - $ref
    then:
      $ref: '#/$defs/reference'
    else:
      $ref: '#/$defs/example'

  link:
    $comment: https://spec.openapis.org/oas/v3.2#link-object
    type: object
    properties:
      operationRef:
        $comment: resolved against the resolved version of $self
        type: string
        format: uri-reference
      operationId:
        type: string
      parameters:
        $ref: '#/$defs/map-of-strings'
      requestBody: true
      description:
        type: string
      server:
        $ref: '#/$defs/server'
    oneOf:
      - required:
        - operationRef
      - required:
        - operationId
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  link-or-reference:
    if:
      type: object
      required:
        - $ref
    then:
      $ref: '#/$defs/reference'
    else:
      $ref: '#/$defs/link'

  header:
    $comment: https://spec.openapis.org/oas/v3.2#header-object
    type: object
    properties:
      description:
        type: string
      required:
        default: false
        type: boolean
      deprecated:
        default: false
        type: boolean
      schema:
        $dynamicRef: '#meta'
      content:
        $ref: '#/$defs/content'
        minProperties: 1
        maxProperties: 1
    oneOf:
      - required:
        - schema
      - required:
        - content
    dependentSchemas:
      schema:
        properties:
          style:
            default: simple
            const: simple
          explode:
            default: false
            type: boolean
          allowReserved:
            default: false
            type: boolean
        $ref: '#/$defs/examples'
    allOf:
    - $ref: '#/$defs/examples'
    - $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  header-or-reference:
    if:
      type: object
      required:
        - $ref
    then:
      $ref: '#/$defs/reference'
    else:
      $ref: '#/$defs/header'

  tag:
    $comment: https://spec.openapis.org/oas/v3.2#tag-object
    type: object
    properties:
      name:
        type: string
      summary:
        type: string
      description:
        type: string
      externalDocs:
        $ref: '#/$defs/external-documentation'
      parent:
        type: string
      kind:
        type: string
    required:
      - name
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

  reference:
    $comment: https://spec.openapis.org/oas/v3.2#reference-object
    type: object
    properties:
      $ref:
        $comment: resolved against the resolved version of $self
        type: string
        format: uri-reference
      summary:
        type: string
      description:
        type: string

  schema:
    $comment: https://spec.openapis.org/oas/v3.2#schema-object
    $dynamicAnchor: meta
    type:
      - object
      - boolean

  security-scheme:
    $comment: https://spec.openapis.org/oas/v3.2#security-scheme-object
    type: object
    properties:
      type:
        enum:
          - apiKey
          - http
          - mutualTLS
          - oauth2
          - openIdConnect
      description:
        type: string
      deprecated:
        default: false
        type: boolean
    required:
      - type
    allOf:
      - $ref: '#/$defs/specification-extensions'
      - $ref: '#/$defs/security-scheme/$defs/type-apikey'
      - $ref: '#/$defs/security-scheme/$defs/type-http'
      - $ref: '#/$defs/security-scheme/$defs/type-http-bearer'
      - $ref: '#/$defs/security-scheme/$defs/type-oauth2'
      - $ref: '#/$defs/security-scheme/$defs/type-oidc'
    unevaluatedProperties: false

    $defs:
      type-apikey:
        if:
          properties:
            type:
              const: apiKey
          required:
            - type
        then:
          properties:
            name:
              type: string
            in:
              enum:
                - query
                - header
                - cookie
          required:
            - name
            - in

      type-http:
        if:
          properties:
            type:
              const: http
          required:
            - type
        then:
          properties:
            scheme:
              type: string
          required:
            - scheme

      type-http-bearer:
        if:
          properties:
            type:
              const: http
            scheme:
              type: string
              pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$
          required:
            - type
            - scheme
        then:
          properties:
            bearerFormat:
              type: string

      type-oauth2:
        if:
          properties:
            type:
              const: oauth2
          required:
            - type
        then:
          properties:
            flows:
              $ref: '#/$defs/oauth-flows'
            oauth2MetadataUrl:
              $comment: resolved against the matching and de-templated server url
              type: string
              format: uri-reference
          required:
            - flows

      type-oidc:
        if:
          properties:
            type:
              const: openIdConnect
          required:
            - type
        then:
          properties:
            openIdConnectUrl:
              $comment: resolved against the matching and de-templated server url
              type: string
              format: uri-reference
          required:
            - openIdConnectUrl

  security-scheme-or-reference:
    if:
      type: object
      required:
        - $ref
    then:
      $ref: '#/$defs/reference'
    else:
      $ref: '#/$defs/security-scheme'

  oauth-flows:
    type: object
    properties:
      implicit:
        $ref: '#/$defs/oauth-flows/$defs/implicit'
      password:
        $ref: '#/$defs/oauth-flows/$defs/password'
      clientCredentials:
        $ref: '#/$defs/oauth-flows/$defs/client-credentials'
      authorizationCode:
        $ref: '#/$defs/oauth-flows/$defs/authorization-code'
      deviceAuthorization:
        $ref: '#/$defs/oauth-flows/$defs/device-authorization'
    $ref: '#/$defs/specification-extensions'
    unevaluatedProperties: false

    $defs:
      implicit:
        $comment: references are resolved against the matching and de-templated server url
        type: object
        properties:
          authorizationUrl:
            type: string
            format: uri-reference
          refreshUrl:
            type: string
            format: uri-reference
          scopes:
            $ref: '#/$defs/map-of-strings'
        required:
          - authorizationUrl
          - scopes
        $ref: '#/$defs/specification-extensions'
        unevaluatedProperties: false

      password:
        $comment: references are resolved against the matching and de-templated server url
        type: object
        properties:
          tokenUrl:
            type: string
            format: uri-reference
          refreshUrl:
            type: string
            format: uri-reference
          scopes:
            $ref: '#/$defs/map-of-strings'
        required:
          - tokenUrl
          - scopes
        $ref: '#/$defs/specification-extensions'
        unevaluatedProperties: false

      client-credentials:
        $comment: references are resolved against the matching and de-templated server url
        type: object
        properties:
          tokenUrl:
            type: string
            format: uri-reference
          refreshUrl:
            type: string
            format: uri-reference
          scopes:
            $ref: '#/$defs/map-of-strings'
        required:
          - tokenUrl
          - scopes
        $ref: '#/$defs/specification-extensions'
        unevaluatedProperties: false

      authorization-code:
        $comment: references are resolved against the matching and de-templated server url
        type: object
        properties:
          authorizationUrl:
            type: string
            format: uri-reference
          tokenUrl:
            type: string
            format: uri-reference
          refreshUrl:
            type: string
            format: uri-reference
          scopes:
            $ref: '#/$defs/map-of-strings'
        required:
          - authorizationUrl
          - tokenUrl
          - scopes
        $ref: '#/$defs/specification-extensions'
        unevaluatedProperties: false

      device-authorization:
        $comment: references are resolved against the matching and de-templated server url
        type: object
        properties:
          deviceAuthorizationUrl:
            type: string
            format: uri-reference
          tokenUrl:
            type: string
            format: uri-reference
          refreshUrl:
            type: string
            format: uri-reference
          scopes:
            $ref: '#/$defs/map-of-strings'
        required:
          - deviceAuthorizationUrl
          - tokenUrl
          - scopes
        $ref: '#/$defs/specification-extensions'
        unevaluatedProperties: false

  security-requirement:
    $comment: https://spec.openapis.org/oas/v3.2#security-requirement-object
    type: object
    additionalProperties:
      type: array
      items:
        type: string

  specification-extensions:
    $comment: https://spec.openapis.org/oas/v3.2#specification-extensions
    patternProperties:
      '^x-': true

  examples:
    properties:
      example: true
      examples:
        type: object
        additionalProperties:
          $ref: '#/$defs/example-or-reference'
    not:
      required:
        - example
        - examples

  map-of-strings:
    type: object
    additionalProperties:
      type: string

  styles-for-form:
    if:
      properties:
        style:
          const: form
      required:
        - style
    then:
      properties:
        explode:
          default: true
    else:
      properties:
        explode:
          default: false