Schema 对象

用于定义输入和输出的数据类型。这些类型可以是对象，但也可以是原始值和数组。这个对象是 JSON Schema Specification Wright Draft 00 扩展后的子集.

关于 property 的的更多信息请查看 JSON Schema Core 和 JSON Schema Validation。除非另有说明，否则 properties 定义遵循 JSON Schema。

Properties

以下 properties 是直接从 JSON Schema  提取出来的，而且遵循同样的规范：

• title
• multipleOf
• maximum
• exclusiveMaximum
• minimum
• exclusiveMinimum
• maxLength
• minLength
• pattern (This string SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect)
• maxItems
• minItems
• uniqueItems
• maxProperties
• minProperties
• required
• enum

以下 properties  是从 JSON Schema 提取出来的，但是做了一些调整以适应 OpenAPI Specification。

• type - 值必须是一个字符串，不支持以数组形式定义多个值。
• allOf - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
• oneOf - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
• anyOf - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
• not - Inline 或 referenced 的 schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
• items - 值必须是一个对象且不是一个数组。Inline 或 referenced 的 schema 必须是一个 Schema 对象且不是一个标准的 JSON Schem。. items 必须存在如果 type 的值是 array。
• properties - Property 定义必须是一个 Schema 对象 且不是一个标准的 JSON Schema (inline 或 referenced).
• additionalProperties - 值可以是 boolean 或 object. Inline 或 referenced schema 必须是一个 Schema 对象 且不是一个标准的 JSON Schema。
• description - CommonMark syntax可以被用来呈现富文本格式.
• format - 查看 Data Type Formats 以深入  了解细节。在依靠 JSON Schema 定义的格式的同时，OAS 额外提供了一些预定义的格式。
• default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. 不同于 JSON Schema，这个值必须符合定义与相同级别的 Schema 对象 中定义的类型，比如 type 是 string，那么default 可以是 "foo" 但不能是 1。

另外，任何可以使用 Schema 对象 的地方也可以使用 Reference 对象 替代。这允许引用一个定义而避免重复定义。

未在此处提及的 JSON Schema 规范中定义的其他属性将严格的不被支持。

Other than the JSON Schema subset fields, 以下字段可能会被用于后续的 schema documentation：

固定字段

字段名	类型	描述
nullable	boolean	对于定义的 schema，允许发送 null 值。默认值是 false。
discriminator	Discriminator 对象	Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See Composition and Inheritance for more details.
readOnly	boolean	仅与 Schema "properties" 定义有关。 声明此属性是 "readonly" 的。这意味着它可以作为 response 的一部分但不应该作为 request 的一部分被发送。如果一个 property 的 readOnly 被标记为 true 且在 required 列表中，required 将只作用于 response。一个 property 的 readOnly 和 writeOnly 不允许同时被标记为 true。默认值是 false。
writeOnly	boolean	仅与 Schema "properties" 定义有关。声明此 property 为 "write only"。所以它可以作为 request 的一部分而不应该作为 response 的一部分被发送。如果一个 property 的 writeOnly 被标记为 true 且在 required 列表中，required 将只作用于 request。一个 property 的 readOnly 和 writeOnly 不能同时被标记为 true。默认值是 false。
xml	XML 对象	这只能用于 properties schemas，在  root schemas 中没有效果。Adds additional metadata to describe the XML representation of this property.
externalDocs	External Documentation 对象	此 schema 附加的外部文档。
example	Any	一个用于示范此 schema 实例的示例，可以是任意格式。为了表达无法用 JSON 或 YAML 格式呈现的示例，可以使用 string 类型的值，且在必要的地方需要使用字符转义。
deprecated	boolean	表示一个 schema 是废弃的，应该逐渐被放弃使用。默认值是 false.

这个对象可能会被规范扩展扩展。

Composition and Inheritance (Polymorphism)

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

While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the discriminator field. When used, the discriminator will be the name of the property that decides which schema definition validates the structure of the model. As such, the discriminator field MUST be a required field. There are are two ways to define the value of a discriminator 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. As such, inline schema definitions, which do not have a given id, cannot be used in polymorphism.

XML Modeling

The xml property allows extra definitions when translating the JSON definition to XML. The XML 对象 contains additional information about the available options.

Schema 对象示例 s

Primitive Sample

{
  "type": "string",
  "format": "email"
}

type: string
format: email

Simple Model

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/Address"
    },
    "age": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
    }
  }
}

type: object
required:
  - name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0

Model with Map/Dictionary Properties

For a simple string to string mapping:

{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}

type: object
additionalProperties:
  type: string

For a string to model mapping:

{
  "type": "object",
  "additionalProperties": {
    "$ref": "#/components/schemas/ComplexModel"
  }
}

type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'

Model with Example

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "Puma",
    "id": 1
  }
}

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

Models with Composition

{
  "components": {
    "schemas": {
      "ErrorModel": {
        "type": "object",
        "required": [
          "message",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "code": {
            "type": "integer",
            "minimum": 100,
            "maximum": 600
          }
        }
      },
      "ExtendedErrorModel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorModel"
          },
          {
            "type": "object",
            "required": [
              "rootCause"
            ],
            "properties": {
              "rootCause": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  }
}

components:
  schemas:
    ErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
        - $ref: '#/components/schemas/ErrorModel'
        - type: object
          required:
            - rootCause
          properties:
            rootCause:
              type: string

Models with Polymorphism Support

{
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "discriminator": {
          "propertyName": "petType"
        },
        "properties": {
          "name": {
            "type": "string"
          },
          "petType": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "petType"
        ]
      },
      "Cat": {
        "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "huntingSkill": {
                "type": "string",
                "description": "The measured skill for hunting",
                "default": "lazy",
                "enum": [
                  "clueless",
                  "lazy",
                  "adventurous",
                  "aggressive"
                ]
              }
            },
            "required": [
              "huntingSkill"
            ]
          }
        ]
      },
      "Dog": {
        "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "packSize": {
                "type": "integer",
                "format": "int32",
                "description": "the size of the pack the dog is from",
                "default": 0,
                "minimum": 0
              }
            },
            "required": [
              "packSize"
            ]
          }
        ]
      }
    }
  }
}

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
        - name
        - petType
    Cat: ## "Cat" will be used as the discriminator value
      description: A representation of a cat
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            huntingSkill:
              type: string
              description: The measured skill for hunting
              enum:
                - clueless
                - lazy
                - adventurous
                - aggressive
          required:
            - huntingSkill
    Dog: ## "Dog" will be used as the discriminator value
      description: A representation of a dog
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            packSize:
              type: integer
              format: int32
              description: the size of the pack the dog is from
              default: 0
              minimum: 0
          required:
            - packSize