Specification
The full GCF specification lives in SPEC.md at the repository root.
It covers:
- Overview (two profiles, design goals)
- Grammar (EBNF, both graph and tabular profiles)
- Header fields (required and optional, graph profile)
- Node line format (positional encoding, graph profile)
- Edge line format (local ID references, graph profile)
- Group headers (distance-based sections, graph profile) 6a. Tabular encoding (generic profile: arrays of objects, nested records, pipe-separated rows)
- Session statefulness (bare reference protocol)
- Delta encoding extension (three-outcome protocol)
- Comments
- Token savings analysis (both graph and tabular profiles)
- Design constraints (text-only, line-oriented, deterministic, shallow nesting)
- Conformance (encoder and decoder checklists for both profiles)
- Security considerations (injection, memory, sanitization)
- MIME type (
application/vnd.gcf+text, file extension.gcf) - Versioning (GCF, GCF2, GCF3, ...)
- Intellectual property (MIT, no patents)
Version
Current: GCF v1.1 (stable, 2026-06-04)
Conventions
The specification uses RFC 2119 keywords (MUST, SHOULD, MAY) to define normative requirements for encoders and decoders.
Profiles
GCF supports two encoding profiles that share the same grammar primitives (## headers, @ IDs, positional fields):
- Graph profile (Sections 3-6): Encodes code graph payloads (symbols, edges, distance groups) for MCP tool responses.
- Tabular profile (Section 6a): Encodes arbitrary structured data (arrays of objects, nested records, mixed types) using positional rows and pipe separators.
Implementations MAY support one or both profiles.
Conformance
The specification defines conformance checklists for:
- Graph encoder (Section 12.1): header format, ID assignment, score formatting, edge validation, determinism
- Tabular encoder (Section 12.2): header counts, pipe separators, positional encoding, null handling
- Graph decoder (Section 12.3): header parsing, node/edge parsing, kind expansion, error handling
- Tabular decoder (Section 12.4): header parsing, row splitting, field validation
Stability guarantee
The v1.1 format is stable. Existing payloads will always parse correctly with future decoders. New features (if any) will be additive and backwards-compatible.