Skip to content

Commit 76540a9

Browse files
committed
docs(spec): frame GTS as a JSON Schema Dialect and add ADR-0001 on derivation form
- Reword §11.0 to explicitly frame GTS Type Schemas as a JSON Schema Dialect over Draft-07, clarifying that GTS extends Draft-07 with x-gts-* keywords and semantic rules without imposing additional syntactic restrictions. - Clarify §3.2 and OP#12 wording so that derivation compatibility applies regardless of whether the derived schema references the parent via allOf + $ref or re-declares parent fields directly. - Clarify §9.11 finality guard is determined from the chained $id alone, not the body's use of allOf. - Add adr/0001-derivation-form.md documenting the decision to treat GTS as a JSON Schema Dialect and not mandate allOf for derivation. Signed-off-by: Aviator 5 <ai.agent.tor@gmail.com>
1 parent c01f956 commit 76540a9

2 files changed

Lines changed: 260 additions & 5 deletions

File tree

README.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ This specification uses the following terms with precise meanings:
119119

120120
- **GTS Type**: a type entity identified by a GTS Type Identifier and defined by a GTS Type Schema. A GTS Type may exist as a standalone document (e.g., a `*.schema.json` file), be exchanged between systems, or be stored in a GTS Registry.
121121
- **GTS Type Identifier**: a canonical GTS identifier ending with `~` that identifies a GTS Type.
122-
- **GTS Type Schema**: the canonical definition of a GTS Type — a JSON Schema document annotated with the GTS vocabulary (`x-gts-*`), describing the type's instance shape, traits, metadata, and relations.
122+
- **GTS Type Schema**: the canonical definition of a GTS Type. It is a [JSON Schema Dialect](https://json-schema.org/learn/glossary#dialect) that extends JSON Schema with GTS-specific keywords (`x-gts-*`) and a set of semantic rules, describing the type's instance shape, traits, and derivation. See §11.0 for details.
123123

124124
Implementations MAY accept alternative source forms (e.g., TypeSpec, YAML) provided they deterministically map to a canonical GTS Type Schema. The canonical form, used for interchange, validation, and registration, is the JSON Schema document.
125125
- **GTS Registry**: a registry that stores and resolves GTS entities — Type Schemas and well-known Instances — by GTS Identifier.
@@ -321,7 +321,7 @@ GTS identifiers may be chained (e.g. `gts.A~B~C`). Validation MUST respect the l
321321
- **Schema → schema validation** (validate a derived schema against its predecessor schema):
322322
- Given a derived type identifier chain (e.g. `A~B~` or `A~B~C~`), the system MUST validate that each derived schema is compatible with its immediate predecessor in the chain.
323323
- The compatibility rule is: every valid instance of the derived schema MUST also be a valid instance of the base schema.
324-
- When JSON Schema inheritance is expressed via `allOf` (recommended), the derived schema MUST be written such that it does not invalidate the compatibility guarantee.
324+
- The derived schema MUST be written such that it does not invalidate this compatibility guarantee, regardless of how the parent's constraints are expressed: via `allOf` with a `$ref` to the parent (recommended, to avoid duplication of parent fields) or by re-declaring the parent's fields directly in the derived schema. See §11.0 for the JSON Schema Dialect framing and [`adr/0001-derivation-form.md`](adr/0001-derivation-form.md) for the full discussion.
325325

326326
- **`additionalProperties` and adding new properties**:
327327
- If a base schema (or any schema in the inheritance chain) defines an object with `additionalProperties: false`, then derived schemas MUST NOT introduce new properties at that object level that would be rejected by the base schema.
@@ -1294,7 +1294,7 @@ Implement and expose all operations OP#1–OP#13 listed above and add appropriat
12941294
- **OP#9 - Version Casting**: Transform instances between compatible MINOR versions
12951295
- **OP#10 - Query Execution**: Filter identifier collections using the GTS query language
12961296
- **OP#11 - Attribute Access**: Retrieve property values and metadata using the attribute selector (`@`)
1297-
- **OP#12 - Type Derivation Validation**: Validate that a derived type correctly extends its base chain. Today this includes JSON Schema-level constraint compatibility (derived schemas using `allOf` must conform to all constraints defined in their parent schemas throughout the inheritance hierarchy — `additionalProperties`, narrowing/widening, etc.) and trait inheritance from OP#13. This ensures type safety in extension and prevents constraint violations in multi-level type hierarchies. When validating derived types, if any base in the chain is marked `x-gts-final: true`, validation MUST fail (see section 9.11)
1297+
- **OP#12 - Type Derivation Validation**: Validate that a derived type correctly extends its base chain. Today this includes JSON Schema-level constraint compatibility (every derived schema MUST conform to all constraints defined in its parent schemas throughout the inheritance hierarchy — `additionalProperties`, narrowing/widening, etc. — regardless of whether the derived schema references the parent via `allOf` + `$ref` or re-declares parent fields directly) and trait inheritance from OP#13. This ensures type safety in extension and prevents constraint violations in multi-level type hierarchies. When validating derived types, if any base in the chain is marked `x-gts-final: true`, validation MUST fail (see section 9.11)
12981298
- **OP#13 - Schema Traits Validation**: Validate schema traits (`x-gts-traits-schema` / `x-gts-traits`). See section 9.7 for full semantics and validation rules.
12991299

13001300
### 9.3 - GTS entities registration
@@ -1560,7 +1560,7 @@ A **schema modifier** is a boolean annotation on a GTS Type Schema that restrict
15601560

15611561
When a schema declares `"x-gts-final": true`:
15621562

1563-
1. **Registration guard**: When a new schema is registered whose `allOf` / `$ref` chain references a final type as a base, the registry MUST reject the registration (when validation is enabled). Specifically, if the derived schema's `$id` is of the form `gts://gts.A~B~` and schema `A~` has `"x-gts-final": true`, then registering `A~B~` MUST fail.
1563+
1. **Registration guard**: When a new schema is registered whose **`$id` chain** references a final type as a base, the registry MUST reject the registration (when validation is enabled). Specifically, if the derived schema's `$id` is of the form `gts://gts.A~B~` and schema `A~` has `"x-gts-final": true`, then registering `A~B~` MUST fail. This is determined from the chained `$id` alone — it does not depend on whether the derived schema body uses `allOf` to reference the parent.
15641564

15651565
2. **Validation via `/validate-type-schema` (OP#12)**: When validating a derived schema against its base chain, if any base schema in the chain is marked `x-gts-final`, validation MUST fail with an error indicating that the base type is final and cannot be extended.
15661566

@@ -1697,7 +1697,9 @@ Result: ❌ NO MATCH (different major versions)
16971697

16981698
### 11.0 JSON Schema Dialect
16991699

1700-
GTS Type Schemas are defined in terms of **JSON Schema Draft-07**. Implementations MUST treat the GTS keywords described in this specification (`$id`, `$ref`, `allOf`, `const`, `x-gts-traits-schema`, `x-gts-traits`, `x-gts-final`, `x-gts-abstract`, etc.) as layered on top of Draft-07 semantics.
1700+
GTS Type Schemas are a [JSON Schema Dialect](https://json-schema.org/learn/glossary#dialect) layered on top of **JSON Schema Draft-07**. GTS extends Draft-07 with additional keywords (`x-gts-*`) and additional **semantic** rules (see §3.2 derivation, §9.11 modifiers, OP#12 derivation compatibility), but does **not** impose additional syntactic restrictions on otherwise-valid JSON Schemas. Any syntactically valid Draft-07 JSON Schema that carries a valid GTS `$id` and the Draft-07 `$schema` URI is a syntactically valid GTS Type Schema. Implementations MUST treat the GTS keywords described in this specification (`$id`, `$ref`, `allOf`, `const`, `x-gts-traits-schema`, `x-gts-traits`, `x-gts-final`, `x-gts-abstract`, etc.) as layered on top of Draft-07 semantics.
1701+
1702+
JSON Schema has no native concept of derivation or inheritance — its closest primitive, [`allOf`](https://json-schema.org/understanding-json-schema/reference/combining#allof), is a logical AND over [subschemas](https://json-schema.org/learn/glossary#subschema) at instance-validation time. In GTS, derivation is expressed by the **chained `$id`** (e.g., `gts://A~B~`); the schema body MAY use `allOf` with a `$ref` to the parent — which is convenient for avoiding duplication of the parent's fields and constraints in the derived schema — but is **not strictly required**. A derived schema that re-declares the parent's fields directly without `allOf` is admissible, provided it satisfies derivation compatibility (OP#12). See [`adr/0001-derivation-form.md`](adr/0001-derivation-form.md) for the full discussion.
17011703

17021704
- The `$schema` field of every GTS Type Schema MUST be `http://json-schema.org/draft-07/schema#`.
17031705
- Implementations MAY accept other JSON Schema dialects for non-GTS schemas, but MUST NOT rely on keywords introduced after Draft-07 (such as `prefixItems`, `unevaluatedProperties`, `unevaluatedItems`, `$dynamicRef`/`$dynamicAnchor`, `dependentRequired`, `dependentSchemas`) when interpreting GTS Type Schemas.

0 commit comments

Comments
 (0)