Specification gap report: normative, conformance, and documentation inconsistencies

# Global Type System Specification Gap Report

## Audit metadata

| Field | Value |
|---|---|
| Repository | `GlobalTypeSystem/gts-spec` |
| Audited revision | `ef457e0acee74f76d40492b5686327d33ba1166f` |
| Audit branch | `docs/gts-spec-gap-report` |
| Report date | 2026-07-16 |
| Status | **Action required** |
| Scope | Static consistency audit of the specification, ADRs, conformance contract, tests, contributor guidance, and selected example guides |

All line references in this report are revision-specific. They may move after remediation begins.

## Executive summary

The audit identified 30 deduplicated findings: **8 CRITICAL, 17 MAJOR, and 5 MINOR**. The critical findings include three normative contradictions and five broken commands or artifact references. The major findings concentrate on unclear document authority, inconsistent conformance language, stale interface terminology, and examples that conflict with current identifier or JSON Schema rules.

The dominant implementation risk is that a registry or client can follow one authoritative-looking source and still disagree with another. Minor-version compatibility, derivation, identifier grammar, trait completeness, and keyword placement all have conflicting statements or executable evidence. The dominant adoption risk is that several copy-and-paste workflows fail immediately because their paths, filenames, or released version are stale.

Remediation should begin with a P0 governance gate that defines authority and conformance classes. Normative compatibility, derivation, and grammar decisions follow that gate, while unambiguous mechanical repairs may proceed in parallel. OpenAPI, tests, examples, and editorial cleanup should follow settled semantics.

## Scope, methodology, and evidence model

This was a static documentation and specification-versus-tests review. The audit compared statements in `README.md`, accepted ADRs, `tests/openapi.json`, Python conformance tests, contributor guidance, and selected example guides.

Python tests were treated as executable evidence: they show behavior expected by the repository, but they do not automatically outrank the specification. Exact quotations are intentionally short. Proposed remediation preserves the frozen register and does not silently introduce new normative behavior.

### Exclusions and limitations

- No live GTS server was started, and no HTTP conformance suite was executed.
- No validation command is claimed as executed in this report.
- Python implementation and test style were excluded; tests were read only for behavioral evidence.
- CI workflows and generated or example schemas were supporting evidence, not general style-review targets.
- TypeSpec source was excluded except where a guide names it as a command input.
- No fixes were applied to source, tests, examples, ADRs, or API descriptions during the audit.
- Several commands documented by the repository are themselves findings; the verification section marks those caveats.

## Severity definitions

| Severity | Definition |
|---|---|
| CRITICAL | A contradiction or broken workflow can cause incompatible implementations, invalid normative interpretation, or immediate failure of a primary documented task. |
| MAJOR | A material gap can produce divergent behavior, mislead implementers, or substantially impair conformance, maintenance, or onboarding. |
| MINOR | A localized language or presentation defect reduces clarity or confidence without changing intended behavior. |

## Prioritized findings matrix

| ID | Severity | Area | Gap type | Concise impact | Remediation class | Phase |
|---|---|---|---|---|---|---|
| GTS-001 | CRITICAL | Compatibility | Spec/test contradiction | Implementations can reverse OP#8 results for required fields in open models. | Normative spec and conformance tests | P0 |
| GTS-002 | CRITICAL | Derivation | Normative contradiction | Schema authors may reject valid derived required fields. | Normative clarification | P0 |
| GTS-003 | CRITICAL | Identifier grammar | Prose/grammar contradiction | Parsers may accept reserved `_` in forbidden positions. | Grammar, regex, and negative tests | P0 |
| GTS-004 | CRITICAL | Events examples | Broken reference | The combined anonymous instance example cannot be opened. | Mechanical documentation fix | P0 |
| GTS-005 | CRITICAL | TypeSpec examples | Broken command | The documented compiler input is not found. | Mechanical command fix | P0 |
| GTS-006 | CRITICAL | YAML examples | Broken command | AJV validation targets an absent schema artifact. | Workflow documentation fix | P0 |
| GTS-007 | CRITICAL | YAML examples | Broken inventory | Six advertised artifacts cannot be located from their literals. | Link normalization | P0 |
| GTS-008 | CRITICAL | Test guide | Broken command | The documented pytest selector cannot locate the test. | Mechanical command fix | P0 |
| GTS-009 | MAJOR | Contributor guide | Incomplete repository map | Contributors do not discover ADR and conformance-test responsibilities. | Onboarding documentation | P2 |
| GTS-010 | MAJOR | Contributor guide | Stale architecture guidance | Contributors are directed toward an obsolete in-repository implementation model. | Onboarding and workflow alignment | P2 |
| GTS-011 | MAJOR | Conformance | Normative scope ambiguity | Mandatory OP rules appear under a section declared non-mandatory. | Governance and conformance classes | P0 |
| GTS-012 | MAJOR | Governance | Missing precedence | Conflicts among README, ADRs, OpenAPI, tests, and examples cannot be resolved consistently. | Authority policy | P0 |
| GTS-013 | MAJOR | Identifier validation | Example/regex contradiction | Prohibited single-segment instances remain accepted or demonstrated. | Regex scope and examples | P1 |
| GTS-014 | MAJOR | References | Syntax inconsistency | Implementers may support different self-reference spellings. | Maintainer decision and normalization rule | P1 |
| GTS-015 | MAJOR | Schema examples | Classification contradiction | Examples intended as schemas are classified as instances by Rule A. | Example completion or fragment labels | P1 |
| GTS-016 | MAJOR | Event scenario | Field-role inconsistency | The scenario alternates between `gtsId` and `type`, obscuring interoperable defaults. | Scenario consistency correction | P1 |
| GTS-017 | MAJOR | OpenAPI | Legacy terminology | Generated clients expose vague nouns inconsistent with canonical terms. | API description cleanup | P2 |
| GTS-018 | MAJOR | Releases | Stale runnable examples | Users may select a test image for spec 0.11 while reading spec 0.12. | Versioned example policy | P2 |
| GTS-019 | MAJOR | Test guide | Incomplete inventory | OP#12 and OP#13 conformance coverage is hidden. | Test documentation alignment | P2 |
| GTS-020 | MAJOR | Traits | ADR/spec contradiction | Registries may enforce completeness always or only when validation is enabled. | ADR or specification decision | P1 |
| GTS-021 | MAJOR | Traits | Boolean-schema contradiction | Implementers may incorrectly treat `false` as accepting an empty traits object. | ADR correction and tests | P1 |
| GTS-022 | MAJOR | Schema shape | ADR/spec contradiction | Keyword-placement rejection conflicts with an absolute no-shape-rejection claim. | Narrow ADR scope | P1 |
| GTS-023 | MAJOR | JSON Schema dialects | Untracked design hazard | Draft-07 composition can reject intended extensions without usable guidance. | Successor decision and interim guidance | P1 |
| GTS-024 | MAJOR | YAML examples | Normative overstatement | Authors may believe `allOf` is mandatory for derivation. | Example guide correction | P1 |
| GTS-025 | MAJOR | Identifier examples | Malformed examples | Readers copy identifiers missing a required relative-segment component. | Example normalization | P1 |
| GTS-026 | MINOR | Opening scope | Undefined acronyms | New schema authors cannot quickly interpret every advertised domain. | Editorial definition pass | P3 |
| GTS-027 | MINOR | Voice | Promotional language | Absolute claims reduce specification precision. | Editorial cleanup | P3 |
| GTS-028 | MINOR | Readability | Excessive sentence length | Independent normative rules are difficult to scan and implement. | Structural editing | P3 |
| GTS-029 | MINOR | Language | Spelling and grammar | Errors reduce confidence in implementation-facing instructions. | Proofreading | P3 |
| GTS-030 | MINOR | Modules example | Unclear introduction | Readers cannot quickly identify the example’s purpose. | Focused rewrite | P3 |

