Skip to content

docs(spec): introduce 0.8beta1 spec version that clarifies schema -> schema validation for chained GTS IDs #55

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

Merged
Artifizer merged 1 commit into from
Feb 17, 2026
Merged

docs(spec): introduce 0.8beta1 spec version that clarifies schema -> schema validation for chained GTS IDs #55

Show file tree
Hide file tree
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
26 changes: 22 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ See the [Practical Benefits for Service and Platform Vendors](#51-practical-bene
| 0.5 | Added Referece Implmenetation recommendations (section 9) |
| 0.6 | Introduced well-known/anonymous instance term; defined field naming implementation recommendations |
| 0.7 | BREAKING: require $ref value to start with 'gts://'; strict rules for schema/instance distinction; prohibiting well-known instances without left-hand type segments |

| 0.8beta1 | Add OP#12 (schema vs schema validation), unified validation endpoint (/validate-entity), and clarify instance -> schema and schema -> schema validation semantics for chained GTS IDs |

## 1. Motivation

Expand Down Expand Up @@ -260,6 +260,24 @@ GTS identifiers enable the following operations and use cases:
- For an instance identifier: extract the rightmost type from the chain and validate the object against that schema
- Chain validation: optionally verify that each type in the chain is compatible with its predecessor

#### Validation semantics for GTS chained IDs (instance -> schema and schema -> schema)

GTS identifiers may be chained (e.g. `gts.A~B~C`). Validation MUST respect the left-to-right inheritance model and MUST preserve the compatibility guarantee (section 3.2).

- **Instance → schema validation** (validate an object instance):
- The system MUST resolve the **rightmost type** in the identifier chain and validate the instance payload against that JSON Schema.
- If the instance identifier includes a type chain (`A~B~<instance>`), validating against the rightmost type `B` MUST also imply conformance to all base types in the chain (by transitivity).
- Implementations MAY additionally validate that each adjacent type pair in the chain is compatible (schema→schema validation), but the primary runtime instance validation target is always the rightmost type.

- **Schema → schema validation** (validate a derived schema against its predecessor schema):
- 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.
- The compatibility rule is: every valid instance of the derived schema MUST also be a valid instance of the base schema.
- When JSON Schema inheritance is expressed via `allOf` (recommended), the derived schema MUST be written such that it does not invalidate the compatibility guarantee.
Comment on lines +263 to +275
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Align “MUST imply conformance” with optional compatibility checks.

You state that validating an instance against the rightmost type MUST imply conformance to all base types by transitivity, but then say schema→schema compatibility checks are MAY. Without mandatory compatibility enforcement (e.g., at registry time), that transitive guarantee doesn’t hold. Consider either requiring schema→schema validation or qualifying the “MUST imply” statement to be conditional on compatibility enforcement.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 263 - 275, The README's "Instance → schema
validation" text claims "validating against the rightmost type MUST also imply
conformance to all base types by transitivity" while "Schema → schema
validation" allows compatibility checks as MAY, creating a contradiction; update
the wording to either require schema→schema compatibility checks at
registry/authoring time or qualify the MUST as conditional (e.g., "MUST imply
conformance ... provided schema→schema compatibility is enforced"); specifically
edit the "Instance → schema validation" and "Schema → schema validation"
paragraphs so they reference the same enforcement model and use consistent modal
language (replace the unconditional "MUST imply conformance" or upgrade the
"MAY" to a required check) to eliminate the inconsistency.


- **`additionalProperties` and adding new properties**:
- 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.
- Derived schemas MAY still tighten constraints of existing properties (e.g. reduce `maxLength`, narrow `enum`, increase `minimum`) and MAY further specify previously-open nested objects (e.g. base `payload: {"type":"object"}` and derived defines `payload.properties`).

3. **Version Compatibility Checking**: Automatically determine if schemas with different MINOR versions are compatible (see section 4).

4. **Access Control Policies**: Build fine-grained or coarse-grained authorization rules using:
Expand Down Expand Up @@ -1193,9 +1211,9 @@ See working examples under `./examples/events`:
- Well-known topics: `./examples/events/instances/gts.x.core.events.topic.v1~x.commerce.orders.orders.v1.0.json`
- Anonymous events: `./examples/events/instances/gts.x.core.events.type.v1~x.commerce.orders.order_placed.v1~.examples.json`

### 9.2 - GTS operations (OP#1–OP#11):
### 9.2 - GTS operations (OP#1 - OP#12):

Implement and expose all operations OP#1–OP#11 listed above and add appropriate unit tests.
Implement and expose all operations OP#1–OP#12 listed above and add appropriate unit tests.

- **OP#1 - ID Validation**: Verify identifier syntax
- **OP#2 - ID Extraction**: Extract identifiers from JSON objects or JSON Schema documents
Expand All @@ -1208,7 +1226,7 @@ Implement and expose all operations OP#1–OP#11 listed above and add appropriat
- **OP#9 - Version Casting**: Transform instances between compatible MINOR versions
- **OP#10 - Query Execution**: Filter identifier collections using the GTS query language
- **OP#11 - Attribute Access**: Retrieve property values and metadata using the attribute selector (`@`)

- **OP#12 - Schema vs Schema Validation**: Validate derived schemas against their base schemas. Derived schemas using `allOf` must conform to all constraints defined in their parent schemas throughout the inheritance hierarchy. This ensures type safety in schema extension and prevents constraint violations in multi-level schema hierarchies.

### 9.3 - GTS entities registration

Expand Down
Loading