Skip to content

ADR-0006: Standard JSON Schema with x-protean Extensions

Status: Accepted

Date: March 2026

Context

Protean's schema generation produces JSON Schemas for domain elements. These schemas carry domain-specific metadata (element type, aggregate linkage, versioning, publication status) that has no equivalent in the JSON Schema specification.

Two approaches were considered for embedding this metadata:

  1. Custom envelope — wrap the JSON Schema in a Protean-specific container with a schema field for the JSON Schema and sibling fields for metadata.
  2. Standard JSON Schema with x- extensions — emit a standard Draft 2020-12 JSON Schema and embed metadata as x-protean-* prefixed properties at the schema root.

Decision

We will emit standard JSON Schema Draft 2020-12 documents with domain metadata encoded as x-protean-* extension properties.

Extension properties used:

Property Description
x-protean-element-type Element kind: aggregate, entity, value_object, command, event, projection
x-protean-fqn Fully qualified name in the domain
x-protean-aggregate FQN of the owning aggregate (for non-aggregate elements)
x-protean-version Event/command version number
x-protean-type Message type string (e.g. Ordering.OrderPlaced.v1)
x-protean-published Whether the event is part of the published contract
x-protean-is-fact-event Whether the event is an auto-generated fact event
x-protean-auto-generated Whether the element was auto-generated by the framework
x-protean-identity-field Name of the identity field (aggregates)
x-protean-is-event-sourced Whether the aggregate uses event sourcing

The x- prefix is explicitly sanctioned by JSON Schema and OpenAPI specifications for vendor extensions.

Consequences

Positive:

  • Interoperability — schemas can be used directly with standard JSON Schema validators (jsonschema, ajv), schema registries (Confluent Schema Registry, AWS Glue), and OpenAPI 3.1 (which uses JSON Schema Draft 2020-12 natively).
  • Tooling compatibility — editors, linters, and documentation generators that understand JSON Schema work out of the box.
  • No custom parsing — consumers that only need validation can ignore the x-protean-* fields entirely; consumers that need metadata can read them without understanding a custom envelope format.
  • Standards compliance — every generated schema validates against the Draft 2020-12 meta-schema.

Negative:

  • Extension properties are not validated by standard validators — incorrect x-protean-* values will not be caught by jsonschema.validate().
  • Consumers must know to look for x-protean-* keys to extract domain metadata; the properties are not self-documenting without Protean's documentation.

Alternatives Considered

Custom envelope format — rejected because it breaks compatibility with standard JSON Schema validators and registries. Consumers would need Protean-specific tooling to validate payloads, and OpenAPI 3.1 integration would require schema extraction from the envelope.

JSON-LD / @context — rejected as over-engineered for this use case. JSON-LD adds complexity without meaningful benefit since the metadata is framework-specific, not intended for linked data interoperability.