如何在 JSON Schema 和 Open API (OAS) 中定义 UUID 属性

Question

使用JSON Schema 和Open API specification (OAS) 记录REST API 时，如何定义UUID 属性？

Answer 1

到目前为止，我发现的唯一方法是将 RegEx 模式手动指定为可重用架构组件：

openapi: 3.0.1

paths:
  /transactions/:
    post:
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionId:
                    $ref: '#/components/schemas/uuid'

components:
  schemas:
    uuid:
      type: string
      pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
      # the regex above limits the length;
      # however, some tools might require explicit settings:
      minLength: 36
      maxLength: 36

但是，我肯定想使用更标准化的方法。

Answer 2

自从最初提出这个问题以来，JSON Schema 规范已被扩展为提供内置支持，以指定和验证字符串类型的 JSON 字段是否为 UUID - 特别是它遵循由定义的 UUID 格式RFC4122，例如“f81d4fae-7dec-11d0-a765-00a0c91e6bf6”。

在 JSON Schema 规范版本 2019-09（以前称为 Draft-08）中添加了支持。 JSON Schema Validation 组件规范进行了扩展，现在可以为字符串类型的架构字段指定的现有“格式”关键字现在支持名为“uuid”的新内置格式。

下面的示例 JSON 模式声明了一个名为“id”的字符串类型的（强制）字段，该字段必须格式化为 UUID -

{
  "$schema": "http://json-schema.org/draft/2019-09/schema#",
  "title": "My JSON object schema",
  "description": "Schema for the JSON representation of my JSON object.",

  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for my object. (A UUID specified by RFC4122).",
      "type": "string",
      "format": "uuid"
    }
  },
  "required": ["id"]
}

请注意，在撰写本文时，JSON Schema 用户指南 ("Understanding JSON Schema") 的部分涵盖了内置字符串验证的示例 - JSON Schema Reference > 特定于类型的关键字 > string > Format - 没有没有提到 UUID 支持，因为它已经过时了——它目前只描述 JSON Schema Draft-7。

对于你们当中的 Java 开发人员来说，JSON 模式使用的 RFC4122 格式与 Java 的 UUID 类的字符串表示兼容 - Javadoc 也提到了 RFC 4122。

更多详情见-

• JSON 模式验证器规范第 7 节。具有“格式”> 7.3 的语义内容词汇表。定义格式 > 7.3.5. Resource Identifiers - 官方规范。
• 此 GitHub 问题 https://github.com/json-schema-org/json-schema-spec/issues/542 (01/2018) 要求添加支持。该增强功能已于 03/2019 正式实施。请参阅拉取请求 https://github.com/json-schema-org/json-schema-spec/pull/715。

Answer 3

UUID 没有内置 type，但 OpenAPI 规范建议使用

type: string
format: uuid

来自Data Types 部分（强调我的）：

基元有一个可选的修饰符属性：format。 OAS 使用几种已知格式来详细定义所使用的数据类型。但是，为了支持文档需求，format 属性是一个开放的字符串值属性，并且可以具有任何值。 "email"、"uuid" 等格式即使未在本规范中定义，也可以使用。

例如，Swagger Codegen 将 format: uuid 映射到 C# 中的 System.Guid 或 Java 中的 java.util.UUID。不支持format: uuid 的工具将按type: string 处理。