# YAML Format Schema — File Format Specification # KNO Schema Version: 0.0.9 # # Describes YAML as a data serialization format for .kno systems. # YAML is used for configuration, knowledge representation, and data exchange. # # OFFICIAL SPECS: # - YAML 1.2: https://yaml.org/spec/1.2.2/ # - YAML.org: https://yaml.org/ # - JSON Schema: https://json-schema.org/ (YAML superset of JSON) # # KEY: YAML is the ONLY format where domain routing VARIES by content. # Unlike Markdown (always → document) or D2 (always → diagram), # YAML files may be config, knowledge, data, or even .kno entities. # # This schema enables .kno systems to understand, process, and route YAML files # to the appropriate domain transformer based on content inspection. # ============================================================================= # SCHEMA DECLARATION # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # BASIC TIER # ============================================================================= id: 01KHS2ZAT88PEK5GK9DN8MX6G3 slug: yaml-format type: spec version: 0.1.0 # ============================================================================= # STANDARD TIER # ============================================================================= title: "YAML Format Schema" purpose: | Define YAML as a file format for .kno systems. **What is YAML?** YAML (YAML Ain't Markup Language) is a human-friendly data serialization language. It is commonly used for configuration files and in applications where data is being stored or transmitted. **Why is YAML special for .kno?** Unlike other format→domain mappings (Markdown→document, D2→diagram), YAML's domain mapping **varies by content**: ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ YAML DOMAIN ROUTING (content-dependent) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ docker-compose.yml → config (services: key) │ │ .github/workflows/*.yml → config (on:/jobs: keys) │ │ glossary-terms.yaml → knowledge ($schema: knowledge-base) │ │ *.kno.yaml → (skip — legacy format) │ ## kno-yaml-allowed-block: format-routing diagram names the legacy extension as the SKIP branch │ other.yaml → config (default fallback) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` **Key Characteristics:** - **Human-readable** — Whitespace-significant, minimal punctuation - **JSON superset** — Every JSON document is valid YAML - **Multi-document** — Supports `---` document separators - **Anchors & aliases** — `&anchor` and `*alias` for DRY - **Complex types** — Maps, sequences, scalars, tags See also: [KAML specification](kno://specs/kaml-spec) — KAML is a markup language built ON TOP of YAML serialization. YAML defines syntax; KAML defines semantic conventions. # ============================================================================= # RICH TIER — Relationships # ============================================================================= provenance: origin: id: 01KHS2ZAT88PEK5GK9DN8MX6G3 timestamp: "2026-02-18T12:00:00Z" tool: manual-creation taxonomy: topics: - file-formats - data-serialization - configuration - knowledge-representation keywords: - yaml - serialization - configuration - data-format - human-readable relationships: depends_on: - xri: "kno://specs/kno-spec" reason: "Conforms to KNO format specification" produces: # YAML is unique: it produces MULTIPLE domain types based on content - xri: "kno://specs/config-schema" reason: "YAML configuration files produce config entities" - xri: "kno://specs/knowledge-base-schema" reason: "YAML knowledge files produce knowledge-base entities" related_to: - xri: "kno://specs/kaml-spec" reason: "KAML markup language uses YAML as its serialization format" - xri: "kno://specs/markdown-format" reason: "Markdown and YAML are complementary formats" - xri: "kno://standards/json" reason: "JSON is a subset of YAML" enables: - xri: "kno://capabilities/config-extraction" reason: "Extract service topology, environment variables, ports" - xri: "kno://capabilities/knowledge-extraction" reason: "Extract structured knowledge from YAML data files" quality: completeness: 0.85 last_reviewed: "2026-02-18" review_status: draft reviewed_by: "claude" # ============================================================================= # HISTORY # ============================================================================= _history: retention: full format: changelog changelog: - version: "0.1.0" date: "2026-02-18" author: "claude" summary: "Initial YAML format schema — closes Gap #1 from file type catalog" changes: - "Created from first principles per bedrock system architecture" - "Documented content-dependent domain routing (unique to YAML)" - "Referenced official YAML 1.2 specification" - "Added produces relationships to config and knowledge-base schemas" - "Noted relationship to KAML markup language" # ============================================================================= # SPECIFICATION CONTENT # ============================================================================= spec: status: Draft # --------------------------------------------------------------------------- # Official Standards References # --------------------------------------------------------------------------- standards: - name: "YAML 1.2" url: "https://yaml.org/spec/1.2.2/" year: 2021 description: | The current YAML specification. YAML 1.2 is a superset of JSON, meaning every JSON document is a valid YAML document. The spec defines scalars, sequences, mappings, anchors, aliases, and tags. - name: "YAML 1.1" url: "https://yaml.org/spec/1.1/" year: 2005 description: | The widely-deployed prior version. Notable differences from 1.2: sexagesimal numbers (60:00 = 3600), boolean variants (yes/no/on/off), and octal format (0777 vs 0o777). Many parsers still default to 1.1. # --------------------------------------------------------------------------- # Format Specification # --------------------------------------------------------------------------- format: mime_types: - "text/yaml" - "application/x-yaml" - "text/x-yaml" extensions: - ".yaml" - ".yml" encoding: "UTF-8" line_endings: "LF or CRLF" # --------------------------------------------------------------------------- # Data Types # --------------------------------------------------------------------------- data_types: scalars: - type: "string" description: "Quoted or plain text" examples: ["hello", "'quoted'", '"double-quoted"'] - type: "integer" description: "Whole numbers" examples: ["42", "0xFF", "0o77", "0b1010"] - type: "float" description: "Floating-point numbers" examples: ["3.14", "6.02e23", ".inf", ".nan"] - type: "boolean" description: "True/false values" examples: ["true", "false"] - type: "null" description: "Null/empty values" examples: ["null", "~", ""] - type: "timestamp" description: "Date and time values" examples: ["2026-02-18", "2026-02-18T12:00:00Z"] collections: - type: "mapping" description: "Key-value pairs (associative array)" syntax: "key: value" - type: "sequence" description: "Ordered list of items" syntax: "- item" # --------------------------------------------------------------------------- # Domain Routing Rules # --------------------------------------------------------------------------- domain_routing: description: | YAML is the ONLY format where the domain cannot be determined from the file extension alone. Domain routing must inspect file content or path to determine the appropriate transformer. rules: - priority: 1 condition: "File ends with .kno.yaml or .kno.yml" # kno-yaml-allowed: routing condition names the legacy extension being filtered domain: "skip" reason: "Legacy .kno format — not supported for transformation" - priority: 2 condition: "Has $schema key starting with 'knowledge'" domain: "knowledge" reason: "Self-declaring knowledge entity" - priority: 3 condition: "Has 'services:' top-level key AND filename matches docker-compose pattern" domain: "config" subtype: "docker-compose" reason: "Docker Compose configuration" - priority: 4 condition: "Has 'on:' AND 'jobs:' top-level keys" domain: "config" subtype: "github-actions" reason: "GitHub Actions workflow" - priority: 5 condition: "Has 'apiVersion:' AND 'kind:' top-level keys" domain: "config" subtype: "kubernetes" reason: "Kubernetes manifest" - priority: 6 condition: "Has 'openapi:' top-level key" domain: "config" subtype: "openapi" reason: "OpenAPI specification" - priority: 7 condition: "Content matches other known config patterns" domain: "config" subtype: "detected" reason: "Known configuration format" - priority: 8 condition: "Default fallback" domain: "config" subtype: "generic" reason: "Unrecognized YAML defaults to generic config" # ============================================================================= # CONTAINER TIER — Navigation Index # ============================================================================= _index: - path: "identity" line: 27 keywords: [id, type, version, yaml-format] - path: "spec/standards" line: 120 keywords: [yaml-1-2, yaml-1-1, specification] - path: "spec/format" line: 150 keywords: [mime, extension, encoding] - path: "spec/data_types" line: 165 keywords: [scalar, mapping, sequence, types] - path: "spec/domain_routing" line: 200 keywords: [routing, domain, content-aware, config, knowledge] contains: - xri: "#identity" role: section title: "Spec Metadata" keywords: [id, type, version] - xri: "#spec" role: section title: "YAML Specification" keywords: [standards, format, data-types, routing]