Protocol reference

The protocol is the public seam between a producer and a renderer. Normal application code should use Laravel builders and React components rather than constructing envelopes by hand.

The sole editable protocol authority is packages/protocol. Its JSON Schemas define structure and its manifest-indexed fixtures define accepted and rejected examples. Generated TypeScript declarations, runtime schema, deterministic bundle, checksum, and Laravel snapshot must agree with that source.

The current protocol is draft 0.1.2 with checksum 5d2f50a049a66c2cb7ec82349c4f5d126b1f4a1d9ddc0387f497c323f270131f.

Envelope

Every payload has exactly the governed envelope shape:

{
  "protocolVersion": "0.1.2",
  "component": {
    "type": "table",
    "id": "users"
  }
}

The abbreviated component above is explanatory, not a valid complete Table. Use fixtures/valid/minimal.json for executable minimal input and schemas/envelope.schema.json for the complete contract.

Table component shape

A complete Table component carries:

• a stable type: "table" and instance id;
• Column and Filter definitions;
• capabilities for pagination, sorting, selection, filter mode, and refresh;
• canonical server state for pagination, ordered sorting, recursive filters, and search;
• result totals and last-page information;
• a rowKey and row-oriented data.rows.

Columns contain definitions only. Each row cell is a payload with value plus optional icon, variant, and meta. Capabilities constrain which state transitions are valid.

Selection and Column visibility are portable client state. They are not part of the server’s query state and do not authorize an action.

Validation boundary

Consumers decode unknown input before creating a runtime session. Producers validate the complete envelope before returning it. A malformed known field reports schema-path context; an unsupported protocol version fails before a transformation or render.

Use decodeEnvelope when an application or integration receives unknown protocol data directly:

import { decodeEnvelope } from '@inertiax/protocol';

const envelope = decodeEnvelope(input);

Evolution and validation

• Protocol versions are independent from npm and Composer package versions.
• Unsupported versions fail before transformation or rendering.
• Known malformed fields fail with schema-path diagnostics.
• Custom column, filter, Clause, and value identifiers must be namespaced as vendor/name.
• Protocol changes begin in schemas and fixtures, then regenerate/verify derived artifacts.
• Laravel consumes a checksum-locked generated snapshot; it is never another editable protocol source.

A package patch or minor release does not imply a protocol change. Conversely, protocol evolution may require coordinated compatible package releases while their version numbers remain different.

For integration authors

Use the exported TypeScript declarations and runtime decoder from @inertiax/protocol. Do not copy types into an integration package. If you produce envelopes outside Laravel, validate them against the canonical schema and fixtures and preserve the exact semantics of state, capabilities, row identity, and custom namespaced identifiers.

Run pnpm --filter @inertiax/protocol verify to verify the canonical package. From the monorepo root, composer --working-dir=packages/laravel protocol:verify verifies the Laravel package’s locked snapshot, while pnpm protocol:verify verifies both authorities together.