# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
structure:
  - heading:
      expr: "filename == heading"
    children:
      - heading: "## Description"
      - heading: "## Domain Model Definitions"
        children:
          - heading: "### Model type"
            description: |
              Model type must be one of Standard, AppendOnly, or Stateful
               - AppendOnly: AppendOnly model where records can be added but not modified or deleted
               - Stateful: Stateful model with state transitions
            required_text:
              - pattern: "(Standard|AppendOnly|Stateful)"
                regex: true
            children:
              - heading: "#### State Transitions"
                description: |
                  Define the state transitions for Stateful models.
                  Mermaid stateDiagram-v2 of the model's lifecycle.
                  Label each arrow with the command name from "### Command Definitions".
                  Use [*] for entry and exit points.
                  Optionally include a Transitions table (one row per operation).
                  The Command column must be a relative markdown link to the command doc (e.g. [activateProduct](../command/ActivateProduct.md)).
                  Multiple source states are comma-separated in From (e.g. "DRAFT, SUBMITTED").
                optional: true
                code_blocks:
                  - lang: mermaid
                    min: 1
                tables:
                  - min: 0
                    required_headers:
                      - Operation
                      - From
                      - To
                      - Command

          - heading: "### Command Definitions"
            description: |
              Definitions of commands this domain model supports.
              Should match with the commands defined in modules/**/docs/command/*.md and link to them.
              Commands heavily influenced by Model type:
                - Standard: Create, Update, Delete (Some model may choose to not implement Delete)
                - AppendOnly: Create
                - Stateful: Create, State Transition Commands
            lists:
              - min: 0
                type: unordered
                min_items: 0

          - heading: "### Query Definitions"
            description: |
              Definitions of queries this domain model supports.
              Should match with the queries defined in modules/**/docs/query/*.md and link to them.
              For Stateful models or models with isActive, follow the status-aware naming convention:
                - get{Entity}: single lookup, returns any status
                - list{Status}{Entities}: business use case with status baked into the name (e.g., listActiveItems)
                - list{Entities}: unfiltered, returns all statuses
                - search{Entities}: admin/exploratory with parametric status filter
            lists:
              - min: 0
                type: unordered
                min_items: 0

          - heading: "### Models"
            description: |
              Actual database models necessary for the domain model.
            lists:
              - min: 1
                type: unordered
                min_items: 1

          - heading: "### Invariants"
            description: |
              Invariants that must always hold true for this domain model.
              - Assume the model boundary (the unit within which consistency is guaranteed) is already defined, and list what must always be true within that boundary.
              - Express each invariant as part of the concept's definition (what makes the concept valid), not as an implementation detail (no DB constraints, computed columns, etc.).
              - If a constraint depends on lifecycle state, write it explicitly as a state-scoped invariant (state x condition that must always hold).

            lists:
              - min: 0
                type: unordered
                min_items: 0

          - heading: "### Relationships"

# Global link validation settings
links:
  validate_internal: true # check anchor links (#section-name)
  validate_files: true # check relative file links (./other.md)
# Global heading validation rules
heading_rules:
  no_skip_levels: true # disallow skipping levels (e.g., h1 -> h3)
  unique: true # all headings must be unique
  max_depth: 4 # maximum heading depth (1-6)