Schemas
The schemas/ directory contains JSON Schema files that mirror the public TypeScript surface of the SDK. These schemas are committed to the repository and used for CI validation, codegen, and agent grounding.
Schema Files
| File | Title | Source TypeScript | Description |
|---|---|---|---|
config.schema.json | ChatClientConfig | src/core/createChatClient.ts | Configuration accepted by createChatClient. |
messages.schema.json | ChatMessage and ChatMessagePart | src/messages/types.ts | Message envelope and all part variants. Each part extends BasePart with a stable id. |
events.schema.json | TransportEvent | src/messages/types.ts | Discriminated union of SDK transport events (the wire protocol). |
errors.schema.json | ChatSdkError | src/errors/errorCodes.ts | Error taxonomy with codes, severity, retryability, and metadata. |
tools.schema.json | Tool definition | src/tools/defineClientTool.ts, src/tools/defineServerTool.ts | Client and server tool schemas. The kind discriminator selects browser (client) vs. backend (server). |
transport.schema.json | TransportContract | src/transport/ChatTransport.ts, src/transport/recoveryPolicy.ts | Transport interface, capabilities, and recovery policy. |
governance.schema.json | DataGovernance | src/governance/types.ts | Data governance lifecycle: consent, retention, export, audit. Includes computer-use policy and commerce strict mode. |
identity.schema.json | ChatIdentity | src/identity/types.ts | Identity and conversation continuity primitives. |
a2ui.schema.json | A2UI v0.9 SDK envelopes | src/a2ui/types.ts | Agent-to-UI envelope schemas. Component-level catalog validation belongs to A2UI catalogs/renderers. |
ui-catalog-manifest.schema.json | A2UI catalog component manifest | src/a2ui/catalog/* | Per-component manifest format (frame factory, schema, action policy, integrity hash, lifecycle). |
ui-catalog-registry.schema.json | A2UI catalog registry | scripts/build-ui-catalog-registry.ts | Aggregated registry of all installed catalog components. |
rich-content.schema.json | Rich content payloads | src/rich-content/* | Built-in rich content families and the negotiation surface (PartFamilyCapability, ClientCapabilityDoc, ServerCapabilityDoc). |
product-analytics.schema.json | ProductAnalyticsEvent | src/analytics/productAnalytics.ts | Discriminated union of product analytics journey events. Includes purchase_completed, six agent_* variants, three a2ui_catalog_* variants, and signal events. |
agent-graph.schema.json | Agent graph definition | src/agents/types.ts | Router, specialist, intent, and graph topology types. |
computer-use.schema.json | Computer-use protocol | src/server/computerUse/* | Computer-use session state, action types, audit envelope, and stream signature scheme. |
permissions.schema.json | Permissions | src/permissions/types.ts | PermissionManager request, snapshot, and provider contract. |
eval-scenario.schema.json | Eval scenario | src/eval/types.ts | Scenario file format (.scenario.ts and .scenario.yaml). |
eval-report.schema.json | Eval report | src/eval/types.ts | JSON report emitted by gecx eval --json. |
eval-config.schema.json | Eval config | src/eval/types.ts | Scorer registry and judge provider configuration. |
walkthrough.schema.json | Walkthrough artifact | src/cli/walkthrough/* | Cross-agent "show your work" artifact format. |
All source paths above are relative to packages/gecx-chat/.
CI Enforcement
CI validates that schemas stay in sync with the TypeScript source. When you change a public type, update the corresponding schema file. The build will fail if schema and source drift apart.
Accessing Schemas at Runtime
Schemas are available as a package export:
import configSchema from 'gecx-chat/schemas/config.schema.json';
Source:
docs/reference/schemas.md