Skip to main content

ADR-013: Signal Schema Enforcement in OpenAPI

Status: Accepted Date: 2026-03-25 Relates to: ADR-003 (Trust Signal Taxonomy)

Context​

The trust signal taxonomy (ADR-003) defines five reference signal types (identity, reputation, compliance, recourse, contact) with typed data schemas in trust-signals.md. The OpenAPI spec defined standalone data schemas (IdentityData, ReputationData, etc.) but left TrustSignal.data as a generic type: object with additionalProperties: true. Code generators and API validators accepted any payload shape for any signal type, causing drift between the machine-readable contract and the prose specification.

Decision​

Use a discriminated union with an explicit extension pattern in the OpenAPI spec:

  1. Each reference signal type gets a full signal schema (e.g., IdentitySignal) that pairs the envelope (type, verifiedAt) with its typed data schema via $ref.
  2. A CustomSignal schema accepts authority-defined extensions with freeform data.
  3. The TrustSignal schema uses oneOf with a discriminator on the type property, mapping each reference type string to its signal schema.
  4. The discriminator mapping covers only reference types. Unknown types match the CustomSignal branch.

Options Considered​

A. Pure discriminated union. Map every type value to a specific schema. Rejects any type not listed — breaks the open taxonomy from ADR-003.

B. Discriminated union with extension pattern (chosen). Reference types get strict schemas. A catch-all CustomSignal preserves extensibility. The not constraint on CustomSignal.type prevents overlap with reference types, directing validators to the correct branch.

C. Generic data field with prose pointer. Keep TrustSignal.data as a generic object and document the schemas in prose only. Rejected — tooling cannot enforce correctness, so reference signal payloads drift across implementations.

Consequences​

  • Code generators produce typed signal models for all five reference types
  • API validators reject malformed data for reference signal types
  • Custom signal types remain valid — the open taxonomy (ADR-003) is preserved
  • Adding a new reference type requires a new signal schema, a discriminator mapping entry, and a not enum update in CustomSignal
  • OpenAPI 3.0-only tools may not fully support the not constraint or single-value enum discriminators — 3.1.0 is required

References​