## Detailed findings

### GTS-001 — Minor-version compatibility table contradicts OP#8 for a new required field in an open model

**Severity:** CRITICAL

**Locations:** `README.md:629-648`; `tests/test_op8_compatibility_checking.py:155-212`.

**Evidence:** The table says, “Adding new required property” is incompatible in every mode. The OP#8 test registers an open-model v1.1 schema with required `newField` and expects forward compatibility.

**Gap:** The table applies one result to both open and closed content models. Executable evidence distinguishes the open-model case.

**Impact:** Independent implementations can return opposite compatibility results for the same schema pair.

**Proposed remediation:** Split the rule by content model. For the audited open-model case, document the registered expectation: backward `false`, forward `true`, full `false`. Do not generalize other cases without tests or a maintainer decision.

**Acceptance criteria:** The table has separate open/closed rows; the open-model row matches the three expected booleans; OP#8 tests cover all three results.

**Dependencies/decision needed:** Confirm the compatibility direction definitions remain those in §4.1 before editing the table.

### GTS-002 — Derived-field guidance conflicts with the instance-set compatibility rule

**Severity:** CRITICAL

**Locations:** `README.md:345-356`; `adr/0001-derivation-form.md:78`; `tests/test_op12_type_derivation_validation.py:190-217`.

**Evidence:** README says derived types “can only add optional fields.” ADR-0001 and OP#12 accept a derived schema that adds required `tier` while preserving every base constraint.

**Gap:** Field optionality is presented as the governing rule, but derivation compatibility is actually an instance-set subset relation.

**Impact:** Schema authors and validators may reject valid derivations or implement a stricter, incompatible dialect.

**Proposed remediation:** State that every derived-valid instance must also validate against every ancestor. Present required-field addition as potentially valid when it narrows the derived instance set without invalidating ancestor constraints.

**Acceptance criteria:** §3.2 uses the subset rule; it no longer bans all new required fields; the accepted OP#12 case is cited or reproduced.

**Dependencies/decision needed:** None beyond confirming ADR-0001 and OP#12 remain authoritative for derivation semantics.

### GTS-003 — The `_` placeholder restriction is not enforced by grammar or regex

**Severity:** CRITICAL

**Locations:** `README.md:185`, `README.md:236-262`, `README.md:1165-1184`.

**Evidence:** Prose reserves singleton `_` for namespace, while EBNF assigns the same `segment` production to vendor, package, namespace, and type. Regex groups also allow `[a-z_]` in every position.

**Gap:** The machine-readable syntax accepts values prohibited by the prose.

**Impact:** Parsers can disagree on canonical validity, registry keys, and cross-implementation identifier exchange.

**Proposed remediation:** Define distinct productions for namespace and non-placeholder segments. Update regexes and add negative tests for `_` as vendor, package, or type, while retaining the intended namespace placeholder.

**Acceptance criteria:** Prose, EBNF, regex, and OP#1 tests agree; each forbidden singleton position has a negative test; the namespace case remains positive.

**Dependencies/decision needed:** Maintainers must confirm that only the singleton `_`, rather than all underscore-prefixed tokens, is reserved.

### GTS-004 — Events guide points to a nonexistent combined-instance file

**Severity:** CRITICAL

**Locations:** `examples/events/README.md:30`.

**Evidence:** The guide names `instances/gts.x.core.events.type_combined.v1~x.commerce.orders.order_placed.v1.0~.examples.json`; the repository file includes `type_combined_id`.

**Gap:** The literal path omits `_id`.

**Impact:** Readers and tools cannot open the advertised combined anonymous instance.

**Proposed remediation:** Link to `instances/gts.x.core.events.type_combined_id.v1~x.commerce.orders.order_placed.v1.0~.examples.json`.

**Acceptance criteria:** The Markdown target resolves from the guide and a repository link check reports no failure.

**Dependencies/decision needed:** None; the intended file is unambiguous.

### GTS-005 — TypeSpec compilation command omits the source directory

**Severity:** CRITICAL

**Locations:** `examples/typespec/vms/README.md:73-77`.

**Evidence:** The command compiles `gts.x.infra.compute.vm.v1~.tsp`, while the guide links the source under `types/`.

**Gap:** The runnable command omits `types/`.

**Impact:** TypeSpec exits before compilation because the input file is not found.

**Proposed remediation:** Use `types/gts.x.infra.compute.vm.v1~.tsp` as the command input and state the expected working directory.

**Acceptance criteria:** The input path resolves from the documented working directory and the command is syntactically consistent with the linked source.

**Dependencies/decision needed:** Verification requires TypeSpec tooling; this audit did not execute it.

### GTS-006 — YAML AJV workflow references an absent JSON schema

**Severity:** CRITICAL

**Locations:** `examples/yaml/ui/README.md:107-115`.

**Evidence:** AJV receives `types/...menu_item.v1~.schema.json`; only the corresponding `.schema.yaml` exists.

**Gap:** The workflow converts the instance but neither converts the schema nor uses a YAML-capable validator for it.

**Impact:** The alternative validation path fails before validation begins.

**Proposed remediation:** Either document conversion of both schema and instance to generated JSON paths, or use the already documented YAML-capable validator. Do not imply AJV reads the existing YAML file directly.

**Acceptance criteria:** Every command input exists or is created by a preceding command; the working directory and temporary outputs are explicit.

**Dependencies/decision needed:** Maintainers should choose one supported validation workflow before final wording.

### GTS-007 — YAML artifact inventory uses six non-resolving literals

**Severity:** CRITICAL

**Locations:** `examples/yaml/ui/README.md:19-51`.

**Evidence:** Schema entries omit `types/`; instance entries use short names such as `main_dashboard.yaml` instead of their expanded filenames under `instances/`.

**Gap:** The inventory labels do not resolve as paths from the guide.

