Split x-gts-ref into x-gts-type-ref and x-gts-instance-ref

[aviator5]

Summary

x-gts-ref is kind-blind: the same constraint can accept a GTS Type Identifier, a derived Type Identifier, and an Instance Identifier rooted at that type. Schema authors cannot state whether a field references a type or an instance.

Replace it with two keywords:

• x-gts-type-ref — the candidate must be a GTS Type Identifier;
• x-gts-instance-ref — the candidate must be a GTS Instance Identifier.

This is a breaking change for specification version 0.14.

Problem

For example, VM powerState is constrained by the VM-state type:

{
  "type": "string",
  "x-gts-ref": "gts.x.infra.compute.vm_state.v1~"
}

The intended values are instances such as:

gts.x.infra.compute.vm_state.v1~x.infra._.running.v1

The current keyword also accepts the bare Type Identifier gts.x.infra.compute.vm_state.v1~. The same ambiguity appears in trait topicRef values and module capability references.

Wildcard syntax cannot close this gap because a chain-suffix wildcard can match both the type root and identifiers below it. The candidate kind must therefore be part of the keyword contract.

Decision

Both new keywords retain the current x-gts-ref operand language, JSON Pointer resolution, wildcard/version rules, rooted matching, and optional registry resolution. After the existing match succeeds, the candidate must also have the kind selected by the keyword.

For a resolved operand gts.a.b.c.v1~:

Keyword	Accepted candidates
x-gts-type-ref	that Type Identifier and Type Identifiers derived from it
x-gts-instance-ref	Instance Identifiers rooted at that type, directly or through derived types

Candidate kind is determined from the parsed canonical GTS identifier: Type Identifiers end in ~; Instance Identifiers do not. Matching MUST respect parsed GTS chain boundaries and the existing wildcard and minor-version semantics, not raw lexical startsWith.

To accept either kind, use anyOf with one branch for each keyword.

Effective schema and JSON Pointer operands

The resolution and matching semantics of /$id, including inherited constraints, are tracked separately in #109. That issue includes a concrete derivation example, observed differences across Rust, Python, Go, and TypeScript, and the required conformance-test updates.

Both new keywords will reuse the pointer-resolution and matching rules agreed there. This issue focuses on the additional type-versus-instance restriction and migration to the two keywords.

Migration

Every existing x-gts-ref occurrence must be migrated according to field intent; /$id cannot be replaced mechanically because it is currently used for both type and instance fields.

GTS-aware registration and validation operations targeting 0.14 MUST reject the legacy x-gts-ref keyword instead of silently ignoring it. Generic JSON Schema validators remain free to treat unknown x-* keywords as annotations.

This issue retains rooted matching. A schema that needs one exact Type Identifier can additionally use standard JSON Schema const.

Work to be done

1. ADR — record the kind-blindness defect, reference the pointer semantics agreed in Clarify /$id resolution and matching semantics in inherited schemas #109, document rejected alternatives, the clean break, and interactions with OP#8 compatibility and optional OP#9 identity-field rewriting/reporting.
2. Specification — rewrite README §9.6, update related §9.7 examples, add a migration table, and add a BREAKING 0.14 document-version entry.
3. Examples — migrate JSON Schema, TypeSpec, and YAML examples by field intent; normalize the undocumented "/gts.…" operand form to a valid literal or pointer.
4. Conformance tests — cover wrong-kind rejection, literal and pointer operands, direct and derived candidates, wildcard/version behavior, and combinators. Reuse the /$id conformance cases added or updated under Clarify /$id resolution and matching semantics in inherited schemas #109 to verify that both new keywords apply the agreed pointer semantics together with their candidate-kind restrictions.
5. Reference implementations — create follow-up implementation issues for gts-go and gts-rust after the ADR and conformance contract are merged.