OpenAPI (formerly Swagger) is the standard for documenting REST APIs. UUID fields appear in nearly every API — as resource IDs in path parameters, as foreign keys in request bodies, and as generated IDs in response objects. Defining them correctly in your OpenAPI 3.1 schema ensures accurate code generation, proper request validation, and self-documenting example values. This guide covers the canonical schema definitions, version-specific patterns, code generation output, and integration with popular validation libraries. The OpenAPI 3.1 specification and the uuid npm package are the primary references throughout.

Basic UUID schema definition

components:
  schemas:
    OrderId:
      type: string
      format: uuid
      description: UUID v7 primary key. Time-ordered — lexicographic sort equals creation order.
      example: "019236a7-b4f2-7000-8d3e-9c1a2b3d4e5f"

    Order:
      type: object
      required: [id, customerId, total]
      properties:
        id:
          $ref: '#/components/schemas/OrderId'
        customerId:
          type: string
          format: uuid
          description: UUID v4 — customer account ID (no timestamp exposure)
          example: "a8098c1a-f86e-4da4-bd1a-00112444be1e"
        total:
          type: number
          format: float

Using a named OrderId schema component lets you reference it throughout the spec — changes propagate automatically to all endpoints that use that type.

UUID v7-specific pattern constraint

To enforce UUID v7 format at the schema level:

components:
  schemas:
    UuidV7:
      type: string
      format: uuid
      pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
      description: >
        RFC 9562 UUID v7. The version nibble (position 14) is always '7'.
        The variant nibble (position 19) is 8, 9, a, or b.
        Lexicographic sort order equals creation time order.
      example: "019236a7-b4f2-7000-8d3e-9c1a2b3d4e5f"

    UuidV4:
      type: string
      format: uuid
      pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
      description: RFC 9562 UUID v4. 122 bits of cryptographic randomness, no timestamp.
      example: "a8098c1a-f86e-4da4-bd1a-00112444be1e"

Pattern validation is supported by AJV (Another JSON Validator), OpenAPI Generator, and most OpenAPI 3.1-compliant validators.

Path parameter and query parameter schemas

paths:
  /orders/{orderId}:
    get:
      summary: Retrieve an order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UuidV7'
          description: UUID v7 primary key of the order
      responses:
        '200':
          description: Order found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid UUID format

  /orders:
    get:
      summary: List orders with cursor pagination
      parameters:
        - name: after
          in: query
          schema:
            $ref: '#/components/schemas/UuidV7'
          description: Return orders created after this UUID v7 cursor
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20

UUID v7 cursors for pagination are self-describing — the cursor encodes the creation time of the last record seen, enabling the server to execute a simple WHERE id > $cursor query.

Request body with UUID fields

components:
  schemas:
    CreateOrderRequest:
      type: object
      required: [customerId, items]
      properties:
        id:
          $ref: '#/components/schemas/UuidV7'
          description: >
            Optional client-assigned UUID v7. If omitted, the server generates one.
            If provided, the server validates format and checks for collision.
          readOnly: false
        customerId:
          $ref: '#/components/schemas/UuidV4'

Allowing client-assigned IDs enables optimistic UI patterns — the client generates a UUID v7, uses it immediately in local state, and sends it to the server for persistence. Server-side collision detection returns HTTP 409 Conflict if the ID already exists.

Code generation output

Running OpenAPI Generator against this spec produces native UUID types:

TypeScript (openapi-typescript):

export interface Order {
  id: string;        // format: uuid → string in TypeScript
  customerId: string;
  total: number;
}

Java (Spring):

public class Order {
    private UUID id;
    private UUID customerId;
    private Float total;
}

C# (ASP.NET):

public class Order {
    public Guid Id { get; set; }
    public Guid CustomerId { get; set; }
    public float Total { get; set; }
}

For TypeScript, add branded types to distinguish UUID v4 from UUID v7 at compile time — the TypeScript brand pattern provides compile-time UUID type safety without runtime overhead.

Validation with Express and AJV

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv); // Adds 'uuid' format validation

const schema = {
  type: 'object',
  required: ['id', 'customerId'],
  properties: {
    id: { type: 'string', format: 'uuid',
          pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$' },
    customerId: { type: 'string', format: 'uuid' },
  }
};

const validate = ajv.compile(schema);
const valid = validate({ id: '019236a7-b4f2-7000-8d3e-9c1a2b3d4e5f', customerId: 'a8098c1a-...' });

The AJV format documentation explains that format validation requires the ajv-formats plugin and strict: false mode or explicit format enablement.

Further reading

External references

Frequently asked questions

What is the correct OpenAPI format for a UUID field?

Use type: string with format: uuid as defined in the OpenAPI 3.1 data types specification. This maps to the 36-character hyphenated UUID string (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). The format: uuid hint instructs code generators to use the appropriate UUID type in the target language — UUID in Java and Kotlin, Guid in C#, string with validation in TypeScript. Validators that support OAS 3.1 fully will enforce the 8-4-4-4-12 hexadecimal format defined in RFC 9562.

How do I distinguish UUID v4 from UUID v7 in an OpenAPI schema?

OpenAPI 3.1's built-in format: uuid does not discriminate between versions. To enforce a specific version, add a pattern constraint. For UUID v7: pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$". The 7 at position 14 enforces the version digit; [89ab] at position 19 enforces the RFC 9562 variant bits. Use description to document that the field is UUID v7 even if the pattern is not enforced by your validation library.

Which OpenAPI code generators support the uuid format natively?

OpenAPI Generator maps format: uuid to native UUID types in Java (UUID), C# (Guid), Kotlin (UUID), and Swift (UUID). TypeScript generators produce string with a UUID type alias. The openapi-typescript library generates TypeScript types where format: uuid maps to string — add a branded type (type UUID = string & { __brand: 'uuid' }) for compile-time safety.