Envelope schemas

The canonical TypeScript definition of every Matrix envelope is MxEnvelope in projects/matrix-3/packages/core/src/engine/messaging/MxEnvelope.ts. This page restates it in TypeScript and JSON Schema, and gives the schemas for the response and error variants.

TypeScript: MxEnvelope (verbatim)

// projects/matrix-3/packages/core/src/engine/messaging/MxEnvelope.ts
export interface MxEnvelope {
  /** Operation name: domain op ("ExpandDir") or system op ("$join", "$reply") */
  op: string;

  /** The actual message data */
  payload: unknown;

  /** For contracted interface calls (e.g., "FsDaemon@1") */
  iface?: string;

  /** For request/reply: unique correlation identifier */
  correlationId?: string;

  /** For request/reply: reply-to inbox topic */
  replyTo?: string;

  /** Lamport timestamp for causal ordering */
  lamport?: number;

  /** Sender mount path */
  from?: string;

  /** Trace context — propagated across actor messages for distributed tracing */
  traceId?: string;
  spanId?: string;
  parentSpanId?: string;
}

JSON Schema: request envelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.matrix-protocol/envelopes/request.json",
  "type": "object",
  "required": ["op", "payload"],
  "additionalProperties": false,
  "properties": {
    "op": {
      "type": "string",
      "description": "Operation name. Domain ops: '<area>.<verb>'. System ops: '$<verb>'."
    },
    "payload": {
      "description": "Op-specific input. Schema varies by op."
    },
    "iface": {
      "type": "string",
      "description": "Optional contracted interface name, e.g. 'FsDaemon@1'."
    },
    "correlationId": {
      "type": "string",
      "minLength": 1,
      "description": "Required for request/reply. Unique per request, reply-matchable."
    },
    "replyTo": {
      "type": "string",
      "minLength": 1,
      "description": "Required for request/reply. Semantic reply subject, e.g. '$replies.<cid>'."
    },
    "lamport": {
      "type": "integer",
      "minimum": 0,
      "description": "Logical clock for causal ordering."
    },
    "from": {
      "type": "string",
      "description": "Sender mount path. Informational; not trusted for authorization."
    },
    "traceId":      { "type": "string", "description": "Trace id (W3C trace context)." },
    "spanId":       { "type": "string", "description": "Span id." },
    "parentSpanId": { "type": "string", "description": "Parent span id." }
  }
}

JSON Schema: response envelope

{
  "$id": "https://docs.matrix-protocol/envelopes/response.json",
  "type": "object",
  "required": ["op", "correlationId", "payload"],
  "properties": {
    "op": {
      "const": "$reply",
      "description": "Always '$reply' for response envelopes."
    },
    "correlationId": {
      "type": "string",
      "description": "Echoed from the request envelope."
    },
    "payload": {
      "description": "The op's result. Conventionally { ok: boolean, ...result }."
    },
    "iface":        { "type": "string" },
    "lamport":      { "type": "integer", "minimum": 0 },
    "from":         { "type": "string" },
    "traceId":      { "type": "string" },
    "spanId":       { "type": "string" },
    "parentSpanId": { "type": "string" }
  }
}

JSON Schema: error payload

The error case is conveyed inside the response envelope's payload field; the wire-level envelope shape is unchanged.

{
  "$id": "https://docs.matrix-protocol/envelopes/error-payload.json",
  "type": "object",
  "required": ["ok", "error"],
  "properties": {
    "ok": {
      "const": false,
      "description": "Always false for error payloads."
    },
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    },
    "code": {
      "type": "string",
      "description": "Optional machine-readable code, e.g. 'NOT_FOUND'.",
      "enum": [
        "OK",
        "NOT_FOUND",
        "INVALID_ARGUMENT",
        "UNAUTHENTICATED",
        "PERMISSION_DENIED",
        "UNAVAILABLE",
        "INTERNAL",
        "DEADLINE_EXCEEDED",
        "ALREADY_EXISTS",
        "RESOURCE_EXHAUSTED",
        "FAILED_PRECONDITION"
      ]
    },
    "statusCode": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599,
      "description": "Optional HTTP-style status when the op maps to HTTP."
    },
    "details": {
      "description": "Op-specific structured error detail."
    }
  }
}

Status: target state for the code enum. The standardized error-code list is documented in Error codes; not every actor today emits a code field.

Conventions for payload shape

Most payloads follow { ok: boolean, ...result }:

Field	Convention
ok: true	success
ok: false, error: string	failure
count: number, items: Array<...>	list responses
cursor: string	pagination cursor
idempotencyKey: string	optional caller-supplied key for write ops

Source: CLAUDE.md Rule 9: "Every list op returns cursor-based pagination. Every write op accepts optional idempotencyKey."

See also

• Request envelope — every field explained.
• Response envelope — success shape.
• Error envelope — error shape.
• Error codes — the catalog the code enum draws from.
• Compatibility rules — how schemas evolve.