# D2 Format Schema — File Format Specification
# KNO Schema Version: 0.0.6
#
# Describes D2 as a diagram scripting language and file format.
# D2 is a modern declarative diagramming language that turns text into diagrams.
#
# OFFICIAL DOCS:
#   - Main Site: https://d2lang.com/
#   - Language Tour: https://d2lang.com/tour/intro
#   - Spec: https://d2lang.com/tour/spec
#   - GitHub: https://github.com/terrastruct/d2
#
# This schema enables .kno systems to understand, process, and render D2 diagrams.

# =============================================================================
# SCHEMA DECLARATION
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# BASIC TIER
# =============================================================================
id: 01KGK3V73MCD4QWJ960GR5ZTM8
slug: d2-format
type: spec
version: 0.2.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "D2 Format Schema"
purpose: |
  Define D2 as a diagram format for .kno systems.

  **What is D2?** D2 is a modern diagram scripting language created by
  Terrastruct. It uses a declarative syntax to define diagrams that compile
  to SVG. D2 emphasizes readability, simplicity, and powerful layout engines.

  **Why D2 for Possibility?**
  - **Text-based** — Satisfies DC-3 (text-editor accessible)
  - **Git-friendly** — Human-readable diffs
  - **Auto-layout** — Multiple layout engines (dagre, elk, tala)
  - **Themes** — Built-in and customizable themes
  - **Composition** — Import and compose diagrams

  **Key Features:**
  ```
  ┌─────────────────────────────────────────────────────────────────────────┐
  │  D2 LANGUAGE FEATURES                                                   │
  ├─────────────────────────────────────────────────────────────────────────┤
  │  • Shapes: rectangle, oval, cylinder, diamond, hexagon, etc.            │
  │  • Connections: ->, <-, <->, --                                         │
  │  • Containers: Nested shapes with implicit containment                  │
  │  • Classes: Reusable styles                                             │
  │  • Icons: Built-in and custom icons                                     │
  │  • Markdown: Labels support markdown                                    │
  │  • Imports: Compose from multiple files                                 │
  │  • Layers: Animation and presentation layers                            │
  └─────────────────────────────────────────────────────────────────────────┘
  ```

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73MCD4QWJ960GR5ZTM8
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - file-formats
    - diagrams
    - visualization
    - developer-tools
  keywords:
    - d2
    - diagram
    - terrastruct
    - svg
    - architecture
    - flowchart

relationships:
  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification"

  produces:
    # Per bedrock § Bi-directional Produces Relationships:
    # Format schemas declare `produces` to their domain schema.
    # "Parsing D2 PRODUCES a diagram entity"
    - xri: "kno://specs/diagram-schema"
      reason: "Parsing D2 source produces DiagramElements (nodes, edges, containers)"

  related_to:
    - xri: "kno://concepts/svg"
      reason: "D2 compiles to SVG"
    - xri: "kno://specs/markdown-format"
      reason: "D2 labels support markdown"

  enables:
    - xri: "kno://capabilities/diagram-rendering"
      reason: "Render D2 source to SVG"
    - xri: "kno://capabilities/architecture-visualization"
      reason: "Visualize system architecture"

quality:
  completeness: 0.9
  last_reviewed: "2026-01-14"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# HISTORY
# =============================================================================
_history:
  retention: full
  format: changelog

  changelog:
    - version: "0.2.0"
      date: "2026-01-15"
      author: "claude"
      summary: "Add produces relationship to diagram-schema"
      changes:
        - "Added `produces: diagram-schema` per bedrock § Bi-directional Produces Relationships"
        - "Moved diagram-schema from related_to to produces (semantic upgrade)"
        - "Documents that parsing D2 produces DiagramElements"

    - version: "0.1.0"
      date: "2026-01-14"
      author: "claude"
      summary: "Initial D2 format schema"
      changes:
        - "Created from first principles"
        - "Referenced official D2 documentation"
        - "Defined syntax elements and themes"