**Impact:** Readers cannot navigate to any of the six advertised artifacts without searching the repository.

**Proposed remediation:** Replace all six literals with full repository-relative Markdown links to the existing files.

**Acceptance criteria:** Each inventory entry is clickable and resolves; displayed names distinguish schema and instance identifiers.

**Dependencies/decision needed:** None; each intended target is unique.

### GTS-008 — Python test selector names the wrong file and working-directory path

**Severity:** CRITICAL

**Locations:** `tests/README.md:82-85`, `tests/README.md:101-108`.

**Evidence:** Docker uses `test_op1_id_validation.py`, but the Python section says `pytest op1_id_validation_test.py`. The repository-root workflow requires `tests/test_op1_id_validation.py`.

**Gap:** The Python selector reverses the filename convention and omits the root-relative directory.

**Impact:** The copy-and-paste command reports that the test file does not exist.

**Proposed remediation:** Use `pytest tests/test_op1_id_validation.py` and state that the Python commands run from repository root.

**Acceptance criteria:** The selector resolves from the stated directory and matches the existing test filename.

**Dependencies/decision needed:** None; the Docker and repository filenames identify the target.

### GTS-009 — Contributor repository map omits ADR and test surfaces

**Severity:** MAJOR

**Locations:** `CONTRIBUTING.md:28-40`.

**Evidence:** The map lists the main README and `examples/`, but omits `adr/` and `tests/`.

**Gap:** Two governance and conformance surfaces are absent from contributor orientation.

**Impact:** Contributors can change normative behavior without discovering the associated ADR or conformance-test update obligations.

**Proposed remediation:** Add `adr/`, `tests/`, `tests/openapi.json`, and the relevant example/test responsibilities to the map.

**Acceptance criteria:** A new contributor can locate normative decisions, the API contract, and black-box tests from the layout section.

**Dependencies/decision needed:** Align wording with the authority policy from GTS-012.

### GTS-010 — Contributor setup describes an obsolete reference-implementation model

**Severity:** MAJOR

**Locations:** `CONTRIBUTING.md:11-22`, `CONTRIBUTING.md:60-68`; `tests/README.md:13-45`, `tests/README.md:101-105`.

**Evidence:** CONTRIBUTING mentions optional “reference implementations” and installing only `jsonschema`; the test guide describes black-box HTTP tests against external servers.

**Gap:** Setup instructions do not explain the repository’s actual conformance architecture or install `tests/requirements.txt`.

**Impact:** Contributors may prepare the wrong environment and misunderstand the boundary between this repository and language implementations.

**Proposed remediation:** Describe external server implementations, install test requirements from the repository, and show how `GTS_BASE_URL` connects tests to a server.

**Acceptance criteria:** Setup and validation steps match `tests/README.md`; no text implies an in-repository server implementation.

**Dependencies/decision needed:** Coordinate with GTS-009 and GTS-018 so contributor commands use current paths and versions.

### GTS-011 — Mandatory operations sit beneath a non-mandatory heading

**Severity:** MAJOR

**Locations:** `README.md:1220-1222`, `README.md:1283-1317`.

**Evidence:** §9 says its recommendations “are not mandatory,” then instructs implementations to expose OP#1–OP#13 and uses `MUST` behavior.

**Gap:** Section scope contradicts its normative language.

**Impact:** Implementers cannot tell whether an operation is required for GTS conformance or only for a reference implementation profile.

**Proposed remediation:** Define explicit conformance classes or profiles, then move or scope normative requirements accordingly. Preserve optional implementation advice separately.

**Acceptance criteria:** Every `MUST` in §9 belongs to a named conformance class; optional recommendations do not contain unqualified mandatory language.

**Dependencies/decision needed:** Requires a maintainer governance decision and should be recorded in an ADR or equivalent normative policy.

### GTS-012 — Document authority and conflict precedence are undefined

**Severity:** MAJOR

**Locations:** `README.md:6`, `README.md:113-115`; decision sections in `adr/0001-0004`; `tests/README.md:11`.

**Evidence:** README presents the specification, ADRs state normative consequences, and tests call themselves a “Single Source of Truth.” No source states which wins on conflict.

**Gap:** Multiple authoritative-looking artifacts lack an explicit precedence and synchronization policy.

**Impact:** Maintainers and implementers can resolve the same conflict differently.

**Proposed remediation:** Define the authority order and roles of the current specification, accepted ADRs, OpenAPI, tests, and examples. State the required update process when they diverge.

**Acceptance criteria:** A repository-level policy answers which artifact governs behavior and how contradictions are repaired; other documents link to it.

**Dependencies/decision needed:** Maintainer decision. This policy should precede all behavioral remediation.

### GTS-013 — Single-segment instances are prohibited but still accepted or shown

**Severity:** MAJOR

**Locations:** `README.md:468`, `README.md:474`, `README.md:485`, `README.md:539`, `README.md:1165-1188`.

**Evidence:** §3.7 prohibits single-segment instance identifiers. The single-segment regex allows the trailing `~` to be absent, and selector or access examples use unchained instance-like forms.

**Gap:** Lexical validation and examples do not enforce the semantic chain requirement.

**Impact:** OP#1 implementations can accept identifiers that the prose declares invalid.

**Proposed remediation:** Either make the regex type-only or label it as a lexical helper requiring a semantic chain check. Replace invalid query and selector examples.

**Acceptance criteria:** No normative example presents a prohibited singleton instance; OP#1 tests reject it; regex scope is explicit.

**Dependencies/decision needed:** Coordinate with GTS-003 because both change grammar and negative tests.

### GTS-014 — Self-reference syntax alternates between `/$id` and `./$id`

**Severity:** MAJOR

**Locations:** `README.md:1323-1334`; `examples/modules/README.md:22-24`.

**Evidence:** README lists `"x-gts-ref": "/$id"` but later describes relative paths such as `./$id`; the modules guide uses `./$id`.

**Gap:** The specification does not define whether both spellings are aliases or one is invalid.

**Impact:** Validators can implement incompatible self-reference parsing.

**Proposed remediation:** Choose one canonical spelling, or define normalization and alias behavior explicitly. Update examples and tests to match.

**Acceptance criteria:** One rule covers all documented spellings; positive and negative tests encode the decision; all examples are consistent.

**Dependencies/decision needed:** Maintainer decision, preferably captured with other `x-gts-ref` semantics.

### GTS-015 — Standalone schema examples are classified as instances by Rule A

**Severity:** MAJOR

**Locations:** `README.md:659-688`, `README.md:1356`, `README.md:1456-1494`, `README.md:1732-1739`; examples in `adr/0004-x-gts-traits-merge-strategy.md`.

**Evidence:** Rule A says a document is a schema “if and only if” it has top-level `$schema`. Several complete-looking schema examples contain `$id` and schema keywords but omit `$schema`.

**Gap:** Examples violate the document classifier unless they are explicitly fragments.

