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

Question

使用JSON Schema和Open API规范(OAS)来记录REST API时,如何定义UUID属性？

Answer 1

typeUUID 没有内置功能,但OpenAPI规范建议使用

type: string
format: uuid

从数据类型部分(强调我的):

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

例如,Swagger Codegen映射format: uuid到System.GuidC#或java.util.UUIDJava.不支持的工具format: uuid将只处理它type: string.

Answer 2

由于最初提出该问题，JSON Schema 规范已扩展为提供内置支持，用于指定和验证字符串类型的 JSON 字段是 UUID - 特别是它遵守RFC4122定义的 UUID 格式，例如“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 用户指南的部分（“了解 JSON Schema”）涵盖了内置字符串验证的示例 - JSON 模式参考 > 类型特定的关键字 > 字符串 >格式- 没有提到 UUID支持，因为它已经过时了——它目前只描述了 JSON Schema 草案 7。

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

更多详情请见——

• JSON Schema Validator 规范第 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。

Answer 3

到目前为止，我发现的唯一方法是手动将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}'

但是，我绝对希望使用更标准化的方法。