# =============================================================================
# SPECIFICATION CONTENT
# =============================================================================
spec:
  status: Draft

  # ---------------------------------------------------------------------------
  # Official Standards References
  # ---------------------------------------------------------------------------
  standards:
    - name: "D2 Language"
      url: "https://d2lang.com/"
      author: "Terrastruct"
      year: 2022
      description: |
        Official D2 documentation and language reference.
        D2 is "a modern diagram scripting language that turns text into diagrams."

    - name: "D2 Language Tour"
      url: "https://d2lang.com/tour/intro"
      description: |
        Interactive tour of D2 language features with examples.
        Covers shapes, connections, containers, styling, and layout.

    - name: "D2 Specification"
      url: "https://d2lang.com/tour/spec"
      description: |
        Formal language specification including grammar and semantics.

    - name: "D2 GitHub Repository"
      url: "https://github.com/terrastruct/d2"
      description: |
        Open-source D2 compiler. MIT licensed.
        Includes CLI, library, and layout engines.

    - name: "D2 Cheat Sheet"
      url: "https://d2lang.com/tour/cheat-sheet"
      description: |
        Quick reference for common D2 syntax patterns.

  # ---------------------------------------------------------------------------
  # Format Definition
  # ---------------------------------------------------------------------------
  format:
    name: "D2"
    mime_type: "text/plain"
    extensions:
      - ".d2"
    encoding: "UTF-8"
    line_endings:
      - "LF" # Unix (preferred)
      - "CRLF" # Windows (accepted)

  # ---------------------------------------------------------------------------
  # Syntax Elements
  # ---------------------------------------------------------------------------
  syntax:
    shapes:
      description: "Basic shape declaration"
      examples:
        - "box"
        - "box: Label text"
        - "box.shape: oval"

    connections:
      description: "Connect shapes with edges"
      examples:
        - "a -> b"
        - "a <- b"
        - "a <-> b"
        - "a -- b"
        - "a -> b: edge label"

    containers:
      description: "Nest shapes inside containers"
      examples:
        - |
          outer: {
            inner
          }
        - |
          server: {
            api
            db
          }

    styles:
      description: "Apply visual styles"
      examples:
        - 'box.style.fill: "#ff0000"'
        - "box.style.stroke: blue"
        - "box.style.stroke-width: 3"

    classes:
      description: "Define reusable style classes"
      examples:
        - |
          classes: {
            error: {
              style.fill: red
            }
          }
          box.class: error

    icons:
      description: "Add icons to shapes"
      examples:
        - "box.icon: https://icons.terrastruct.com/aws/Compute/Amazon-EC2.svg"
        - "box.icon: ./local-icon.svg"

    markdown:
      description: "Use markdown in labels"
      examples:
        - |
          box: |md
            # Heading
            - List item
          |

  # ---------------------------------------------------------------------------
  # Layout Engines
  # ---------------------------------------------------------------------------
  layout_engines:
    - name: "dagre"
      description: "Default engine, fast hierarchical layout"
      url: "https://github.com/dagrejs/dagre"

    - name: "elk"
      description: "Eclipse Layout Kernel, more layout options"
      url: "https://www.eclipse.org/elk/"

    - name: "tala"
      description: "Terrastruct's proprietary engine (requires license)"
      url: "https://terrastruct.com/tala"

  # ---------------------------------------------------------------------------
  # Themes
  # ---------------------------------------------------------------------------
  themes:
    description: "D2 includes built-in themes for consistent styling"
    built_in:
      - id: 0
        name: "Default"
      - id: 1
        name: "Neutral Grey"
      - id: 3
        name: "Flagship Terrastruct"
      - id: 4
        name: "Cool Classics"
      - id: 5
        name: "Mixed Berry Blue"
      - id: 6
        name: "Grape Soda"
      - id: 7
        name: "Aubergine"
      - id: 8
        name: "Colorblind Clear"
      - id: 100
        name: "Origami"
      - id: 200
        name: "Terminal"
        notes: "Dark theme, good for docs"
    usage: "d2 --theme 200 input.d2 output.svg"

  # ---------------------------------------------------------------------------
  # Usage in .kno
  # ---------------------------------------------------------------------------
  kno_integration:
    description: |
      In the .kno ecosystem, D2 serves as a primary diagram authoring format.
      Diagrams can be:
      - Embedded in .kno files (content.d2 field)
      - Referenced as external .d2 files (source.xri)
      - Stored alongside ASCII representations for DC-3 compliance

    patterns:
      - name: "Embedded D2 Source"
        example: |
          content:
            d2: |
              direction: right
              a -> b -> c

      - name: "External D2 Reference"
        example: |
          source:
            xri: "kno://diagrams/arch-overview.d2"
            format: d2

      - name: "Dual Format (D2 + ASCII)"
        description: "Both D2 source and ASCII representation for DC-3"
        example: |
          content:
            d2: |
              a -> b
            ascii: |
              ┌───┐     ┌───┐
              │ a │────▶│ b │
              └───┘     └───┘

  # ---------------------------------------------------------------------------
  # Possibility Project Usage
  # ---------------------------------------------------------------------------
  pspace_conventions:
    location: "diagrams/*.d2"
    naming: "{type}-{subject}.d2"
    rendering:
      command: "d2 --theme 200 input.d2 output.svg"
      theme: 200 # Terminal theme
    examples:
      - "arch-schema-ecosystem.d2"
      - "flow-corpus-import.d2"
      - "layout-specs-slug.d2"

# =============================================================================
# ANNOTATIONS
# =============================================================================
annotations:
  design_notes: |
    **Why reference official D2 docs?**

    The ontological chain requires that format schemas trace back to
    authoritative sources. For D2:

    1. **d2lang.com** — Official documentation and language reference
    2. **Language Tour** — Interactive examples and syntax guide
    3. **GitHub repo** — Open-source implementation

    This enables:
    - Validation against known syntax rules
    - Consistent rendering with official tooling
    - Upgrade paths as D2 evolves

  dc3_compliance: |
    D2 satisfies DC-3 (Text-Editor Accessible) because:
    - Plain text source files
    - Human-readable syntax
    - Git-friendly diffs
    - Works in any text editor

    For maximum accessibility, diagrams should also have an ASCII
    representation that conveys the same information.