**Impact:** Implementers copying examples may register them as instances or reject them unexpectedly.

**Proposed remediation:** Add the appropriate `$schema` to standalone examples or label and format them as non-registerable fragments.

**Acceptance criteria:** Every complete schema example satisfies Rule A; every omission is explicitly labeled as a fragment.

**Dependencies/decision needed:** Confirm the intended dialect for each complete example.

### GTS-016 — Event scenario uses inconsistent type-reference fields

**Severity:** MAJOR

**Locations:** `README.md:990`, `README.md:1087-1092`, `README.md:1272-1277`, `README.md:1806-1808`.

**Evidence:** The scenario introduction says every event must contain a `gtsId` field that references its schema, while its later payload and explanatory prose use `type`. The specification recommends `id`/`gtsId` for instance identifiers and `type`/`gtsType` for type references as interoperable defaults, but also allows implementation-specific, configuration-driven field handling.

**Gap:** One scenario presents two different default fields for the same type-reference role without explaining that the earlier `gtsId` usage is a configured exception.

**Impact:** Client authors copying different parts of the scenario may choose different default fields, reducing out-of-the-box interoperability even when each implementation permits configuration.

**Proposed remediation:** Use the recommended `type` field consistently throughout the scenario, or explicitly label `gtsId` as an implementation-specific configuration and define its extraction precedence. Do not describe either recommendation as universally reserved.

**Acceptance criteria:** README line 990 and the later payload/prose use one consistent field; any exception is labeled implementation-specific; §9.1 remains framed as an interoperable recommendation rather than a universal field reservation.

**Dependencies/decision needed:** Resolve after the conformance scope in GTS-011 is clear.

### GTS-017 — OpenAPI summaries use vague legacy nouns

**Severity:** MAJOR

**Locations:** `tests/openapi.json:51`, `tests/openapi.json:651`; canonical terminology at `README.md:117-128`.

**Evidence:** Summaries say “Register a single entity (object or schema)” and “Cast instance to target schema,” rather than naming GTS Types, GTS Type Schemas, and GTS Instances.

**Gap:** API-facing prose lags the terminology introduced in specification version 0.11.

**Impact:** Generated documentation and clients perpetuate ambiguous concepts at interface boundaries.

**Proposed remediation:** Rewrite summaries and related descriptions with canonical nouns without changing endpoint behavior.

**Acceptance criteria:** OpenAPI prose uses the terminology definitions consistently; generated documentation contains no ambiguous legacy “schema” where “GTS Type Schema” is intended.

**Dependencies/decision needed:** Apply after GTS-012 establishes OpenAPI’s authority role.

### GTS-018 — Release and Docker examples remain pinned to specification 0.11

**Severity:** MAJOR

**Locations:** `README.md:1-2`; `CONTRIBUTING.md:128-143`; `tests/README.md:56-85`.

**Evidence:** The marker declares spec 0.12, while runnable Docker examples use `v0.11` and `v0.11.3`.

**Gap:** Examples do not distinguish illustrative tags from the current available release.

**Impact:** Users may run conformance tests for the wrong specification version.

**Proposed remediation:** Use placeholders for generic instructions and separately show a clearly labeled current available tag. Keep examples synchronized with the release process.

**Acceptance criteria:** Runnable examples cannot be mistaken for the audited spec version; a documented check detects marker/tag drift.

**Dependencies/decision needed:** Confirm which 0.12 image tag is actually published before naming it.

### GTS-019 — Implemented-test inventory omits OP#12 and OP#13

**Severity:** MAJOR

**Locations:** `tests/README.md:118-133`; `README.md:1283-1299`; `tests/openapi.json:472-514`.

**Evidence:** The checklist ends at OP#11 even though README defines OP#12 and OP#13 and OpenAPI includes `/validate-type-schema`.

**Gap:** Test documentation understates the conformance surface.

**Impact:** Implementers may consider OP#12 and OP#13 untested or optional.

**Proposed remediation:** Add inventory entries for both operations, linking their test modules and endpoints.

**Acceptance criteria:** The inventory covers OP#1–OP#13 and each item maps to existing test or explicitly states a coverage gap.

**Dependencies/decision needed:** Align labels with the conformance classes decided in GTS-011.

### GTS-020 — Trait completeness timing differs between ADR and specification

**Severity:** MAJOR

**Locations:** `adr/0003-x-gts-traits-completeness.md:143-145`, `adr/0003-x-gts-traits-completeness.md:226-245`; `README.md:1518`, `README.md:1638`; `tests/openapi.json:50-63`, `tests/openapi.json:178-217`; `tests/test_op13_schema_traits_validation.py:12-14`.

**Evidence:** ADR-0003 chooses completeness validation “at type registration,” while README gates registration checks on validation being enabled. Generic `POST /entities` exposes `validate` with default `false`; dedicated `POST /type-schemas` has no equivalent parameter. The OP#13 test policy states that reference implementations remain permissive at `POST /entities`.

**Gap:** The sources disagree on whether completeness is unconditional and do not define how the rule differs among generic registration, dedicated type-schema registration, and explicit validation endpoints.

**Impact:** Registries can accept different state and provide different fail-fast guarantees.

**Proposed remediation:** Decide the completeness policy separately for generic `POST /entities`, dedicated `POST /type-schemas`, and explicit validation endpoints. Then align ADR-0003, README, OpenAPI endpoint semantics, and the stated OP#13 test policy in one change.

**Acceptance criteria:** README, ADR-0003, OpenAPI, and test policy describe the same endpoint-specific behavior; tests cover generic registration with default validation, generic registration with `validate=true`, dedicated type-schema registration, and explicit validation endpoints.

**Dependencies/decision needed:** Maintainer decision and likely ADR amendment.

### GTS-021 — ADR-0003 misstates boolean `false` validation

**Severity:** MAJOR

**Locations:** `adr/0003-x-gts-traits-completeness.md:248-252`; `README.md:1366`, `README.md:1518-1519`; `adr/0002-x-gts-traits-schema.md:239`; `tests/test_op13_schema_traits_validation.py:2030-2065`.

**Evidence:** ADR-0003 says a non-abstract type can register beneath `false` by omitting traits, although a JSON Schema boolean `false` validates no instance, including an empty object. `TestCaseOp13_TraitsSchema_BooleanFalse_NoTraits_Ok` positively asserts that a concrete descendant with no `x-gts-traits` registers and validates.

**Gap:** The edge-case explanation contradicts standard JSON Schema semantics and ADR-0002’s “unsatisfiable” description.

**Impact:** Trait validators may incorrectly special-case the empty effective traits object as valid.

**Proposed remediation:** Remove the false-validates-empty claim and revise or replace `TestCaseOp13_TraitsSchema_BooleanFalse_NoTraits_Ok` after the maintainer decision. Retain negative and inherited-`false` coverage so unsatisfiability is tested across the chain.

