Schema Registry

MolnOS Schema Registry provides a lightweight, built-in schema registry for defining and validating event contracts. Schemas are first-class resources—managed independently of functions—enabling schema evolution without redeploying code.

Features

Versioned Event Schemas

Define the expected shape of your events as schemas. Each update creates a new version, giving you a full history of how event contracts evolve over time.

Explicit Validation

Functions validate event data on demand using schemas.validate(). Validation is never implicit or automatic—your code decides when and whether to validate, keeping behavior transparent and predictable.

Decoupled from Functions

Schemas are standalone resources. Multiple functions can reference the same schema. Schemas can evolve independently of the functions that use them.

Lightweight Validation Engine

The built-in validator checks property types, required fields, and additional properties without requiring external libraries. Covers the common cases without bloat.

Common Use Cases

• Event contract enforcement: Validate event payloads before emitting them to catch malformed data early
• API input validation: Validate incoming request bodies against known schemas
• Schema evolution tracking: See how event contracts change over time via versioning
• Documentation: Schemas serve as machine-readable documentation of your event contracts

How It Works

API

Schemas are managed through the HTTP API at /schemas endpoints.

Create a Schema

POST /schemas

{
  "name": "order-created",
  "description": "Emitted when a new order is placed",
  "schema": {
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "currency": { "type": "string" }
    },
    "required": ["orderId", "amount", "currency"],
    "additionalProperties": false
  }
}

Schema names must be kebab-case (lowercase alphanumeric and hyphens), between 2 and 100 characters.

List Schemas

GET /schemas

Returns all schemas with their current versions.

Get a Schema

GET /schemas/:name
GET /schemas/:name/:version

Returns the schema. If no version is specified, returns the latest version.

Update a Schema

PUT /schemas/:name

Updates the schema definition and increments the version number:

{
  "description": "Emitted when a new order is placed (v2: added status)",
  "schema": {
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "currency": { "type": "string" },
      "status": { "type": "string" }
    },
    "required": ["orderId", "amount", "currency", "status"],
    "additionalProperties": false
  }
}

Delete a Schema

DELETE /schemas/:name

Removes a schema from the registry.

Using Schemas in Functions

Functions access the schema registry through the schemas binding.

Binding Configuration

{
  "name": "create-order",
  "code": "...",
  "bindings": [
    {
      "service": "schemas",
      "permissions": [{ "actions": ["validate"] }]
    },
    {
      "service": "events",
      "permissions": [{ "actions": ["emit"], "targets": ["order-created"] }]
    }
  ]
}

Validating Data

export async function handler(request, context) {
  const { schemas, events } = context.bindings;
  const data = request.body;

  // Validate against the latest version
  const check = schemas.validate(data, 'order-created');

  if (!check.valid) {
    return {
      statusCode: 400,
      body: { errors: check.errors }
    };
  }

  // Data is valid — emit the event
  await events.emit('order-created', data);

  return {
    statusCode: 200,
    body: { success: true }
  };
}

Pinning to a Specific Version

const check = schemas.validate(data, 'order-created', 2);

Validation Result Shape

// Valid
{ valid: true }

// Invalid
{
  valid: false,
  errors: [
    { path: "amount", message: "Expected type 'number', got 'string'" },
    { path: "currency", message: "Missing required field 'currency'" }
  ]
}

Schema Definition Format

Schemas define properties with types:

{
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" },
    "active": { "type": "boolean" },
    "tags": { "type": "array" },
    "address": { "type": "object" }
  },
  "required": ["name", "age"],
  "additionalProperties": false
}

Supported types: string, number, boolean, array, object

required: Array of property names that must be present in the data.

additionalProperties: When set to false, any properties not defined in the schema will produce a validation error.

Permissions

• schemas.schema.create - Create new schemas
• schemas.schema.read - View schemas
• schemas.schema.update - Update existing schemas
• schemas.schema.delete - Delete schemas

The schemas.validate() call in functions does not require a separate permission—it’s an in-process read operation covered by the schemas binding declaration.