Schemas

Schema registration and lifecycle management. Schemas define the structure documents must follow (JSON Schema Draft 7).

Quick Reference

Method	Path	Summary
POST	/api/v1/schemas	Register a new schema
GET	/api/v1/schemas/{schemaRef}	Retrieve a schema
PUT	/api/v1/schemas/{schemaRef}	Update a schema (new version)
GET	/api/v1/schemas/{schemaRef}/versions	List schema version history
POST	/api/v1/schemas/{schemaRef}/decommission	Decommission a schema
POST	/api/v1/schemas/{schemaRef}/reactivate	Reactivate a decommissioned schema

POST

/api/v1/schemas

Request Body

Field	Type	Required	Description
ref	string	Yes	Unique schema reference identifier
schema	object	Yes	JSON Schema Draft 7 object

Response

201 Created 400 Bad Request 409 Conflict (ref exists)

{
  "ref": "temperature-sensor-v1",
  "version": 1
}

Note: Properties annotated with "identityKind": "primary-key" or "parent-key" define the D-Id extraction strategy for documents validated against this schema.

GET

/api/v1/schemas/{schemaRef}

Retrieve the current version of a registered schema.

Response

200 OK 404 Not Found

{
  "ref": "temperature-sensor-v1",
  "version": 2,
  "status": "active",
  "schema": { ... }
}

PUT

/api/v1/schemas/{schemaRef}

Update an existing schema. Creates a new version; previous versions are retained in history.

Request Body

Field	Type	Required	Description
schema	object	Yes	Updated JSON Schema Draft 7 object

Response

200 OK 404 Not Found

{
  "ref": "temperature-sensor-v1",
  "version": 2
}

GET

/api/v1/schemas/{schemaRef}/versions

List all historical versions of a schema.

Response

200 OK 404 Not Found

{
  "ref": "temperature-sensor-v1",
  "versions": [
    { "version": 1, "createdAt": "2026-07-17T10:00:00Z" },
    { "version": 2, "createdAt": "2026-07-18T14:30:00Z" }
  ]
}

POST

/api/v1/schemas/{schemaRef}/decommission

Prevent the schema from being assigned to new Document_Types. Existing assignments continue to work.

Response

200 OK 404 Not Found

{
  "ref": "temperature-sensor-v1",
  "status": "decommissioned"
}

POST

/api/v1/schemas/{schemaRef}/reactivate

Reactivate a decommissioned schema, allowing new Document_Type assignments again.

Response

200 OK 404 Not Found

{
  "ref": "temperature-sensor-v1",
  "status": "active"
}