Skip to content

docs(spec): clarify trait schema merge follows $id chain #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aviator5 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(spec): clarify trait schema merge follows $id chain #80

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1501,9 +1501,9 @@ Traits MUST follow standard JSON Schema practices. The key rule is that **the re
Given an inheritance chain `S₀ → S₁ → … → Sₙ`:

- **Trait schema merge**
- The registry MUST build an *effective trait schema* by composing all encountered `x-gts-traits-schema` values using JSON Schema `allOf`.
- Any `$ref` appearing inside `x-gts-traits-schema` MUST be resolved using standard JSON Schema `$ref` resolution rules (base URI resolution + JSON Pointer fragments).
- Derived schemas MAY further constrain (narrow) traits by adding additional schema constraints in their `x-gts-traits-schema` (this is naturally enforced by `allOf`).
- The registry MUST build an *effective trait schema* by composing all `x-gts-traits-schema` values along the **`$id` chain** using JSON Schema `allOf`. Aggregation follows `$id` regardless of how the host body expresses derivation — including bodies with no `allOf` (ADR-0001 Variant 2c).
- Any `$ref` inside `x-gts-traits-schema` MUST be resolved by standard JSON Schema rules (base URI + JSON Pointer fragments). A fragment ref (e.g. `#/$defs/Foo`) resolves against the host type schema the keyword appears in, not against the extracted trait subschema in isolation.
- Derived schemas MAY further constrain (narrow) traits by adding constraints in their `x-gts-traits-schema` (naturally enforced by `allOf`).

- **Trait value merge**
- The registry MUST build an *effective traits object* by walking the type's `$id` chain root → leaf and applying each layer's `x-gts-traits` as a [JSON Merge Patch (RFC 7396)](https://datatracker.ietf.org/doc/html/rfc7396) against the chain-merged object so far. Top-level scalar / array / `null` leaves are overwritten by the descendant (last-wins). Object-valued top-level traits merge **recursively** — fields of an ancestor's object trait that the descendant does not restate are preserved.
Expand Down