You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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>
Copy file name to clipboardExpand all lines: README.md
+7-5Lines changed: 7 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -119,7 +119,7 @@ This specification uses the following terms with precise meanings:
119
119
120
120
-**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.
121
121
-**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.
123
123
124
124
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.
125
125
-**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
321
321
-**Schema → schema validation** (validate a derived schema against its predecessor schema):
322
322
- 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.
323
323
- 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.
325
325
326
326
-**`additionalProperties` and adding new properties**:
327
327
- 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
1294
1294
-**OP#9 - Version Casting**: Transform instances between compatible MINOR versions
1295
1295
-**OP#10 - Query Execution**: Filter identifier collections using the GTS query language
1296
1296
-**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)
1298
1298
-**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.
1299
1299
1300
1300
### 9.3 - GTS entities registration
@@ -1560,7 +1560,7 @@ A **schema modifier** is a boolean annotation on a GTS Type Schema that restrict
1560
1560
1561
1561
When a schema declares `"x-gts-final": true`:
1562
1562
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.
1564
1564
1565
1565
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.
1566
1566
@@ -1697,7 +1697,9 @@ Result: ❌ NO MATCH (different major versions)
1697
1697
1698
1698
### 11.0 JSON Schema Dialect
1699
1699
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.
1701
1703
1702
1704
- The `$schema` field of every GTS Type Schema MUST be `http://json-schema.org/draft-07/schema#`.
1703
1705
- 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