# Diagram Domain Schema — Layer 2 Entity Type # KNO Schema Version: 0.0.6 # # Layer 2 domain schema for Diagram entities — visual representations. # Supports ASCII art, D2, Mermaid, graph views, and other diagram formats. # # EXTENDS: document-schema.kno (Layer 2 base) # COMPOSES: identity-schema, history-schema, quality-schema (Layer 1) # ENABLES: Diagram instances in content/diagrams/ # ============================================================================= # BASIC TIER (required per kno-spec.kno) # ============================================================================= $schema: kno@0.0.9 id: 01KGK3V73FB7FDQBB8QBAWD7F0 slug: diagram-schema type: spec version: 0.0.3 # ============================================================================= # STANDARD TIER # ============================================================================= title: "Diagram Domain Schema" purpose: | Define the schema for Diagram entities — visual representations of concepts. A Diagram represents a visual artifact in the Possibility system: - **ASCII art** — Unicode box-drawing diagrams (DC-3 compliant) - **D2** — Modern diagram scripting language - **Mermaid** — Markdown-friendly diagrams - **Other formats** — PlantUML, GraphViz, etc. Diagrams are stored as .kno files with source content embedded. They can have multiple views: source, rendered preview, alternate formats. # ============================================================================= # RICH TIER — Relationships # ============================================================================= provenance: origin: id: 01KGK3V73FB7FDQBB8QBAWD7F0 timestamp: "2026-02-04T01:47:56Z" tool: manual-migration taxonomy: topics: - diagrams - visualization - architecture - domain-schemas keywords: - diagram - ascii - d2 - mermaid - flowchart - architecture - visualization relationships: extends: - xri: "kno://specs/document-schema" reason: "Layer 2 base type for textual entities" depends_on: - xri: "kno://specs/kno-spec" reason: "Conforms to KNO format specification v0.0.6" produced_by: - xri: "kno://specs/d2-format" reason: "Primary diagram authoring format — see d2lang.com" - xri: "kno://formats/mermaid" reason: "Markdown-friendly diagrams" - xri: "kno://formats/ascii" reason: "Unicode box-drawing for DC-3 compliance" composes: - xri: "kno://specs/identity-schema" reason: "Layer 1: canonical_id, local_ids" - xri: "kno://specs/history-schema" reason: "Layer 1: _history, changelog" - xri: "kno://specs/quality-schema" reason: "Layer 1: quality, validation" related_to: - xri: "kno://specs/document-schema" reason: "Diagrams are often embedded in documents" enables: - xri: "kno://content/diagrams/*" reason: "Diagram instance files" - xri: "kno://content/examples/diagram-example" reason: "Example diagram entity" quality: completeness: 0.9 last_reviewed: "2026-01-14" review_status: draft reviewed_by: "claude" # ============================================================================= # HISTORY (P9 Temporal) # ============================================================================= _history: retention: full format: changelog changelog: - version: "0.0.3" date: "2026-02-26" author: "claude" summary: "Add graph view subtype and graph_config field" changes: - "Extended diagram_type enum with graph subtypes (graph, graph-concept, graph-dependency, graph-workflow, graph-ontology, graph-er)" - "Added graph_config optional field for graph-specific view configuration" - "graph_config includes scope, layout, visual_mapping, predicate_filter, and annotations" - "See docs/architecture/graph-ontology.md for design rationale" - "Graph DATA remains derived per P10 — only view config is stored" - version: "0.0.2" date: "2026-01-15" author: "claude" summary: "Add semantic elements structure per bedrock § Domain as Pivot" changes: - "Added `elements` property with nodes[], edges[], containers[]" - "Elements is the format-agnostic semantic layer (REQ-03)" - "Content fields remain for source preservation (REQ-04)" - "Updated spec description to document dual-layer architecture" - "Added thin transformation pattern documentation" - version: "0.0.1" date: "2026-01-14" author: "claude" summary: "Initial diagram domain schema" changes: - "Created fresh from first principles per bedrock" - "Removed deprecated facets field (kno-spec v0.0.6)" - "Supports multiple diagram formats (ascii, d2, mermaid)" - "Content block holds diagram source" # ============================================================================= # SPECIFICATION CONTENT # ============================================================================= spec: status: Draft description: | ## Diagram Entity Structure A Diagram entity represents a visual artifact. The schema supports multiple diagram formats while maintaining the .kno structure. ### Dual-Layer Architecture Per bedrock, diagram entities have two complementary layers: | Layer | Field | Purpose | Bedrock Principle | |-------|-------|---------|-------------------| | **Source** | `content.*` | Original format preserved | REQ-04: Source Preservation | | **Semantic** | `elements` | Format-agnostic structure | REQ-03: Enhancement Over Source | The `content` fields hold the original source (Mermaid, D2, ASCII). The `elements` field holds the parsed semantic structure that ALL formats map to — enabling queries, validation, and format-to-format transformation. ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ DIAGRAM ENTITY STRUCTURE │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ diagram-example.kno │ │ ├── $schema: kno@0.0.9 │ │ ├── id: diagram-example │ │ ├── type: diagram │ │ ├── format: ascii | d2 | mermaid │ │ ├── content: ← SOURCE LAYER (REQ-04) │ │ │ ├── description: "What this shows" │ │ │ ├── ascii: | (DC-3 compliant) │ │ │ │ ┌─────────┐ │ │ │ │ │ Box │ │ │ │ │ └─────────┘ │ │ │ └── mermaid: | (original source) │ │ │ flowchart TB │ │ │ A["Box"] │ │ ├── elements: ← SEMANTIC LAYER (REQ-03) │ │ │ ├── direction: TB │ │ │ ├── nodes: [{id: A, label: Box}] │ │ │ ├── edges: [] │ │ │ └── containers: [] │ │ └── metadata: │ │ └── created_at, updated_at │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ### Thin Transformation Pattern Per bedrock § Domain as Pivot, format conversion flows through `elements`: ``` Mermaid ──parse──▶ elements ──render──▶ D2 └── content.mermaid └── styled via template ``` This enables: - **Queries:** "find all diagrams with >5 nodes" - **Validation:** "no orphan nodes", "max 50 elements" - **Transformation:** parse(any format) → elements → render(any format) ## Format Types | Format | Field | Purpose | |--------|---------------|---------| | ascii | .kno | Human-readable, text-editor accessible (DC-3) | | d2 | .d2 | Modern diagram scripting, renders to SVG | | mermaid | .md | Markdown-friendly, GitHub renders | ## Why ASCII First? ASCII diagrams satisfy **DC-3 (Text-Editor Accessible)**: - Viewable with any text editor - Git-friendly diffs - Works in terminals, chat, email - No rendering required for comprehension schema: type: object required: - id - type - version - title - content properties: # ----------------------------------------------------------------------- # BASIC TIER (required) # ----------------------------------------------------------------------- $schema: type: string description: "KNO schema version" const: "kno@0.0.9" id: type: string description: "Unique identifier" pattern: "^[a-zA-Z0-9_-]+$" examples: - "kaml-layering-diagram" - "entity-lifecycle" type: type: string description: "Entity type" const: "diagram" version: type: string description: "Semantic version of this entity instance" pattern: "^\\d+\\.\\d+\\.\\d+$" examples: - "1.0.0" # ----------------------------------------------------------------------- # STANDARD TIER (recommended) # ----------------------------------------------------------------------- title: type: string description: "Human-readable title" examples: - "The .kno Format Stack" - "Entity Lifecycle Diagram" conforms_to: type: string description: "Schema this entity conforms to" const: "diagram-schema" # ----------------------------------------------------------------------- # DIAGRAM-SPECIFIC FIELDS # ----------------------------------------------------------------------- format: type: string description: "Primary diagram format" enum: - ascii - d2 - mermaid - plantuml - graphviz default: ascii examples: - "ascii" - "d2" diagram_type: type: string description: "Semantic type of diagram" enum: - architecture - flowchart - sequence - entity-relationship - class - state - layered - grid - general # Graph subtypes (v0.0.3) — see docs/architecture/graph-ontology.md - graph # General knowledge/concept graph - graph-concept # Concept graph (entries within a container) - graph-dependency # Dependency graph (depends_on edges emphasized) - graph-workflow # Workflow graph (sequential flow between entries) - graph-ontology # Schema-level type hierarchy - graph-er # Entity-relationship diagram (graph form) default: general examples: - "layered" - "flowchart" - "graph-concept" # ----------------------------------------------------------------------- # CONTENT (diagram source — REQ-04: Source Preservation) # ----------------------------------------------------------------------- content: type: object description: | Diagram content in one or more source formats. Per REQ-04, the original source is embedded here for provenance. properties: description: type: string description: "What this diagram illustrates" ascii: type: string description: "ASCII art representation (Unicode box-drawing)" d2: type: string description: "D2 diagram source" mermaid: type: string description: "Mermaid diagram source" svg: type: string description: "Rendered SVG (optional, generated)" # ----------------------------------------------------------------------- # ELEMENTS (semantic structure — REQ-03: Enhancement Over Source) # ----------------------------------------------------------------------- # Per bedrock § Domain as Pivot: This is the format-agnostic semantic # structure that both Mermaid and D2 map to. Enables: # - Querying: "find diagrams with >5 nodes" # - Validation: "no orphan nodes" # - Transformation: parse(format) → elements → render(format) # ----------------------------------------------------------------------- elements: type: object description: | Semantic structure of diagram (format-agnostic). This is the domain representation that format parsers produce and format renderers consume. See bedrock § Domain as Pivot. properties: direction: type: string description: "Layout direction for the diagram" enum: - TB - BT - LR - RL default: TB examples: - "TB" - "LR" nodes: type: array description: "Individual diagram elements (boxes, shapes)" items: type: object required: - id properties: id: type: string description: "Unique node identifier within the diagram" label: type: string description: "Display label (may include line breaks via \\n)" container: type: string description: "Parent container id (if nested)" style: type: object description: "Visual styling (resolved from template at render time)" properties: fill: type: string description: "Background color" stroke: type: string description: "Border color" font_color: type: string description: "Text color" edges: type: array description: "Connections between nodes" items: type: object required: - source - target properties: source: type: string description: "Source node id" target: type: string description: "Target node id" label: type: string description: "Edge label (optional)" style: type: object description: "Visual styling" properties: stroke: type: string description: "Line color" containers: type: array description: "Grouping structures (subgraphs, clusters)" items: type: object required: - id properties: id: type: string description: "Unique container identifier" label: type: string description: "Container title/header" parent: type: string description: "Parent container id (for nesting)" grid_columns: type: integer description: "Grid layout columns (D2-specific)" default: 1 grid_gap: type: integer description: "Grid gap in pixels (D2-specific)" default: 0 style: type: object description: "Visual styling" properties: fill: type: string stroke: type: string font_color: type: string bold: type: boolean # ----------------------------------------------------------------------- # GRAPH VIEW CONFIGURATION (v0.0.3) # ----------------------------------------------------------------------- # Optional configuration for diagram_type: graph-* # Graph DATA (nodes, edges) is always DERIVED from entity relationships # per P10 (Derivable Structure). This field configures HOW to render # the derived graph — scope, layout, visual mappings, filters. # See: docs/architecture/graph-ontology.md # ----------------------------------------------------------------------- graph_config: type: object description: | Configuration for graph-type diagrams. Controls how the derived graph is scoped, laid out, and rendered. The graph data itself (nodes + edges) is always computed from entity relationships at render time — never stored — per P10 (Derivable Structure). properties: scope: type: object description: "Which entities to include in the graph" properties: source_xri: type: string description: "XRI of the container whose entries form the graph" examples: - "pspace://playbook:awecelot" - "pspace://playbook:howl" entry_filter: type: object description: "Optional filters to restrict which entries appear as nodes" properties: types: type: array items: type: string description: "Include only these entry types" examples: - ["principle", "pattern", "procedure"] domains: type: array items: type: string description: "Include only entries matching these domain patterns" examples: - ["methodology.*", "technical.architecture"] min_relationships: type: integer description: "Minimum relationship count to include (filters orphans)" default: 0 layout: type: object description: "Graph layout algorithm and parameters" properties: algorithm: type: string description: "Layout algorithm" enum: - radial # Domain-grouped radial (current default) - force # Force-directed (spring physics) - hierarchical # Top-down or left-right hierarchy - dagre # Directed acyclic graph layout - circular # Circular arrangement default: radial group_by: type: string description: "Property to group nodes by (affects spatial clustering)" enum: - domain - type - priority - none default: domain parameters: type: object description: "Algorithm-specific parameters" properties: outer_radius: type: number description: "Outer radius for radial layout" inner_radius: type: number description: "Inner radius for radial layout" center: type: array items: type: number description: "Center point [x, y] for radial/circular layouts" spacing: type: number description: "Node spacing for force/hierarchical layouts" iterations: type: integer description: "Iteration count for force-directed layout" visual_mapping: type: object description: "Maps entity properties to visual channels" properties: node_color: type: string description: "Property that determines node color" enum: - type - domain - priority - custom default: type node_size: type: string description: "Property or metric that determines node size" enum: - uniform - centrality - relationship_count - custom default: uniform edge_color: type: string description: "Property that determines edge color" enum: - predicate - custom default: predicate edge_width: type: string description: "Property that determines edge width" enum: - uniform - weight - custom default: uniform predicate_filter: type: object description: "Which relationship predicates to display as edges" properties: include: type: array items: type: string description: | Only show these predicates. If omitted, all predicates shown. Uses P7 vocabulary: depends_on, extends, enables, supports, contradicts, exemplifies, exemplified_by, implements, supersedes, specializes, related. examples: - ["enables", "depends_on", "extends", "contradicts"] exclude: type: array items: type: string description: "Hide these predicates (applied after include)" examples: - ["related"] annotations: type: object description: "Visual overlays and callouts" properties: highlight_nodes: type: array items: type: string description: "Entry IDs to visually emphasize" cluster_labels: type: boolean description: "Show labels for node clusters (e.g., domain names)" default: true show_orphans: type: boolean description: "Include nodes with zero relationships" default: true show_legend: type: boolean description: "Display color/shape legend" default: true # ----------------------------------------------------------------------- # METADATA # ----------------------------------------------------------------------- metadata: type: object properties: created_at: type: string format: date-time updated_at: type: string format: date-time author: type: string