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: object|string|integer|number|array|boolean
  format: int32|int64|float|double|password|date|email|file|uuid
  properties:
    color:
      type: string
    size:
      type: integer
      format: int32
      minimum: 0
      maximum: 100
    weight:
      type: number
      format: double
  required:
    - color
    - size
    - weight
  description:
  discriminator:
  externalDocs:
  example:

A Go type is generated for a schema 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. Alias types are generated: a custom-named typed for integer or string can be generated.

Both the types and their fields are implicitly exported with oapi-codegen, they get names that start with upper case characters, even if they are declared with lower case characters in the OpenAPI specification.

type

One of the supported data types ("object", "string", "integer", "number", "array", "boolean", etc.):

OpenAPI Data Types

format

One of the supported formats ( "int32", "int64", "float", "double", "password", "date", "email", etc.):

OpenAPI 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:          # 'color' is the name of a field of MyType
      type: string
    size:           # 'size' is the name of a field of MyType
      type: integer
      format: int32
      minimum: 0
    weight:         # 'weight' is the name of a field of MyType
      type: number
      format: double

required

An array with the name of the required fields:

MyType:
  [...]
  required:
    - color
    - size
    # weight is not required, it will be represented as a pointer

If a field is declared as "required", oapi-codegen will generate the struct corresponding to the schema with a value for that field. If the field is not among the required fields, the struct will carry a pointer instead of a the value, presumably so it can be set to nil.

type MyType struct {
	Color  string   `json:"color"`            // required field 
	Size   int32    `json:"size"`             // required field
	Weight *float64 `json:"weight,omitempty"` // not required field
}

discriminator

TODO. Also see Polymorphism below.

example

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
- name
example:
  name: Blue
  id: 1

Composition

Types can be composed with $ref:

components:
  schemas:
    Person:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        address:
          $ref: "#/components/schemas/Address"
      required:
        - firstName
        - lastName
        - address
    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        zip:
          type: integer
          format: int32
      required:
        - street
        - city
        - zip

The corresponding generated code:

type Person struct {
	Address   Address `json:"address"`
	FirstName string  `json:"firstName"`
	LastName  string  `json:"lastName"`
}

type Address struct {
	City   string `json:"city"`
	Street string `json:"street"`
	Zip    int32  `json:"zip"`
}

A <String,String> Map

components:
  schemas:
    AMap:
      type: object
      additionalProperties:
        type: string

The corresponding generated code:

type AMap map[string]string

A <String,Object> Map

components:
  schemas:
    AMap:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/MapElement"
    MapElement:
      type: object
      properties:
        color:
          type: string
        size:
          type: integer
      required:
        - color
        - size

The corresponding generated code:

type AMap map[string]MapElement
type MapElement struct {
	Color string `json:"color"`
	Size  int    `json:"size"`
}

Combining Schemas

OpenAPI 3.0 provides a set of keywords that can be used to combine schemas. These keywords can be used to compose complex schemas from components, or validate against multiple criteria. These keywords are allOf, oneOf, anyOf and not.

allOf

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#models-with-composition

allOf takes an array of object definitions that are used for independent validation - they can be used as individual types - and composes them in a single object. This is a simple composition model, it does imply hierarchy between models. To create a hierarchy, use the discriminator field. To be valid against allOf, the data provided by the client must be valid against all of the given subschemas.

allOf

TODO:

• https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/
• https://www.speakeasyapi.dev/post/openapi-tips-oneof-allof-anyof

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

Polymorphism

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

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#models-with-polymorphism-support

See discriminator above.