**Acceptance criteria:** ADR-0002, ADR-0003, README, and tests agree that boolean `false` is unsatisfiable; no test expects a non-abstract materialized traits object to validate against `false`; negative and inherited-`false` coverage remains.

**Dependencies/decision needed:** Maintainer decision on whether an abstract-only subtree is useful; coordinate with GTS-020.

### GTS-022 — ADR-0001’s no-shape-rejection claim is too broad

**Severity:** MAJOR

**Locations:** `adr/0001-derivation-form.md:212-217`; `README.md:1358`; `tests/test_xgts_keyword_placement.py:12-16`, `tests/test_xgts_keyword_placement.py:277-292`.

**Evidence:** ADR-0001 says schemas are “never” rejected purely for shape. README and tests require top-level GTS keywords and reject nested placements.

**Gap:** A claim about derivation composition form is written as an absolute claim about all schema shape.

**Impact:** Implementers can ignore required placement checks or view conforming tests as contradicting an accepted ADR.

**Proposed remediation:** Narrow ADR-0001 to say derivation is not rejected solely for omitting or arranging `allOf`/parent references. Preserve explicit GTS keyword placement rules.

**Acceptance criteria:** ADR language no longer conflicts with placement tests; README links the narrowed claim to §9.7.1 and §9.11.

**Dependencies/decision needed:** ADR amendment, but no new derivation behavior is proposed.

### GTS-023 — Draft-07 composition hazard is deferred without ownership

**Severity:** MAJOR

**Locations:** `adr/0001-derivation-form.md:42`, `adr/0001-derivation-form.md:204`; `adr/0002-x-gts-traits-schema.md:249`; `README.md:1718-1724`.

**Evidence:** Both ADRs call the `$ref`/`additionalProperties` interaction a known Draft-07 “footgun” and defer it to a separate discussion, but no successor is identified.

**Gap:** A known interoperability hazard has no tracked decision, owner, milestone, or interim author guidance.

**Impact:** Authors can produce schemas that appear to derive correctly but reject intended fields under Draft-07 composition.

**Proposed remediation:** Open and link a successor ADR or issue. Until resolved, add bounded guidance showing affected forms and safer alternatives without changing the chosen dialect-agnostic policy.

**Acceptance criteria:** The deferral links to an owned decision artifact with status; README provides actionable interim guidance and a conformance example.

**Dependencies/decision needed:** Maintainers must choose the tracking vehicle and whether stronger dialect guidance requires an ADR.

### GTS-024 — YAML authoring guide makes optional `allOf` mandatory

**Severity:** MAJOR

**Locations:** `examples/yaml/ui/README.md:118-125`; `README.md:1724`; `adr/0001-derivation-form.md:214-216`.

**Evidence:** The guide instructs authors to “Use `allOf` to inherit base properties.” README and ADR-0001 make `allOf` recommended but not required.

**Gap:** An example-specific convention is phrased as a universal derivation step.

**Impact:** Authors may believe valid direct-restatement schemas are non-conforming.

**Proposed remediation:** Label `allOf` as the convention used by this example and mention that chained `$id` plus OP#12 establishes derivation semantics.

**Acceptance criteria:** The guide distinguishes recommendation from requirement and links to §11.0 or ADR-0001.

**Dependencies/decision needed:** None after GTS-022 narrows the ADR language.

### GTS-025 — Identifier examples omit a required relative-segment component

**Severity:** MAJOR

**Locations:** `README.md:395`, `README.md:401`, `README.md:1661`, `README.md:1663`, `README.md:1673`, `README.md:1676`; `examples/yaml/ui/README.md:125`.

**Evidence:** Malformed relative segments include `abc.events.order_placed.v1~` at README line 395, `abc.orders.order_placed.v1~` at line 401, and `x.llm.system_message.v1.0~` or `x.llm.user_message.v1.1~` at lines 1661, 1663, 1673, and 1676. The YAML naming template at line 125 uses `<vendor>.components.<type>.v<version>~`. By contrast, YAML lines 62, 66, and 67 contain valid four-component relative segments.

**Gap:** The identified literals omit one required vendor/package/namespace/type component, while nearby valid examples make the intended grammar clear.

**Impact:** Readers copy malformed identifiers and may compensate by implementing an incorrect parser.

**Proposed remediation:** Correct only the malformed literals listed above to four labels plus version. Use `_` only for an intentionally omitted namespace, and preserve the valid YAML examples at lines 62, 66, and 67.

**Acceptance criteria:** Every corrected literal parses under the OP#1 grammar; the valid four-component YAML examples remain unchanged as positive controls; tests cover each corrected pattern.

**Dependencies/decision needed:** Apply after GTS-003 settles placeholder grammar.

### GTS-026 — Opening scope uses specialized acronyms without expansion

**Severity:** MINOR

**Locations:** `README.md:16-30`.

**Evidence:** The opening list uses `RPC`, `FaaS`, `RBAC`, `ABAC`, `IAM`, `IoT`, `ML`, `AI`, and `MCP` without expansion.

**Gap:** Domain-specific abbreviations appear before readers receive definitions.

**Impact:** Schema authors outside those domains cannot quickly evaluate the scope examples.

**Proposed remediation:** Expand each acronym at first use and retain the abbreviation in parentheses. Avoid adding domain behavior.

**Acceptance criteria:** Every uncommon acronym in the opening is expanded once; common JSON and API terms remain concise.

**Dependencies/decision needed:** None; this is editorial only.

### GTS-027 — Promotional and absolute language reduces precision

**Severity:** MINOR

**Locations:** `README.md:36-44`, `README.md:132-158`, `README.md:950-980`.

**Evidence:** Phrases include “production-ready,” “instantly comprehensible,” “robust,” and “Zero-downtime extensions.”

**Gap:** Capability descriptions present outcomes without their registry, compatibility, deployment, or storage assumptions.

**Impact:** Readers must separate marketing claims from normative guarantees.

**Proposed remediation:** Replace absolute claims with neutral descriptions of observable mechanisms and qualify outcomes with their prerequisites.

**Acceptance criteria:** Capability sections use evidence-based language; guarantees are either normative and sourced or explicitly conditional.

**Dependencies/decision needed:** Perform after behavioral remediation so qualifications reflect settled rules.

### GTS-028 — Long paragraphs combine independent normative rules

**Severity:** MINOR

**Locations:** `README.md:1372-1376`, `README.md:1616-1626`, `README.md:1718-1720`.

**Evidence:** Individual paragraphs combine aggregation, narrowing, extension, defaults, placement, dialect handling, and multiple exceptions.

**Gap:** Rule, exception, and example boundaries are hidden inside long sentences.

**Impact:** Implementers can overlook a condition while translating prose into validation branches.

**Proposed remediation:** Use a short rule-first sentence followed by parallel bullets for conditions, exceptions, and examples.

