OpenAPI Specification Schemas

External

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject
• https://tools.ietf.org/html/draft-bhutton-json-schema-00
• https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00

Internal

• OpenAPI Specification

Overview

The /components/schemas section of the OpenAPI specification defines reusable types that are used as input and output data types. These types can represent objects, but also primitives and arrays. The specification is based on JSON Schema Specification Draft 2020-12. A client or server code generator creates programming language types from these schemas. This article is annotated with details related to how oapi-codegen generates Go code.

Schema

SchemaName
  type:
  properties:
    color:
      type: string
    size:
      type: integer
      format: int32
    weight:
      type: number
      format: double
  required:
    - color
    - size
    - weight
  format:
  description:
  discriminator:
  externalDocs:

type

One of the supported data types.

properties

For a schema of type object, properties contains a map whose keys are the names of the fields. Each map element must mandatorily include type and optionally format:

MyType:
  type: object
  properties:
    color: 
      type: string
    size:
      type: integer
      format: int32
    weight:
      type: number
      format: double

Code Generation

Currently, this section only refers to oapi-codegen and Go code generation.

A Go type is generated only if a schema is referred from the specification with schema.$ref. If the type is declared, but not referred, no code will be generated for it.

Example

components:
  schemas:
    Pet:
      allOf:
        - $ref: '#/components/schemas/NewPet'
        - type: object
          required:
            - id
          properties:
            id:
              type: integer
              format: int64
    NewPet:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        tag:
          type: string
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

Composition

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#composition-and-inheritance-polymorphism

allOf

Polymorphism

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#composition-and-inheritance-polymorphism

discriminator