如何在JSON Schema和Open API（OAS）中定义UUID属性

Question

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

- Slava Fomin II

---

另请参见：https://github.com/json-schema-org/json-schema-spec/issues/542和https://github.com/json-schema-org/json-schema-spec/pull/715 - Christophe Roussy

Answer 1

没有针对UUID的内置type，但是OpenAPI规范建议使用

type: string
format: uuid

以下内容来自于 数据类型 部分（我加粗了）：

原始类型具有可选的修饰符属性：format。OAS使用几种已知格式来详细定义所使用的数据类型。然而，为了支持文档需求，format属性是一个开放的字符串值属性，可以具有任何值。即使未被此规范定义，也可以使用例如"email"、"uuid"等格式。

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

- Helen

---

这仅适用于OpenAPI 3.0，不适用于OpenAPI 3.1或更高版本。 - Relequestual

@Relequestual，您是指自JSON Schema 2019-09以来，“format”已成为注释而不是断言的事实吗？还是其他什么？ - Helen

此外，OpenAPI 3.1 充分使用 JSON Schema，而 OpenAPI 3.0 使用自己的模式格式。截至 JSON Schema 2020-12（这是 OAS 3.1 使用的版本），format 仅为注释，但如果您使用“格式断言词汇”的方式定义 JSON Schema 方言，则可以使用 format 的断言版本。 - Relequestual

Answer 2

到目前为止，我找到的唯一方法是手动将正则表达式模式指定为可重用的模式组件：

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

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

- Slava Fomin II

---

我可以建议添加字符串定界符：pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} - Ktipr

uuid规范中的破折号是可选的，因此可能是 pattern: '^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$' 和 minlength: 32。 - Papooch

@Papooch，你有关于连字符可选性的来源吗？我无法验证该说法，但对这样更紧凑的表示方法很感兴趣。RFC4122直接在ABNF中包含了连字符，ITU建议X667表示连字符“应”被包括在内。 - hiergiltdiestfu

@hiergiltdiestfu 我错了。看来规范不允许省略连字符，但是我使用的大多数消耗 UUID 的系统都允许它，所以这是我的假设。如果您对为您的系统提供紧凑表示的 UUID 感兴趣，请查看 https://www.npmjs.com/package/short-uuid - Papooch

@Papooch 看起来已经是长度至少为32的结果了，这是由正则表达式决定的。 啊哈，这是用于某个奇怪的工具。 - Lukas Salich

Answer 3

自从最初提出这个问题以来，JSON Schema规范已经扩展，提供了内置的支持，用于指定和验证JSON字符串字段是否为UUID类型，特别是符合RFC4122定义的UUID格式，例如“f81d4fae-7dec-11d0-a765-00a0c91e6bf6”。 这项功能是在JSON Schema规范版本2019-09（先前称为draft-08）中添加的。 JSON Schema验证组件规范被扩展，以使现有的“format”关键字可以针对字符串类型的模式字段指定新的内置格式，名为“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用户指南（"理解JSON Schema"）中涵盖内置字符串验证示例 - JSON Schema参考>类型特定关键字>字符串>格式 - 没有提到UUID支持，因为它已经过时了，它目前只描述了JSON Schema draft-7。 对于Java开发人员，JSON模式使用的RFC4122格式与Java的UUID类的字符串表示形式兼容 - 它的Javadoc也提到了RFC 4122。 更多细节请参见-

• JSON Schema验证器规范第7节。用于“格式”的语义内容词汇表> 7.3.定义的格式> 7.3.5.资源标识符 - 正式规范。
• 这个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。

- Neil Brown

---

除非我漏看了什么明显的东西，否则UUID格式并未在2019年09月得到实现。请参见此示例，即使ID不是UUID也可以成功验证 - https://www.jsonschemavalidator.net/s/lWxTWkoP - David Gard

@DavidGard - 您的评论是最近的，但似乎现在已经添加了UUID？ {"id": '9151f21f-43ae-43b4-92f3-f4af67cdf544'} 可以验证...从该UUID中删除任何内容或用垃圾替换它，现在会导致验证失败。 - some bits flipped