How to define UUID property in JSON Schema and Open API (OAS)

Question

When using JSON Schema and Open API specification (OAS) to document a REST API, how do I define the UUID property?

Solution 1

There's no built-in type for UUID, but the OpenAPI Specification suggests using

type: string
format: uuid

From the Data Types section (emphasis mine):

Primitives have an optional modifier property: format. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string-valued property, and can have any value. Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification.

For example, Swagger Codegen maps format: uuid to System.Guid in C# or java.util.UUID in Java. Tools that don't support format: uuid will handle it as just type: string.

Solution 2

The only way I found so far is to manually specify the RegEx pattern as reusable schema component:

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

But, I would definitely want to use a more standardized approach.

Solution 3

Since the question was originally asked the JSON Schema spec has been extended to provide built-in support for specifying and validating that a JSON field of type string is a UUID - specifically that it adheres to the format of a UUID as defined by RFC4122, e.g. “f81d4fae-7dec-11d0-a765-00a0c91e6bf6”.

The support was added in JSON Schema spec version 2019-09 (previously known as draft-08). The JSON Schema Validation component spec was extended such that the existing ‘format' keyword that can be specified for schema fields of type string now supports a new built-in format named "uuid".

The example JSON schema below declares a (mandatory) field named "id" of type string that must be formatted as 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"]
}

Note that at the time of writing, the section of the JSON Schema user guide ("Understanding JSON Schema") covering examples of built-in string validation - JSON Schema Reference > Type-specific keywords > string > Format - doesn’t mention UUID supports, as it’s out of date - it currently only describes JSON Schema draft-7.

For the Java developers among you, the RFC4122 format used by JSON schema is compatible with the string representation of Java’s UUID class - it’s Javadoc also mentions RFC 4122.

For more details see -

• The JSON Schema Validator spec section 7. A Vocabulary for Semantic Content With “format” > 7.3. Defined Formats > 7.3.5. Resource Identifiers - The official spec.
• This GitHub issue https://github.com/json-schema-org/json-schema-spec/issues/542 (01/2018) requested that support be added. And the enhancement was duly implemented in 03/2019. See pull request https://github.com/json-schema-org/json-schema-spec/pull/715.