{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://clearhead.dev/schemas/v0.7.0/charters.schema.json",
  "title": "Charters Serialization Format",
  "description": "JSON Schema for the canonical serialization of charter documents (see charters.md). Describes charter facts only: Actions and Plans have their own projections and join back through their charter reference, so they are never embedded here. Field names follow the charter frontmatter; each description names the v4 actions ontology property it projects.",
  "type": "object",
  "required": [
    "charters"
  ],
  "properties": {
    "charters": {
      "type": "array",
      "description": "Flat array of charters. Hierarchy is carried by each charter's parent reference, not by nesting.",
      "items": {
        "$ref": "#/definitions/charter"
      }
    }
  },
  "definitions": {
    "charter": {
      "type": "object",
      "required": [
        "state",
        "title"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Frontmatter `id`. UUIDv7 preferred. Omitted when the document declares none: an ephemeral identity is never serialized (see Concept Identity in workspace.md).",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        },
        "state": {
          "type": "string",
          "description": "hasCharterState — frontmatter `state`. Locally asserted lifecycle state; an omitted source state projects as `new`. Inherited engagement eligibility is derived and not serialized here.",
          "enum": [
            "new",
            "active",
            "blocked",
            "closed",
            "cancelled"
          ]
        },
        "title": {
          "type": "string",
          "description": "rdfs:label — frontmatter `title`, or the document's first heading.",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "description": "Content under the title heading, including its subsections."
        },
        "alias": {
          "type": "string",
          "description": "hasAlias — a short human handle, scoped within the parent charter.",
          "minLength": 1
        },
        "parent": {
          "type": "string",
          "description": "Inverse of hasSubCharter — reference (alias or UUID, never title) to the parent charter, whether declared in frontmatter or derived from directory placement. Absent for a root charter.",
          "minLength": 1
        },
        "objectives": {
          "type": "array",
          "description": "inServiceOf — frontmatter `objectives`: references to the Objectives this charter serves.",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "minItems": 1
        },
        "defaults": {
          "type": "object",
          "description": "Frontmatter `defaults`: key-value settings applied to descendants. Keys are not yet specified.",
          "additionalProperties": true
        },
        "log": {
          "type": "array",
          "description": "Entries of the `Log` section, in document order (which is time order: entries are appended).",
          "items": {
            "$ref": "#/definitions/logEntry"
          }
        },
        "sections": {
          "type": "array",
          "description": "Sibling sections after the core section (excluding `Log`), in document order.",
          "items": {
            "$ref": "#/definitions/section"
          }
        }
      },
      "additionalProperties": false
    },
    "section": {
      "type": "object",
      "required": [
        "heading"
      ],
      "properties": {
        "heading": {
          "type": "string",
          "description": "Heading text without the leading `#` markers.",
          "minLength": 1
        },
        "body": {
          "type": "string",
          "description": "Content under the heading, including its subsections."
        }
      },
      "additionalProperties": false
    },
    "logEntry": {
      "type": "object",
      "required": [
        "text"
      ],
      "properties": {
        "at": {
          "type": "string",
          "description": "The entry's leading ISO 8601 date or date-time. Omitted for an undated entry; never filled in after the fact.",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?(Z|[+-]\\d{2}:\\d{2})?)?$"
        },
        "text": {
          "type": "string",
          "description": "Entry text after the date and separator.",
          "minLength": 1
        }
      },
      "additionalProperties": false
    }
  }
}
