{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://clearhead.dev/schemas/v0.7.0/actions.schema.json",
  "title": "Actions File Serialization Format",
  "description": "JSON Schema for the canonical serialization of .actions files. ontology.md's action terms map each field to its DSL token and its application-graph terms.",
  "type": "object",
  "required": [
    "actions"
  ],
  "properties": {
    "actions": {
      "type": "array",
      "description": "Array of root-level actions",
      "items": {
        "$ref": "#/definitions/action"
      }
    }
  },
  "definitions": {
    "action": {
      "type": "object",
      "required": [
        "state",
        "name"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "'#' in the DSL. UUIDv7 preferred.",
          "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": "Current lifecycle state.",
          "enum": [
            "not_started",
            "completed",
            "in_progress",
            "blocked",
            "cancelled"
          ]
        },
        "name": {
          "type": "string",
          "description": "The decoded semantic title, after DSL escapes are removed.",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "description": "Decoded long-form description — '$ ... $' in the DSL."
        },
        "priority": {
          "type": "integer",
          "description": "'!' in the DSL. RFC 5545-aligned, 1 (highest) to 9 (lowest).",
          "minimum": 1,
          "maximum": 9
        },
        "contexts": {
          "type": "array",
          "description": "'+' in the DSL.",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "minItems": 1
        },
        "scheduledDateTime": {
          "type": "string",
          "description": "'@' in the DSL. When the Action is planned to be worked: an ISO 8601 local date/time (the planned start), or an ISO 8601 interval `start/end` (a planned block, its end exclusive). Duration is the block's length and is not serialized. Intent only: it bounds nothing and is not inherited (Decisions 48 and 51)."
        },
        "recurrenceRule": {
          "type": "string",
          "minLength": 1,
          "description": "R: RFC 5545 RRULE text, only valid on roots in .habits.actions. Ordinary Action use is a semantic lint."
        },
        "dueDateTime": {
          "type": "string",
          "description": "':' in the DSL. The Action's window: an ISO 8601 local date/time (a deadline), or an ISO 8601 interval `start/end` (a lower bound and a deadline). A date covers its day; a time is an instant. Effective bounds inherited from ancestors are derived and are not serialized here."
        },
        "completedDateTime": {
          "type": "string",
          "description": "'%' in the DSL. ISO 8601 completion time."
        },
        "createdDateTime": {
          "type": "string",
          "description": "'^' in the DSL. ISO 8601 creation time."
        },
        "charter": {
          "type": "string",
          "description": "Decoded charter membership hint — '*' in the DSL.",
          "minLength": 1
        },
        "alias": {
          "type": "string",
          "description": "A short human handle.",
          "minLength": 1
        },
        "sequentialChildren": {
          "type": "boolean",
          "description": "'~' in the DSL. When true, each child implicitly depends on the previous sibling completing."
        },
        "predecessors": {
          "type": "array",
          "description": "Dependency references — '<' in the DSL. A canonical UUID or unresolved alias is preserved as semantic reference text.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "externalScheduleId": {
          "type": "string",
          "description": "External transport schedule-series identifier (e.g. an ICS UID), not native Habit identity. Native occurrence lineage is recorded in sidecar occurrence.habit_id."
        },
        "externalOccurrenceKey": {
          "type": "string",
          "description": "External transport occurrence-level identifier within a series, not the canonical native slot. The native slot is recorded in sidecar occurrence.occurrence_key."
        },
        "parentId": {
          "type": "string",
          "description": "UUID of the parent action ('>' nesting in the DSL).",
          "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}$"
        },
        "children": {
          "type": "array",
          "description": "Nested child actions ('>' depth in the DSL).",
          "items": {
            "$ref": "#/definitions/action"
          }
        }
      },
      "additionalProperties": false
    }
  }
}
