{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/agile-north/rexo/schema/v1.0/policy.schema.json",
  "title": "Rexo policy configuration schema",
  "description": "Schema for policy files that provide shared command and alias baselines.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "$schema",
    "schemaVersion",
    "name",
    "commands",
    "aliases"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Schema URI/path used by editors and validators for policy files.",
      "enum": [
        "https://raw.githubusercontent.com/agile-north/rexo/schema/v1.0/policy.schema.json",
        "https://raw.githubusercontent.com/agile-north/rexo/release/next/policy.schema.json",
        "https://raw.githubusercontent.com/agile-north/rexo/schema/v1.0/policy.schema.json",
        "policy.schema.json",
        "./policy.schema.json",
        "../policy.schema.json",
        ".rexo/policy.schema.json"
      ]
    },
    "schemaVersion": {
      "type": "string",
      "description": "Policy schema contract version. Currently only 1.0 is supported.",
      "const": "1.0"
    },
    "name": {
      "type": "string",
      "description": "Human-friendly policy name shown in diagnostics/output.",
      "minLength": 1
    },
    "description": {
      "type": "string",
      "description": "Optional longer description of what the policy provides."
    },
    "commands": {
      "type": "object",
      "minProperties": 1,
      "description": "Policy-defined commands merged into repository command space.",
      "additionalProperties": {
        "$ref": "#/$defs/repoCommand"
      }
    },
    "aliases": {
      "type": "object",
      "description": "Policy-defined command aliases. Key is alias name, value is command target.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "capabilities": {
      "description": "Runtime capability requirements and compatibility contract expectations for this policy.",
      "$ref": "#/$defs/capabilityContract"
    }
  },
  "$defs": {
    "capabilityContract": {
      "type": "object",
      "additionalProperties": false,
      "description": "Declares compatibility against runtime capability contract and required features.",
      "properties": {
        "contractVersion": {
          "type": "string",
          "description": "Capability contract version expected by this policy. Current runtime contract is 1.0."
        },
        "required": {
          "type": "array",
          "description": "Capabilities that must be supported by the active runtime.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    },
    "repoCommand": {
      "type": "object",
      "description": "Command definition contributed by a policy.",
      "additionalProperties": false,
      "required": [
        "steps"
      ],
      "properties": {
        "description": {
          "type": "string",
          "description": "Human-readable command summary shown in help/list output."
        },
        "args": {
          "type": "object",
          "description": "Positional argument declarations keyed by argument name.",
          "additionalProperties": {
            "$ref": "#/$defs/argConfig"
          }
        },
        "options": {
          "type": "object",
          "description": "Named option declarations keyed by option name.",
          "additionalProperties": {
            "$ref": "#/$defs/optionConfig"
          }
        },
        "steps": {
          "type": "array",
          "description": "Ordered execution steps for this command.",
          "items": {
            "$ref": "#/$defs/step"
          }
        },
        "merge": {
          "description": "Layered command composition behavior. Accepts legacy string mode or merge envelope object.",
          "$ref": "#/$defs/commandMerge"
        },
        "stepOps": {
          "description": "Legacy explicit step-level extension operations. Prefer merge.steps envelope.",
          "$ref": "#/$defs/commandStepOps"
        }
      }
    },
    "commandMerge": {
      "description": "Command merge configuration. Can be a legacy scalar mode or envelope object.",
      "oneOf": [
        {
          "$ref": "#/$defs/commandMergeMode"
        },
        {
          "$ref": "#/$defs/commandMergeEnvelope"
        }
      ]
    },
    "commandMergeMode": {
      "type": "string",
      "description": "Layered command composition mode for this command.",
      "enum": [
        "layer",
        "replace",
        "append",
        "prepend",
        "wrap"
      ]
    },
    "commandMergeEnvelope": {
      "type": "object",
      "additionalProperties": false,
      "description": "Unified merge envelope containing mode and optional step operations.",
      "properties": {
        "mode": {
          "$ref": "#/$defs/commandMergeMode"
        },
        "steps": {
          "$ref": "#/$defs/commandStepOps"
        }
      }
    },
    "commandStepOps": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "remove": {
          "type": "array",
          "description": "Step ids to remove from the inherited command pipeline.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "replace": {
          "type": "array",
          "description": "Step replacements by id.",
          "items": {
            "$ref": "#/$defs/stepReplace"
          }
        },
        "prepend": {
          "type": "array",
          "description": "Steps inserted before the inherited pipeline.",
          "items": {
            "$ref": "#/$defs/step"
          }
        },
        "append": {
          "type": "array",
          "description": "Steps added after the inherited pipeline.",
          "items": {
            "$ref": "#/$defs/step"
          }
        }
      }
    },
    "stepReplace": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "step"],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Target step id to replace."
        },
        "step": {
          "$ref": "#/$defs/step"
        }
      }
    },
    "argConfig": {
      "type": "object",
      "description": "Configuration for a positional command argument.",
      "additionalProperties": false,
      "required": [
        "required"
      ],
      "properties": {
        "required": {
          "type": "boolean",
          "description": "Whether this positional argument must be provided by the user."
        },
        "description": {
          "type": "string",
          "description": "Help text shown for the argument."
        }
      }
    },
    "optionConfig": {
      "type": "object",
      "description": "Configuration for a named command option.",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Option value type identifier.",
          "enum": [
            "string",
            "bool",
            "boolean",
            "int",
            "integer",
            "number"
          ],
          "default": "string"
        },
        "default": {
          "type": [
            "string",
            "boolean",
            "number",
            "integer"
          ],
          "description": "Default value applied when the option is omitted."
        },
        "allowed": {
          "type": "array",
          "description": "Optional allowed values list enforced at runtime.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "step": {
      "type": "object",
      "description": "Single executable unit in a command pipeline. Exactly one of run, uses, or command must be set.",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable step identifier for logging and dependency wiring."
        },
        "command": {
          "type": "string",
          "description": "Invokes another configured command by name."
        },
        "uses": {
          "type": "string",
          "description": "Invokes a built-in primitive (for example builtin:push-artifacts)."
        },
        "run": {
          "type": "string",
          "description": "Shell command text to execute.",
          "examples": [
            "dotnet format --verify-no-changes",
            "npm test"
          ]
        },
        "when": {
          "type": "string",
          "description": "Conditional expression that controls whether the step executes."
        },
        "with": {
          "type": "object",
          "description": "String key/value inputs passed to the selected built-in or command.",
          "examples": [
            {
              "confirm": "{{options.push}}"
            },
            {
              "push": "{{options.push}}",
              "stage": "{{args.stage | default(publish)}}"
            }
          ],
          "additionalProperties": {
            "type": "string"
          }
        },
        "description": {
          "type": "string",
          "description": "Optional step summary shown in plan/log output."
        },
        "whenExists": {
          "type": "boolean",
          "description": "Only for command steps. When true, missing target commands are skipped successfully instead of failing."
        },
        "continueOnError": {
          "type": "boolean",
          "description": "Continue executing later steps when this step fails."
        },
        "dependsOn": {
          "type": "array",
          "description": "List of step ids that must complete before this step can run.",
          "items": {
            "type": "string"
          }
        }
      },
      "anyOf": [
        { "required": ["run"] },
        { "required": ["uses"] },
        { "required": ["command"] }
      ]
    }
  }
}