Skip to content
InertiaX Docs

Protocol reference

The protocol defines the serialized table response. Use the Laravel builders for application code; use these schemas and the decoder when building validation or integration tooling.

The current protocol is draft 0.1.2 with checksum 5d2f50a049a66c2cb7ec82349c4f5d126b1f4a1d9ddc0387f497c323f270131f.

Declare @inertiax/protocol as a direct dependency if your source imports it.

Shipped reference files

Section titled “Shipped reference files”

The installed @inertiax/protocol package exposes the maintained contract without repository access:

Package subpath Purpose
@inertiax/protocol/schemas/envelope.schema.json Envelope entry schema
@inertiax/protocol/schemas/table.schema.json Complete Table component schema
@inertiax/protocol/schemas/common.schema.json Shared JSON definitions
@inertiax/protocol/fixtures/manifest.json Accepted and rejected fixture inventory
@inertiax/protocol/fixtures/valid/minimal.json Smallest complete valid Table example
@inertiax/protocol/fixtures/valid/custom-type.json Namespaced custom leaf example
@inertiax/protocol/VERSION and @inertiax/protocol/CHECKSUM Installed artifact identity

Use these package subpaths in validators, tests, or tooling. Application code normally needs only the root package exports.

Envelope

Section titled “Envelope”

Every payload contains a protocol version and a component:

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

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

Table component shape

Section titled “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;
  • 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 local state, not server query state.

data.rowKey must name a declared Column even when rows is empty. Each row must contain that cell, and its value must be a string or JavaScript-safe integer. Laravel transports larger integer identities as exact decimal strings so JavaScript does not silently change them.

Validation boundary

Section titled “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';


export function decodeInput(input: unknown) {
  return decodeEnvelope(input);
}

decodeEnvelope returns a deeply immutable clone. It throws ProtocolDecodeError with:

  • INERTIAX_PROTOCOL_VERSION_UNSUPPORTED when the received major is not supported;
  • INERTIAX_PROTOCOL_DECODE_FAILED for invalid JSON-domain values, malformed known fields, or invalid Table semantics.

The error includes path, structured diagnostics, the supported version, and available received version/component context. Catch it only when the application can add useful context or recovery; do not continue with the rejected input.

Compatibility rules

Section titled “Compatibility rules”
  • 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 and filter types and custom clause keys must be namespaced as vendor/name.
  • Unknown custom leaf identifiers remain valid protocol data, but the React renderer needs a matching registration or uses its configured diagnosed fallback.

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.

Integration tooling

Section titled “Integration tooling”

Use the exported TypeScript declarations and runtime decoder; do not copy protocol types into application code. Validate unknown input before creating a session. See Direct React rendering for custom integrations and their ownership contracts.