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?

Answer 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.

Answer 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}'

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