Schemas API

The Schemas API manages versioned JSON Schema definitions for domain topics. Each topic can have multiple schema versions with backward compatibility enforcement.

Info

Schemas are optional payload contracts that belong to topics. To understand how topics, schemas, and mappings relate, see Core Concepts.

List Schema Versions

GET /api/schemas/:topic/versions

Returns all schema versions for a topic, scoped by application and environment.

Example:

curl http://localhost:3000/api/schemas/session.status/versions

Response:

[
  {
    "topic": "session.status",
    "version": 1,
    "schema": { "type": "object", "properties": { ... } },
    "compatibilityMode": "backward",
    "createdAt": 1710000000000
  },
  {
    "topic": "session.status",
    "version": 2,
    "schema": { "type": "object", "properties": { ... } },
    "compatibilityMode": "backward",
    "createdAt": 1710001000000
  }
]

Get Specific Version

GET /api/schemas/:topic/versions/:version

curl http://localhost:3000/api/schemas/session.status/versions/2

Get Latest Schema

GET /api/schemas/:topic/latest

Returns the most recent schema version for a topic.

Register Schema

POST /api/schemas/:topic

Request Body:

{
  "schema": {
    "type": "object",
    "properties": {
      "sessionId": { "type": "string" },
      "status": { "type": "string" },
      "campusId": { "type": "number" }
    },
    "required": ["sessionId", "status"]
  },
  "compatibilityMode": "backward"
}

The version number is assigned automatically (increments from the latest version).

Compatibility Modes:

Mode	Description
`backward`	New schema must be able to read data written by the previous version. Default.
`none`	No compatibility check — any schema is accepted.

If backward compatibility fails, the registration is rejected with a detailed error message.

Response: 201 Created with the new schema definition.

Validate Payload

POST /api/schemas/:topic/validate

Validates a payload against the latest schema for a topic.

Request Body:

{
  "payload": {
    "sessionId": "abc123",
    "status": "active",
    "campusId": 12
  }
}

Response (valid):

{
  "valid": true
}

Response (invalid):

{
  "valid": false,
  "errors": [
    {
      "path": "/sessionId",
      "message": "must be string"
    }
  ]
}

Compatibility Checking

When registering a new schema with compatibilityMode: "backward", the system checks that:

No required fields are removed
No field types are changed in incompatible ways
Existing consumers can still read payloads produced by the new schema

If the check fails, you receive a 400 error with details about which fields are incompatible.