Schema Versioning and the v Field
Palyra employs a strict versioning convention for all JSON-based envelopes. Every top-level object MUST include a v field (unsigned integer) representing the schema version schemas/generated/rust/protocol_stubs.rs#5-5.
Versioning Rules
- Mandatory Field: The
vfield is required for all envelopes (e.g.,ApprovalRecord,Canvas). - Major Versioning: The
PROTOCOL_MAJOR_VERSIONis currently set to1schemas/generated/rust/protocol_stubs.rs#5-5. - Forward Compatibility: Parsers are designed to accept higher version numbers if the structure remains compatible, but they must reject payloads missing the version field.
Envelope Formats
1. Message and Approval Envelopes
Used for auditing and security decisions. TheApprovalRecord is the primary structure for documenting policy evaluations and operator decisions.
| Field | Type | Description |
|---|---|---|
v | uint32 | Schema version (1) |
approval_id | CanonicalId | Unique ULID for the approval request |
subject_type | Enum | Type of action (Tool, Secret, Browser, etc.) |
decision | Enum | Allow, Deny, Timeout, or Error |
policy_snapshot | Object | Hash and ID of the policy evaluated |
2. A2UI and Canvas Envelopes
The Agent-to-User Interface (A2UI) uses a JSON-based state representation for rendering sandboxed web components. TheCanvas object encapsulates the state and the bundle required to render it.
Canvas State Flow
Sources: schemas/proto/palyra/v1/gateway.proto#255-266, schemas/proto/palyra/v1/gateway.proto#44-51
3. Process Runner Input
Thepalyra.process.run tool uses a specialized JSON schema to define execution parameters. This format enforces additionalProperties: false via Rust’s #[serde(deny_unknown_fields)] attribute to prevent injection of unsupported execution flags.
Sources: crates/palyra-common/src/process_runner_input.rs#5-17
Implementation and Validation
Strict Property Enforcement
To ensure security and prevent “schema creeping,” Palyra enforces strict field validation. In the Rust implementation, theProcessRunnerToolInput struct uses deny_unknown_fields to reject any JSON payload containing keys not explicitly defined in the schema crates/palyra-common/src/process_runner_input.rs#6-6.
Payload Size Caps
To prevent Denial of Service (DoS) attacks via oversized JSON payloads, the system enforces hard limits during parsing:- Process Runner Input: Capped at 32 KB fuzz/fuzz_targets/process_runner_input_parser.rs#6-6.
- Workspace Patches: Capped at 16 KB fuzz/fuzz_targets/workspace_patch_parser.rs#10-10.
- Fuzzing Limits: These caps are strictly enforced in the fuzzing harness to ensure the parser remains performant under stress fuzz/fuzz_targets/process_runner_input_parser.rs#9-11.
Data Flow: Webhook to Gateway
Webhooks arrive as signed JSON payloads and are converted into internal message formats. Webhook Validation Pipeline Sources: schemas/proto/palyra/v1/gateway.proto#16-16, fuzz/Cargo.toml#33-34Generated Stubs
JSON schemas are synchronized with Protobuf definitions. Stubs are automatically generated for multiple languages to ensure cross-platform consistency:- Rust:
protocol_stubs.rsschemas/generated/rust/protocol_stubs.rs#1-1 - Kotlin:
ProtocolStubs.ktschemas/generated/kotlin/ProtocolStubs.kt#1-1 - Swift:
ProtocolStubs.swiftschemas/generated/swift/ProtocolStubs.swift#1-1