# KAML: Knowledge-Adapted Markup Language Specification # KNO Schema Version: 0.0.4 # # KAML is an independent markup language that .kno files happen to use. # This specification is self-describing: a .kno file defining the markup # language that .kno files are written in. # # KAML is NOT a serialization format — it's a markup language built ON TOP # of YAML serialization. The relationship is: # # KAML (markup language) → uses → YAML (serialization format) # .kno (file format) → uses → KAML (markup language) # # KAML could theoretically be adopted by other file formats that want # structured knowledge representation with semantic addressing. # ============================================================================= # SCHEMA DECLARATION # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # BASIC TIER # ============================================================================= id: 01KGK3V73NKZAWSGJ7C2D3VJ9E slug: kaml-spec type: spec version: 0.1.0 # ============================================================================= # STANDARD TIER # ============================================================================= title: "KAML: Knowledge-Adapted Markup Language" purpose: | KAML (Knowledge-Adapted Markup Language) is a markup language for structured knowledge documents. It uses YAML as its serialization format, with microsyntax conventions that enable: - **Semantic addressing** via XRI (Extensible Resource Identifiers) - **Hierarchical containment** via `_contains` reserved key - **Agent-optimized retrieval** via `_index` navigation hints - **Section markers** for grep-based navigation KAML is INDEPENDENT of .kno — it defines the markup conventions, while .kno defines a file format that uses KAML. Other formats could adopt KAML. # ============================================================================= # RICH TIER # ============================================================================= provenance: origin: id: 01KGK3V73NKZAWSGJ7C2D3VJ9E timestamp: "2026-02-04T01:47:56Z" tool: manual-migration taxonomy: topics: - markup-language - knowledge-representation - semantic-addressing - yaml keywords: - kaml - markup - xri - microsyntax - yaml - container - navigation relationships: depends_on: - xri: "kno://standards/yaml-1-2" reason: "KAML uses YAML 1.2 as serialization" enables: - xri: "kno://specs/kno-spec" reason: ".kno format uses KAML" related_to: - xri: "kno://docs/architecture/bedrock/kno-foundational-principles" reason: "Design principles for KAML" - xri: "kno://docs/architecture/bedrock/kno-format-requirements" reason: "Requirements that KAML satisfies" quality: completeness: 0.85 last_reviewed: "2026-01-07" review_status: draft # ============================================================================= # @kno:spec # ============================================================================= _contains: # =========================================================================== # @kno:spec/overview # =========================================================================== overview: $schema: kno-section@0.0.1 id: overview title: "Overview" content: summary: | KAML is a markup language — not a serialization format. It defines conventions for structured knowledge documents that: 1. Are valid YAML (standard parsers work as fallback) 2. Include microsyntax for enhanced tooling 3. Degrade gracefully when microsyntax is ignored 4. Support agent-optimized retrieval patterns layering: | ┌─────────────────────────────────────────┐ │ KAML (markup language) │ 🐪 │ - XRI addressing │ │ - Container semantics (_contains) │ │ - Navigation index (_index) │ │ - Section markers (# @kno:) │ │ - Schema declarations ($schema) │ ├─────────────────────────────────────────┤ │ YAML (serialization format) │ │ - Key: value syntax │ │ - Indentation structure │ │ - Block scalars │ │ - Comments │ ├─────────────────────────────────────────┤ │ File Extension (.kno, .kaml, etc.) │ │ - Indicates KAML content │ └─────────────────────────────────────────┘ terminology: - term: "KAML" definition: "The markup language (conventions + microsyntax)" example: "KAML is a knowledge-adapted markup language" - term: "KAML document" definition: "A file written in KAML" example: "This KAML document contains..." - term: "YAML" definition: "The serialization format KAML uses" example: "KAML uses YAML serialization" - term: "Microsyntax" definition: "KAML-specific patterns in opaque YAML positions" example: "XRI strings, section markers, reserved keys" # =========================================================================== # @kno:spec/principles # =========================================================================== principles: $schema: kno-section@0.0.1 id: principles title: "Core Principles" content: description: | Four principles govern KAML design, ensuring compatibility with standard YAML tools while enabling enhanced functionality. principles: - id: P-KAML-01 name: "YAML Foundation" statement: | Every KAML document MUST be valid YAML 1.2. Standard YAML parsers (`yaml.safe_load()`) MUST successfully parse any KAML document. rationale: "Ensures universal fallback and tooling compatibility" - id: P-KAML-02 name: "Microsyntax in Opaque Positions" statement: | KAML microsyntax lives in positions YAML treats as opaque: - String values (XRI references, schema URIs) - Comments (section markers, hints) - Reserved keys (_index, _contains, _offset) rationale: "Standard parsers ignore what they don't understand" - id: P-KAML-03 name: "Graceful Degradation" statement: | If KAML microsyntax is missing, malformed, or ignored: - Document MUST still be valid and usable - Standard YAML parse + tree navigation MUST work - Only performance/convenience degrades, not correctness rationale: "Robust fallback guarantees accessibility" - id: P-KAML-04 name: "Enhancement Through Tooling" statement: | Custom KAML tooling MAY interpret microsyntax to provide: - Partial parsing (skip to section) - Index-based navigation - Pre-computed relationship traversal - Chunk retrieval for RAG rationale: "Enables optimization without mandating it" # =========================================================================== # @kno:spec/reserved-keys # =========================================================================== reserved-keys: $schema: kno-section@0.0.1 id: reserved-keys title: "Reserved Keys" content: description: | KAML reserves certain keys with underscore prefixes for structural purposes. These keys have special meaning to KAML tooling. keys: - key: "$schema" purpose: "Schema declaration with version" required: true format: "{schema-name}@{version}" examples: - "kno@0.0.9" - "kb-article@0.1" - "https://schemas.example.com/type@1.0" - key: "_index" purpose: "Navigation index for tooling" required: false description: | Provides hints for fast navigation. Derived from content, not authoritative. Tooling may use without verification. structure: - path: "relative/path" - line: 42 - hash: "sha256:abc..." - keywords: ["k1", "k2"] - size: 1024 - key: "_contains" purpose: "Nested container contents" required: "If container" description: | Contains nested KAML entities. Each child is a complete entity with its own $schema, id, and optional _contains. - key: "_offset" purpose: "Line hint for fast seeking" required: false description: "Byte or line offset for quick file positioning" # =========================================================================== # @kno:spec/xri # =========================================================================== xri: $schema: kno-section@0.0.1 id: xri title: "XRI: Extensible Resource Identifier" content: description: | XRIs identify entities within and across KAML documents. They provide semantic addressing without requiring file paths. types: - name: "Fragment XRI (Internal)" pattern: "#path/to/entity" meaning: "Relative to current document" resolution: "_contains.path._contains.to._contains.entity" examples: - xri: "#articles" resolves_to: "_contains.articles" - xri: "#articles/intro" resolves_to: "_contains.articles._contains.intro" - xri: "#schema/tiers/basic" resolves_to: "_contains.schema._contains.tiers._contains.basic" - name: "Absolute XRI (External)" pattern: "kno://authority/path/to/entity" meaning: "Cross-document reference" components: - part: "kno://" meaning: "Scheme" - part: "authority" meaning: "Container ID or registry namespace" - part: "/path/to/entity" meaning: "Path within container" - part: "#fragment" meaning: "Optional internal reference" examples: - xri: "kno://specs/kno-spec" meaning: "The kno-spec entity in specs namespace" - xri: "kno://pspace-kb/articles/p1#overview" meaning: "Section overview of P1 article in pspace-kb" - name: "Parent Reference" pattern: "#" meaning: "Immediate parent container" description: "The bare # refers to the parent in the _contains tree" # =========================================================================== # @kno:spec/section-markers # =========================================================================== section-markers: $schema: kno-section@0.0.1 id: section-markers title: "Section Markers" content: format: "# @kno:{path}" description: | Section markers are YAML comments that: - Standard parsers ignore completely - KAML tooling uses for indexing and grep-based navigation - Enable partial file parsing (read from marker forward) purpose: - Indexing without full parse - grep-based section location - Partial file retrieval - Human navigation aid examples: - marker: "# @kno:articles" meaning: "Start of articles section" - marker: "# @kno:articles/foundational-principles" meaning: "Start of foundational-principles within articles" - marker: "# @kno:schema/tiers/basic" meaning: "Start of basic tier within schema section" # =========================================================================== # @kno:spec/parser-behavior # =========================================================================== parser-behavior: $schema: kno-section@0.0.1 id: parser-behavior title: "Parser Behavior" content: overview: | KAML supports two parsing modes: standard YAML (fallback) and enhanced KAML (optimized). Both must produce equivalent results for the document content — only performance differs. modes: - mode: "Standard YAML (Fallback)" description: "Uses yaml.safe_load() — always works" characteristics: - "Parses entire file" - "O(n) navigation through _contains" - "No partial retrieval" - "Ignores _index and markers" - mode: "Enhanced KAML (Optimized)" description: "Interprets microsyntax for performance" characteristics: - "Uses _index for O(1) lookup" - "Falls back to marker scanning" - "Falls back to tree navigation" - "Supports partial parsing from line offset" - "Keyword search without full content parse" fallback_algorithm: | ```python import yaml def parse_kaml_basic(file_path): """Fallback: standard YAML parse of KAML document.""" with open(file_path) as f: return yaml.safe_load(f) def navigate_basic(data, xri): """Navigate using XRI without optimization.""" if xri.startswith('#'): path = xri[1:].split('/') node = data for segment in path: node = node.get('_contains', {}).get(segment, {}) return node else: raise ValueError("External XRI requires resolver") ``` # =========================================================================== # @kno:spec/container-structure # =========================================================================== container-structure: $schema: kno-section@0.0.1 id: container-structure title: "Container Structure" content: manifest_first: | Every KAML container follows the manifest-first pattern: 1. Root level contains manifest metadata (id, type, $schema) 2. `contains` field lists what's inside (for discovery) 3. `_index` provides navigation hints (for tooling) 4. `_contains` holds the actual nested entities This enables: - Discovery: `contains` lists children with metadata - Query without parse: Keywords, titles in manifest - Navigation: `_index` provides line hints - Lazy loading: Parse manifest first, dive deeper as needed nested_containers: | Containers can contain containers. The XRI path reflects nesting: - `#articles` → `_contains.articles` - `#articles/intro` → `_contains.articles._contains.intro` - `#articles/intro/section1` → `_contains.articles._contains.intro._contains.section1` example: | ```yaml $schema: kno@0.0.9 id: my-container type: manifest contains: - xri: "#child-1" title: "Child One" keywords: [important] _index: - path: "child-1" line: 20 _contains: # @kno:child-1 child-1: $schema: article@0.0.1 id: child-1 title: "Child One" # ... content ``` # =========================================================================== # @kno:spec/index-generation # =========================================================================== index-generation: $schema: kno-section@0.0.1 id: index-generation title: "Index Generation" content: description: | The `_index` is derived, not authoritative. Tools that write KAML documents SHOULD generate it. Tools that read KAML documents MAY use it for optimization but MUST work without it. properties: - property: "Derived" meaning: "Generated from content, not authoritative" - property: "Optional" meaning: "Tooling must work without it" - property: "Trusted" meaning: "Tooling may use without verification (for speed)" - property: "Regenerable" meaning: "Can be rebuilt from content at any time" algorithm: | ```python def generate_index(data, path="", result=None): """Generate _index from _contains tree.""" if result is None: result = [] if 'id' in data: entry = { 'path': path, 'keywords': data.get('keywords', []) + data.get('topics', []), } if 'title' in data: entry['title'] = data['title'] result.append(entry) for name, child in data.get('_contains', {}).items(): child_path = f"{path}/{name}" if path else name generate_index(child, child_path, result) return result ``` # ============================================================================= # DESIGN RATIONALE # ============================================================================= _design_rationale: $schema: kno-section@0.0.1 id: design-rationale title: "Design Rationale" content: problem: | Markdown fails the triple-audience requirement: - Agent: Must parse prose to extract facts; no semantic navigation - Programmatic: No schema, no structure, parse-dependent - Human: Works well Pure YAML satisfies standard parser compatibility but constrains optimization (must parse entire file for any query). Custom syntax (like MIME) enables optimization but loses fallback and tooling ecosystem. solution: | KAML is the hybrid solution: Use YAML as the foundation, with microsyntax conventions that: 1. Are ignored by standard parsers (comments, string values) 2. Are interpreted by KAML tooling for enhanced access 3. Provide graceful degradation — fallback always works This preserves: - YAML compatibility (standard parsers work) - Agent optimization (microsyntax unlocks fast navigation) - Text-editor accessibility (YAML syntax highlighting works) - Custom tooling (enhanced parsers interpret microsyntax) # ============================================================================= # OPEN QUESTIONS # ============================================================================= _open_questions: - id: "KAML-01" question: "Should _index be in a separate section or inline in contains?" priority: "Medium" - id: "KAML-02" question: "How to handle line number drift after edits?" priority: "High" - id: "KAML-03" question: "Should section markers include hash for integrity?" priority: "Low" - id: "KAML-04" question: "XRI resolution for federated/external references?" priority: "Medium" - id: "KAML-05" question: "Should _contains be renamed (e.g., _children, _parts)?" priority: "Low" # ============================================================================= # HISTORY # ============================================================================= _history: - version: "0.1.0" date: "2026-01-07" summary: "Initial spec extracted from kno-serialization-design.md" changes: - "Established KAML as independent markup language" - "Documented four core principles (P-KAML-01 to P-KAML-04)" - "Defined reserved keys ($schema, _index, _contains, _offset)" - "Specified XRI syntax (fragment, absolute, parent)" - "Documented section markers and parser behavior" - "Included index generation algorithm" # ============================================================================= # CONTAINER TIER — Navigation Index # ============================================================================= _index: - path: "identity" line: 18 keywords: [id, type, version, kaml-spec] - path: "spec/principles" line: 100 keywords: [P-KAML-01, P-KAML-02, P-KAML-03, P-KAML-04] - path: "spec/reserved_keys" line: 180 keywords: [$schema, _index, _contains, _offset] - path: "spec/xri_syntax" line: 260 keywords: [fragment, absolute, parent, resolution] - path: "spec/section_markers" line: 350 keywords: [header, body, trailer, "section-markers"] - path: "spec/parser" line: 420 keywords: [parse, index-generation, algorithm] contains: - xri: "#identity" role: section title: "Spec Metadata" keywords: [id, type, version] - xri: "#spec" role: section title: "KAML Specification" keywords: [principles, reserved-keys, xri, parser]