**Acceptance criteria:** Each normative sentence carries one principal obligation; exceptions are discoverable by scanning labels or bullets.

**Dependencies/decision needed:** Edit after GTS-020 through GTS-023 to avoid polishing unsettled semantics.

### GTS-029 — Implementation-facing prose contains recurring language defects

**Severity:** MINOR

**Locations:** `README.md:653`, `README.md:1303-1334`, `README.md:1669`.

**Evidence:** Examples include `identitfiers`, `refererred`, “Test it's conformance,” `accordinly`, and “deriver types.”

**Gap:** Grammar and spelling errors remain in instructions and examples.

**Impact:** Errors interrupt reading and reduce confidence in prescriptive text.

**Proposed remediation:** Correct the terms to `identifiers`, `referred`, “Test its conformance,” `accordingly`, and “derived types,” then proofread adjacent prose.

**Acceptance criteria:** Listed defects are absent outside historical quotations; a documentation spelling pass reports no new implementation-term errors.

**Dependencies/decision needed:** None; apply during P3 editorial cleanup.

### GTS-030 — Modules example introduction is unclear and ungrammatical

**Severity:** MINOR

**Locations:** `examples/modules/README.md:3`.

**Evidence:** “This folder contains a simple self-contained examples ... and also needs to know modules capabilities ...” combines number, possessive, and run-on errors.

**Gap:** The opening does not state the example and its purpose directly.

**Impact:** Readers cannot quickly decide whether the module example is relevant.

**Proposed remediation:** Use two direct sentences: identify the self-contained SaaS example, then explain that module capabilities configure its API gateway.

**Acceptance criteria:** The introduction is grammatical, ends with punctuation, and identifies both the domain and demonstrated relationship.

**Dependencies/decision needed:** Confirm the proposed purpose against the example artifacts before merging.

## Cross-cutting root causes

1. **Authority is implicit.** README, ADRs, tests, and OpenAPI each use source-of-truth language without an agreed precedence model.
2. **Normative and advisory content are mixed.** Mandatory behavior appears beneath recommendation headings and inside example guides.
3. **Behavior evolved unevenly.** ADR decisions and newer tests were added without fully updating earlier tables, examples, and contributor workflows.
4. **Machine-readable syntax is not checked against prose.** EBNF, regex, example identifiers, and semantic restrictions drift independently.
5. **Examples lack automated integrity gates.** Paths, version tags, and runnable commands can become stale without detection.
6. **Known design risks lack lifecycle metadata.** Deferred hazards do not identify owners, successor decisions, or interim guidance.
7. **Editorial review follows feature accumulation.** Long normative paragraphs and promotional language indicate repeated append-only revisions.

## Remediation roadmap

The dependency order below prevents downstream examples or tests from encoding unresolved policy.

```mermaid
flowchart LR
    A[P0 governance and authority gate] --> B[P0/P1 normative semantics]
    B --> C[P1/P2 conformance, API, and tests]
    C --> D[P2 examples and tooling]
    D --> E[P3 editorial cleanup]
```

### P0 — Governance and correctness blockers

**Findings:** GTS-011, GTS-012, and GTS-001 through GTS-008.

**Suggested owners:** Specification governance maintainers for GTS-011 and GTS-012; specification maintainers for GTS-001 through GTS-003; documentation/example owners for GTS-004 through GTS-008; conformance-test maintainers for acceptance coverage.

**Order:** Establish the GTS-012 authority policy, then define GTS-011 conformance classes before deciding GTS-001 through GTS-003. Mechanical path and command repairs GTS-004 through GTS-008 may proceed in parallel because their intended targets are unambiguous.

**Exit criteria:** A written authority policy and explicit conformance classes exist; critical contradictions are resolved across the governing prose and tests; all five documented workflows or inventories resolve from their stated working directories; new grammar and compatibility cases are covered.

### P1 — Authority and normative semantics

**Findings:** GTS-013 through GTS-016 and GTS-020 through GTS-025.

**Suggested owners:** Specification governance group, ADR authors, registry implementers, and conformance maintainers.

**Order:** After the P0 authority and conformance gate, decide trait timing and boolean-schema behavior, narrow ADR claims, track the Draft-07 hazard, and normalize dependent examples.

**Exit criteria:** Each behavioral contradiction has one approved rule under the P0 authority policy; ADRs, README, OpenAPI, and tests agree on the affected semantics.

### P2 — Conformance interfaces, examples, tooling, and onboarding

**Findings:** GTS-009, GTS-010, and GTS-017 through GTS-019.

**Suggested owners:** Contributor-experience maintainers, OpenAPI/test maintainers, release maintainers, and documentation owners.

**Order:** Update OpenAPI and test inventory after P1 terminology and conformance decisions. Then repair contributor setup, version examples, and the repository map.

**Exit criteria:** Contributor setup matches the black-box test architecture; API prose uses canonical terms; test inventory covers OP#1–OP#13; release examples identify their version status.

### P3 — Editorial cleanup

**Findings:** GTS-026 through GTS-030.

**Suggested owners:** Documentation editor with review from specification maintainers for any sentence containing normative keywords.

**Order:** Perform only after P0–P2 text stabilizes.

**Exit criteria:** Claims are neutral and qualified; normative paragraphs are scannable; listed grammar defects are corrected; example introductions state purpose directly.

## ADR and maintainer-decision candidates

| Candidate | Related findings | Decision required |
|---|---|---|
| Document authority and conformance classes | GTS-011, GTS-012, GTS-017, GTS-019 | Define which artifact governs conflicts and which operation sets constitute conformance. |
| Identifier grammar clarification | GTS-003, GTS-013, GTS-025 | Confirm singleton `_` rules and the separation between lexical and semantic validation. |
| `x-gts-ref` canonical self-reference | GTS-014 | Select one spelling or define supported aliases and normalization. |
| Trait completeness registration timing | GTS-020 | Choose unconditional registration validation or the `validate=true` model. |
| Boolean `false` trait-schema consequences | GTS-021 | Define whether and how types beneath an unsatisfiable effective trait schema can register. |
| ADR-0001 scope amendment | GTS-022 | Limit “never rejected for shape” to derivation composition form. |
| Draft-07 composition successor | GTS-023 | Assign an owner, decision artifact, milestone, and interim guidance for the known hazard. |

These are proposals for maintainer action, not decisions made by this report.

## Verification strategy

Verification should combine static integrity checks, focused conformance tests, and full black-box testing against a selected server implementation. Commands below are proposed; this audit did not execute them.

### Static documentation checks

```bash
# Search for stale or contradictory literals after edits.
rg -n "op1_id_validation_test|type_combined\.v1|\.schema\.json|v0\.11|identitfiers|refererred|accordinly|deriver types" \
  README.md CONTRIBUTING.md tests examples adr

# Confirm all finding IDs remain represented in this report.
n=1; while [ "$n" -le 30 ]; do id=$(printf 'GTS-%03d' "$n"); rg -q "$id" docs/reports/gaps.md || exit 1; n=$((n + 1)); done

# Validate OpenAPI JSON syntax.
jq empty tests/openapi.json
```

