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

Posted 2023-02-15

【中文标题】如何在 JSON Schema 和 Open API (OAS) 中定义 UUID 属性

【英文标题】：How to define UUID property in JSON Schema and Open API (OAS)

【发布时间】：2018-10-16 16:36:47

【问题描述】：

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

【问题讨论】：

另见：github.com/json-schema-org/json-schema-spec/issues/542 和 github.com/json-schema-org/json-schema-spec/pull/715

【参考方案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

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

【讨论】：

我可以建议添加字符串分隔符吗：pattern: '[0-9a-f]8-[0-9a-f]4-[0-9a-f]4-[0-9a-f]4-[0-9a-f]12

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

这是提示我需要解决 openapi 工具验证 UUID 格式的问题。我们的实现是添加一个前缀，例如，Gcc55edda-7acd-4128-877d-02b94430896a。仅使用format: uuid 会使路径参数使用它的工具失败。我使用这个答案创建了一个“自定义 UUID”！谢谢！

模式是否需要值（想象 minLength 不存在）？

【参考方案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。

【讨论】：

除非我遗漏了一些明显的东西，否则 UUID 格式并未在 2019-09 年实施。请参阅此示例，即使 ID 不是 UUID，它也会成功验证 - jsonschemavalidator.net/s/lWxTWkoP

@DavidGard - 您的评论是最新的 - 但现在似乎已经添加了 UUID？ "id": '9151f21f-43ae-43b4-92f3-f4af67cdf544' 验证...从该 UUID 中删除任何内容，或将其替换为垃圾，现在验证失败。

【参考方案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 处理。

【讨论】：

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

@Relequestual 你的意思是自 JSON Schema 2019-09 以来，format 是注释而不是断言？还是别的什么？

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