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
- UUID in JavaScript — uuid package and validation
- UUID Security — v7 timestamp exposure in API responses
- UUID Testing Strategies — mocking UUIDs in API tests
External references
- OpenAPI 3.1 data types specification
- OpenAPI Generator
- AJV JSON schema validator
- RFC 9562 — UUID standard
- uuid npm package
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.