c4-annotations-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "C4 Literate Python Annotation Schema",
  "version": "0.9.0",
  "description": "Schema for C4 model annotations embedded in Python docstrings and comments",
  
  "definitions": {
    "placement": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["module", "class", "function", "inline"]
      }
    },
    
    "annotation": {
      "type": "object",
      "required": ["name", "placement", "description"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Annotation name (e.g., @c4-container)"
        },
        "placement": {
          "$ref": "#/definitions/placement",
          "description": "Where this annotation can be placed in code"
        },
        "required_attributes": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Attributes that must accompany this annotation"
        },
        "optional_attributes": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Optional attributes for this annotation"
        },
        "format": {
          "type": "string",
          "description": "Expected format of the annotation value"
        },
        "description": {
          "type": "string",
          "description": "What this annotation declares or describes"
        },
        "examples": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Example usage of this annotation"
        }
      }
    }
  },
  
  "annotations": {
    "@c4-container": {
      "name": "@c4-container",
      "placement": ["module"],
      "required_attributes": ["@c4-technology", "@c4-description"],
      "optional_attributes": ["@c4-responsibilities"],
      "format": "Name of the container",
      "description": "Declares that this module represents a C4 container (deployable unit like a web application, database, mobile app, etc.)",
      "examples": [
        "@c4-container: API Application",
        "@c4-container: Database Layer",
        "@c4-container: Message Queue"
      ],
      "notes": "Containers are the high-level building blocks of your system. Each container is separately deployable and typically runs in its own process space."
    },
    
    "@c4-component": {
      "name": "@c4-component",
      "placement": ["module", "class"],
      "required_attributes": ["@c4-technology"],
      "optional_attributes": ["@c4-description"],
      "format": "Name of the component",
      "description": "Declares that this module or class represents a C4 component (a grouping of related functionality within a container)",
      "examples": [
        "@c4-component: Data Validation Layer",
        "@c4-component: API Request Handler",
        "@c4-component: Authentication Service"
      ],
      "notes": "Components are the major structural elements within a container. They represent groupings of related functionality."
    },
    
    "@c4-technology": {
      "name": "@c4-technology",
      "placement": ["module", "class", "function"],
      "format": "Technology stack description",
      "description": "Describes the technology or tech stack used to implement this element",
      "examples": [
        "@c4-technology: Python 3.12, FastAPI 0.104",
        "@c4-technology: SQLAlchemy 2.0, SQLite 3",
        "@c4-technology: Pydantic 2.0"
      ],
      "notes": "Be specific about versions when relevant for documentation purposes."
    },
    
    "@c4-description": {
      "name": "@c4-description",
      "placement": ["module", "class", "function"],
      "format": "Brief description (1-2 sentences recommended)",
      "description": "Provides a brief description of what this element does or represents",
      "examples": [
        "@c4-description: REST API providing CRUD operations for notes",
        "@c4-description: Validates and serializes request/response data"
      ],
      "notes": "Keep descriptions concise and focused on the primary responsibility. Detailed explanations belong in the surrounding prose documentation."
    },
    
    "@c4-responsibilities": {
      "name": "@c4-responsibilities",
      "placement": ["module", "class"],
      "format": "Bullet list of responsibilities (one per line, indented)",
      "description": "Lists the key responsibilities of this element",
      "examples": [
        "@c4-responsibilities:\n    - Accept and validate HTTP requests\n    - Route requests to handlers\n    - Transform responses to JSON"
      ],
      "notes": "Each responsibility should be a brief action phrase. Typically 3-7 items."
    },
    
    "@c4-uses": {
      "name": "@c4-uses",
      "placement": ["module", "class"],
      "format": "Target - \"Description\" - \"Technology\"",
      "description": "Declares that this element depends on or uses another container or component",
      "examples": [
        "@c4-uses: Database Layer (app.database) - \"Manages note persistence\" - \"SQLAlchemy ORM\"",
        "@c4-uses: Data Models (app.models) - \"Validates requests\" - \"Pydantic\""
      ],
      "notes": "The three parts are: (1) Target name with optional module path in parens, (2) Action description in quotes, (3) Technology/protocol in quotes."
    },
    
    "@c4-used-by": {
      "name": "@c4-used-by",
      "placement": ["module", "class"],
      "format": "Source - \"Description\" - \"Technology\"",
      "description": "Declares that this element is used by another container or component (inverse of @c4-uses)",
      "examples": [
        "@c4-used-by: API Application (app.main) - \"Requests database sessions\" - \"SQLAlchemy ORM\""
      ],
      "notes": "Use this for documenting reverse dependencies when the relationship is important to understand from this element's perspective."
    },
    
    "@c4-used-by-person": {
      "name": "@c4-used-by-person",
      "placement": ["module", "class"],
      "format": "Person name - \"Description\" - \"Technology/Protocol\"",
      "description": "Declares that this element is used by an external actor (person or external system acting as a user)",
      "examples": [
        "@c4-used-by-person: API Consumer - \"Creates and manages notes\" - \"HTTPS/JSON\"",
        "@c4-used-by-person: System Administrator - \"Monitors health\" - \"HTTPS\""
      ],
      "notes": "Persons represent human actors or external systems that interact with your system from the outside."
    },
    
    "@c4-operation": {
      "name": "@c4-operation",
      "placement": ["function"],
      "format": "Operation name (typically function name)",
      "description": "Declares that this function represents a significant operation within a component",
      "examples": [
        "@c4-operation: create_note",
        "@c4-operation: authenticate_user"
      ],
      "notes": "Operations are the finest level of detail, showing key functions within components. Only annotate significant operations, not every function."
    },
    
    "@c4-calls": {
      "name": "@c4-calls",
      "placement": ["function"],
      "format": "Target - \"Description\"",
      "description": "Declares that this operation calls another component or container",
      "examples": [
        "@c4-calls: Database Layer - \"Persists new note\"",
        "@c4-calls: Authentication Service - \"Validates token\""
      ],
      "notes": "Use this to show data flow and interactions at the operation level. Two-part format: Target and action description."
    },
    
    "@c4-relationship": {
      "name": "@c4-relationship",
      "placement": ["module", "class", "function"],
      "format": "Generic relationship declaration",
      "description": "Generic relationship annotation for advanced use cases not covered by @c4-uses/@c4-calls",
      "examples": [
        "@c4-relationship: Initializes Database Container on startup"
      ],
      "notes": "Use specific annotations (@c4-uses, @c4-calls) when possible. This is for special cases."
    }
  },
  
  "validation_rules": {
    "container_requirements": {
      "description": "A module with @c4-container must have @c4-technology and @c4-description",
      "required": ["@c4-technology", "@c4-description"]
    },
    "component_requirements": {
      "description": "A module or class with @c4-component must have @c4-technology",
      "required": ["@c4-technology"]
    },
    "relationship_format": {
      "description": "Relationship annotations must follow the specified format with proper quoting",
      "pattern": "^.+ - \".+\" - \".+\"$"
    }
  },
  
  "best_practices": {
    "placement": "Place container declarations at module level, component declarations at module or class level, operation declarations at function level",
    "naming": "Use clear, consistent names that match your architecture documentation",
    "descriptions": "Keep descriptions concise (1-2 sentences). Use surrounding prose for detailed explanations",
    "relationships": "Document relationships from the perspective of the element being annotated",
    "consistency": "Use consistent terminology across all annotations in your codebase"
  },
  
  "future_extensions": {
    "planned": [
      "@c4-software-system: For declaring system context",
      "@c4-person: For declaring external actors",
      "@c4-database: For declaring data stores",
      "@c4-external-system: For declaring external dependencies",
      "@c4-deployment-node: For deployment context",
      "@c4-security-zone: For security boundaries"
    ]
  }
}