The first search is a review aid, not a universal rejection rule. Some literals may remain in historical context or intentionally generated outputs.

### Focused behavioral verification

```bash
pytest tests/test_op8_compatibility_checking.py
pytest tests/test_op12_type_derivation_validation.py
pytest tests/test_op13_schema_traits_validation.py
pytest tests/test_xgts_keyword_placement.py
```

These are black-box HTTP tests and require a conforming server at the configured `GTS_BASE_URL`. They are not standalone unit tests for this repository.

### Full conformance verification

```bash
python -m pip install -r tests/requirements.txt
GTS_BASE_URL=http://127.0.0.1:8000 pytest tests
```

The Docker tags currently shown in `tests/README.md` are affected by GTS-018. Do not treat `v0.11` as the correct image for specification 0.12 without confirming the published release. The targeted Python selector in that guide is affected by GTS-008 until corrected. The TypeSpec and YAML commands are affected by GTS-005 and GTS-006 until their paths or workflow are repaired.

### Acceptance review

1. Review every normative edit against the approved authority policy.
2. Require tests for grammar, compatibility, registration timing, boolean schemas, and keyword placement.
3. Run a repository-relative Markdown link checker over README, ADRs, tests, and example guides.
4. Execute every documented command from its stated working directory in a clean environment.
5. Compare README version markers, release tags, and Docker examples before release.

## Appendix A — Finding index

| Range | Theme |
|---|---|
| GTS-001–GTS-003 | Normative compatibility, derivation, and grammar blockers |
| GTS-004–GTS-008 | Broken example and test workflows |
| GTS-009–GTS-010 | Contributor onboarding and repository architecture |
| GTS-011–GTS-012 | Conformance scope and document authority |
| GTS-013–GTS-016 | Identifier, reference, schema classification, and field-role consistency |
| GTS-017–GTS-019 | OpenAPI terminology, release versions, and test inventory |
| GTS-020–GTS-023 | Trait semantics, ADR scope, and deferred JSON Schema risk |
| GTS-024–GTS-026 | Authoring examples and audience accessibility |
| GTS-027–GTS-030 | Voice, structure, proofreading, and example introductions |

## Appendix B — Reviewed and excluded evidence inventory

### Primary reviewed evidence

- `README.md`
- `CONTRIBUTING.md`
- `adr/0001-derivation-form.md`
- `adr/0002-x-gts-traits-schema.md`
- `adr/0003-x-gts-traits-completeness.md`
- `adr/0004-x-gts-traits-merge-strategy.md`
- `tests/README.md`
- `tests/openapi.json`
- `tests/test_op8_compatibility_checking.py`
- `tests/test_op12_type_derivation_validation.py`
- `tests/test_op13_schema_traits_validation.py`
- `tests/test_xgts_keyword_placement.py`
- `examples/events/README.md`
- `examples/modules/README.md`
- `examples/typespec/vms/README.md`
- `examples/yaml/ui/README.md`

### Supporting evidence

- Example files named by the reviewed guides, used only to verify paths and formats.
- `.github/workflows/validate-schemas.yml` and `.github/workflows/release-tests-image.yml`, used only to understand documented validation and release expectations.

### Excluded review surfaces

- Test-source style, internal helper design, and implementation quality.
- Live server behavior, deployment configuration, and performance.
- Generated schema correctness beyond the specific references in the finding register.
- TypeSpec program semantics beyond the documented compiler input path.
- New requirements or normative behavior not present in the frozen register.


Field	Value
Repository	`GlobalTypeSystem/gts-spec`
Audited revision	`ef457e0acee74f76d40492b5686327d33ba1166f`
Audit branch	`docs/gts-spec-gap-report`
Report date	2026-07-16
Status	Action required
Scope	Static consistency audit of the specification, ADRs, conformance contract, tests, contributor guidance, and selected example guides

Severity	Definition
CRITICAL	A contradiction or broken workflow can cause incompatible implementations, invalid normative interpretation, or immediate failure of a primary documented task.
MAJOR	A material gap can produce divergent behavior, mislead implementers, or substantially impair conformance, maintenance, or onboarding.
MINOR	A localized language or presentation defect reduces clarity or confidence without changing intended behavior.

ID	Severity	Area	Gap type	Concise impact	Remediation class	Phase
GTS-001	CRITICAL	Compatibility	Spec/test contradiction	Implementations can reverse OP#8 results for required fields in open models.	Normative spec and conformance tests	P0
GTS-002	CRITICAL	Derivation	Normative contradiction	Schema authors may reject valid derived required fields.	Normative clarification	P0
GTS-003	CRITICAL	Identifier grammar	Prose/grammar contradiction	Parsers may accept reserved `_` in forbidden positions.	Grammar, regex, and negative tests	P0
GTS-004	CRITICAL	Events examples	Broken reference	The combined anonymous instance example cannot be opened.	Mechanical documentation fix	P0
GTS-005	CRITICAL	TypeSpec examples	Broken command	The documented compiler input is not found.	Mechanical command fix	P0
GTS-006	CRITICAL	YAML examples	Broken command	AJV validation targets an absent schema artifact.	Workflow documentation fix	P0
GTS-007	CRITICAL	YAML examples	Broken inventory	Six advertised artifacts cannot be located from their literals.	Link normalization	P0
GTS-008	CRITICAL	Test guide	Broken command	The documented pytest selector cannot locate the test.	Mechanical command fix	P0
GTS-009	MAJOR	Contributor guide	Incomplete repository map	Contributors do not discover ADR and conformance-test responsibilities.	Onboarding documentation	P2
GTS-010	MAJOR	Contributor guide	Stale architecture guidance	Contributors are directed toward an obsolete in-repository implementation model.	Onboarding and workflow alignment	P2
GTS-011	MAJOR	Conformance	Normative scope ambiguity	Mandatory OP rules appear under a section declared non-mandatory.	Governance and conformance classes	P0
GTS-012	MAJOR	Governance	Missing precedence	Conflicts among README, ADRs, OpenAPI, tests, and examples cannot be resolved consistently.	Authority policy	P0
GTS-013	MAJOR	Identifier validation	Example/regex contradiction	Prohibited single-segment instances remain accepted or demonstrated.	Regex scope and examples	P1
GTS-014	MAJOR	References	Syntax inconsistency	Implementers may support different self-reference spellings.	Maintainer decision and normalization rule	P1
GTS-015	MAJOR	Schema examples	Classification contradiction	Examples intended as schemas are classified as instances by Rule A.	Example completion or fragment labels	P1
GTS-016	MAJOR	Event scenario	Field-role inconsistency	The scenario alternates between `gtsId` and `type`, obscuring interoperable defaults.	Scenario consistency correction	P1
GTS-017	MAJOR	OpenAPI	Legacy terminology	Generated clients expose vague nouns inconsistent with canonical terms.	API description cleanup	P2
GTS-018	MAJOR	Releases	Stale runnable examples	Users may select a test image for spec 0.11 while reading spec 0.12.	Versioned example policy	P2
GTS-019	MAJOR	Test guide	Incomplete inventory	OP#12 and OP#13 conformance coverage is hidden.	Test documentation alignment	P2
GTS-020	MAJOR	Traits	ADR/spec contradiction	Registries may enforce completeness always or only when validation is enabled.	ADR or specification decision	P1
GTS-021	MAJOR	Traits	Boolean-schema contradiction	Implementers may incorrectly treat `false` as accepting an empty traits object.	ADR correction and tests	P1
GTS-022	MAJOR	Schema shape	ADR/spec contradiction	Keyword-placement rejection conflicts with an absolute no-shape-rejection claim.	Narrow ADR scope	P1
GTS-023	MAJOR	JSON Schema dialects	Untracked design hazard	Draft-07 composition can reject intended extensions without usable guidance.	Successor decision and interim guidance	P1
GTS-024	MAJOR	YAML examples	Normative overstatement	Authors may believe `allOf` is mandatory for derivation.	Example guide correction	P1
GTS-025	MAJOR	Identifier examples	Malformed examples	Readers copy identifiers missing a required relative-segment component.	Example normalization	P1
GTS-026	MINOR	Opening scope	Undefined acronyms	New schema authors cannot quickly interpret every advertised domain.	Editorial definition pass	P3
GTS-027	MINOR	Voice	Promotional language	Absolute claims reduce specification precision.	Editorial cleanup	P3
GTS-028	MINOR	Readability	Excessive sentence length	Independent normative rules are difficult to scan and implement.	Structural editing	P3
GTS-029	MINOR	Language	Spelling and grammar	Errors reduce confidence in implementation-facing instructions.	Proofreading	P3
GTS-030	MINOR	Modules example	Unclear introduction	Readers cannot quickly identify the example’s purpose.	Focused rewrite	P3

