Split README.md into Specification, Guide, and a thin README

[aviator5]

Problem

README.md has grown to ~1900 lines and mixes normative specification content (an RFC-style document) with informative guidance (motivation, use-cases, implementation recommendations). This makes it hard to read, hard to maintain, and hard to reference precisely (e.g. for conformance testing, which only cares about normative parts).

Proposal

Split into two documents plus a thin README. The Specification is treated as the normative RFC; the Guide is informative; the README is just an entry point.

SPECIFICATION.md (normative / RFC)

• Terminology (full version)
• Scope & Non-goals (from current §6)
• Identifier Format (current §2)
• Semantics & Capabilities, including the normative operations catalog OP#1–OP#13 (current §3 + §9.2)
• Versions Compatibility (current §4, kept inside the spec)
• Parsing & Validation (current §8)
• Collecting Identifiers with Wildcards (current §10)
• JSON & JSON Schema Conventions (current §11, consolidated with the $id/$ref rules currently duplicated in §9.1)
• x-gts-* JSON Schema Keywords — normative keyword semantics: x-gts-ref, x-gts-traits-schema / x-gts-traits, x-gts-final / x-gts-abstract (from current §9.6, §9.7, §9.11)

GUIDE.md (informative)

• Motivation (current §1)
• Typical Use-cases (current §5)
• Comparison with other identifiers (current §7)
• Reference Implementation Recommendations (non-normative part of §9): reference libraries, entity registration (§9.3), CLI support (§9.4), web server / OpenAPI (§9.5), YAML support (§9.8), TypeSpec support (§9.9), UUID as object IDs (§9.10)
• Notes & Best Practices (current §12)

README.md (thin entry point)

• Short description of GTS
• Short Terminology (full version lives in the Specification)
• Document Version table
• Testing link (current §13)
• Registered Vendors (current §14)
• Links to SPECIFICATION.md and GUIDE.md

Notes / things to resolve during the split

• §9 is not monolithic — it currently mixes normative keyword semantics and the OP catalog with genuinely informative implementation recommendations; these go to the Specification and the Guide respectively.
• Duplication §9.1 ↔ §11 — both describe how GTS identifiers are embedded in JSON $id/$ref/instance fields; consolidate into the Specification to avoid two sources of truth.
• Duplication §3.1 ↔ §9.2 — §3.1 describes operations conceptually while §9.2 lists OP#1–OP#13; decide whether to merge into a single normative Operations section.
• Document Version table — keep in README or move into the Specification (RFC versioning is usually part of the document)?
• Renumber sections within each new file, convert internal "see Section X.Y" references into cross-file links, and re-check relative links to examples/, adr/, and the test suite.

[stevesagronegocios673-ux]

Quick split-structure note after reading #78 and the current README: I agree with the three-document direction, but I would not split strictly by the current section numbers. I would split by what a conformance test, registry, or implementer needs to cite.

The current README's biggest boundary problem is section 9. The heading says Reference Implementation Recommendations, but the section contains both informative implementation advice and normative-looking contract material:

• OP#1-OP#13 in section 9.2
• x-gts-ref semantics in section 9.6
• x-gts-traits-schema / x-gts-traits semantics in section 9.7
• x-gts-final / x-gts-abstract semantics in section 9.11

Those read much closer to specification surface than guide material, especially because sections 9.7 and 9.11 use MUST/SHOULD language and define fail-fast behavior.

I would use this split rule:

SPECIFICATION.md = anything a validator, registry, implementation, or conformance suite can fail against.
GUIDE.md = anything that helps a human understand why/when/how to adopt GTS.
README.md = navigation + current draft + which doc should I read?

Concrete edits I would make during the split:

1. Merge section 3.1 and section 9.2 into one normative Operations Catalog in SPECIFICATION.md, instead of keeping conceptual operations in one place and OP#1-OP#13 later under implementation recommendations.
2. Move 9.6, 9.7, and 9.11 into the same normative area as JSON Schema conventions, because they define keyword semantics and rejection behavior, not just library advice.
3. Consolidate 9.1 with section 11 so $id, $ref, gts://, document categories, and instance/type extraction rules have one source of truth.
4. Keep the full Document Version table in SPECIFICATION.md, but leave a tiny current-draft line near the top of README, for example Current draft: 0.12 with a link to the version history.
5. Add a Moved sections map in the PR or README before merging, because external links may already point at anchors like #92---gts-operations-op1---op13 or #97---gts-type-schema-traits-x-gts-traits-schema--x-gts-traits.

Suggested thin README shape:

# Global Type System (GTS)

One-paragraph description.

Current draft: 0.12

## Read this first

- Need the normative rules? See SPECIFICATION.md.
- Need motivation, examples, and adoption guidance? See GUIDE.md.
- Need runnable examples? See examples/.
- Need conformance checks? See the test suite.

## Core idea

Short identifier example + one sentence explaining type vs instance.

## Documents

| Document | Purpose |
|---|---|
| SPECIFICATION.md | Normative rules for identifiers, parsing, validation, operations, JSON Schema keywords, and conformance. |
| GUIDE.md | Motivation, use cases, comparisons, implementation notes, and best practices. |

One small caution: I would not leave Testing only in the thin README. The README can link to it, but the normative specification should still define what the tests are proving, otherwise conformance readers have to bounce back to the entry page.

Want the fuller pass? I can send a tightened SPEC/GUIDE/README split map + 5 exact section-boundary edits.