Candidate	Related findings	Decision required
Document authority and conformance classes	GTS-011, GTS-012, GTS-017, GTS-019	Define which artifact governs conflicts and which operation sets constitute conformance.
Identifier grammar clarification	GTS-003, GTS-013, GTS-025	Confirm singleton `_` rules and the separation between lexical and semantic validation.
`x-gts-ref` canonical self-reference	GTS-014	Select one spelling or define supported aliases and normalization.
Trait completeness registration timing	GTS-020	Choose unconditional registration validation or the `validate=true` model.
Boolean `false` trait-schema consequences	GTS-021	Define whether and how types beneath an unsatisfiable effective trait schema can register.
ADR-0001 scope amendment	GTS-022	Limit “never rejected for shape” to derivation composition form.
Draft-07 composition successor	GTS-023	Assign an owner, decision artifact, milestone, and interim guidance for the known hazard.

Range	Theme
GTS-001–GTS-003	Normative compatibility, derivation, and grammar blockers
GTS-004–GTS-008	Broken example and test workflows
GTS-009–GTS-010	Contributor onboarding and repository architecture
GTS-011–GTS-012	Conformance scope and document authority
GTS-013–GTS-016	Identifier, reference, schema classification, and field-role consistency
GTS-017–GTS-019	OpenAPI terminology, release versions, and test inventory
GTS-020–GTS-023	Trait semantics, ADR scope, and deferred JSON Schema risk
GTS-024–GTS-026	Authoring examples and audience accessibility
GTS-027–GTS-030	Voice, structure, proofreading, and example introductions

Uh oh!

Specification gap report: normative, conformance, and documentation inconsistencies #86

Description

Global Type System Specification Gap Report

Audit metadata

Executive summary

Scope, methodology, and evidence model

Exclusions and limitations

Severity definitions

Prioritized findings matrix

Detailed findings

GTS-001 — Minor-version compatibility table contradicts OP#8 for a new required field in an open model

GTS-002 — Derived-field guidance conflicts with the instance-set compatibility rule

GTS-003 — The _ placeholder restriction is not enforced by grammar or regex

GTS-004 — Events guide points to a nonexistent combined-instance file

GTS-005 — TypeSpec compilation command omits the source directory

GTS-006 — YAML AJV workflow references an absent JSON schema

GTS-007 — YAML artifact inventory uses six non-resolving literals

GTS-008 — Python test selector names the wrong file and working-directory path

GTS-009 — Contributor repository map omits ADR and test surfaces

GTS-010 — Contributor setup describes an obsolete reference-implementation model

GTS-011 — Mandatory operations sit beneath a non-mandatory heading

GTS-012 — Document authority and conflict precedence are undefined

GTS-013 — Single-segment instances are prohibited but still accepted or shown

GTS-014 — Self-reference syntax alternates between /$id and ./$id

GTS-015 — Standalone schema examples are classified as instances by Rule A

GTS-016 — Event scenario uses inconsistent type-reference fields

GTS-017 — OpenAPI summaries use vague legacy nouns

GTS-018 — Release and Docker examples remain pinned to specification 0.11

GTS-019 — Implemented-test inventory omits OP#12 and OP#13

GTS-020 — Trait completeness timing differs between ADR and specification

GTS-021 — ADR-0003 misstates boolean false validation

GTS-022 — ADR-0001’s no-shape-rejection claim is too broad

GTS-023 — Draft-07 composition hazard is deferred without ownership

GTS-024 — YAML authoring guide makes optional allOf mandatory

GTS-025 — Identifier examples omit a required relative-segment component

GTS-026 — Opening scope uses specialized acronyms without expansion

GTS-027 — Promotional and absolute language reduces precision

GTS-028 — Long paragraphs combine independent normative rules

GTS-029 — Implementation-facing prose contains recurring language defects

GTS-030 — Modules example introduction is unclear and ungrammatical

Cross-cutting root causes

Remediation roadmap

P0 — Governance and correctness blockers

P1 — Authority and normative semantics

P2 — Conformance interfaces, examples, tooling, and onboarding

P3 — Editorial cleanup

ADR and maintainer-decision candidates

Verification strategy

Static documentation checks

Focused behavioral verification

Full conformance verification

Acceptance review

Appendix A — Finding index

Appendix B — Reviewed and excluded evidence inventory

Primary reviewed evidence

Supporting evidence

Excluded review surfaces

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions

GTS-003 — The `_` placeholder restriction is not enforced by grammar or regex

GTS-014 — Self-reference syntax alternates between `/$id` and `./$id`

GTS-021 — ADR-0003 misstates boolean `false` validation

GTS-024 — YAML authoring guide makes optional `allOf` mandatory