{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/welkaim/ea-codex/schemas/v1/architecture-principle.json",
  "title": "ArchitecturePrinciple",
  "description": "Stable architectural anchor that downstream standards, decisions, and fitness functions reference. Introduced in Chapter 14. Principles are deliberately stable: when a vendor policy or regulation is updated, the principle text typically does not change while the standard catalogue and the fitness-function allowed values are touched. A principle whose statement fits in two sentences and whose validation criteria fit in a single row is a principle a fitness function can enforce.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata", "spec"],
  "properties": {
    "apiVersion": { "$ref": "_common.json#/$defs/apiVersion" },
    "kind": { "type": "string", "const": "ArchitecturePrinciple" },
    "metadata": {
      "type": "object",
      "required": ["id", "name", "status"],
      "properties": {
        "id": { "$ref": "_common.json#/$defs/identifier" },
        "name": {
          "type": "string",
          "description": "Short human-readable name for the principle. May contain spaces and dashes."
        },
        "title": { "type": "string" },
        "status": { "$ref": "_common.json#/$defs/lifecycleStatus" },
        "version": { "$ref": "_common.json#/$defs/version" },
        "domain": {
          "type": "string",
          "description": "Architectural domain governing the principle. Examples: integration, data, ai, security, sovereignty. The domain typically matches the identifier prefix."
        },
        "applicability": {
          "type": "string",
          "description": "Scope of artifacts to which the principle applies, expressed as a short noun phrase."
        },
        "owners": { "$ref": "_common.json#/$defs/owners" }
      },
      "additionalProperties": true
    },
    "spec": {
      "type": "object",
      "required": ["statement", "rationale"],
      "properties": {
        "statement": {
          "type": "string",
          "minLength": 20,
          "description": "The principle itself, normative, ideally one or two sentences."
        },
        "rationale": {
          "type": "string",
          "minLength": 20,
          "description": "Why the principle exists. Names the risks it eliminates and the strategic position it locks in."
        },
        "validationCriteria": {
          "type": "array",
          "minItems": 1,
          "description": "How the principle is checked. Each criterion names a checkable condition and the mechanism that enforces it.",
          "items": {
            "type": "object",
            "required": ["criterion", "checkMethod"],
            "properties": {
              "criterion": {
                "type": "string",
                "description": "The checkable condition, expressed as an attribute predicate over fact sheets, specs, or running artifacts."
              },
              "checkMethod": {
                "type": "string",
                "description": "How the criterion is evaluated. Names the fitness function, the Rego package, or the scheduled scan."
              },
              "requiredValue": {
                "type": "string",
                "description": "Allowed values or expected outcome of the check, when applicable."
              }
            },
            "additionalProperties": true
          }
        },
        "eaToolMapping": {
          "type": "object",
          "description": "Mapping to the EA tool's fact-sheet model so the principle can be evaluated automatically. Equivalent fields apply to other EA platforms (Ardoq, ServiceNow); the eaToolMapping field is the EA-tool-agnostic binding.",
          "properties": {
            "factSheet": {
              "type": "string",
              "description": "Fact-sheet type the principle applies to (Application, Interface, AgentContract, DataObject, etc.)."
            },
            "field": {
              "type": "string",
              "description": "Attribute path on the fact sheet that the principle predicates on."
            },
            "autoCheck": {
              "type": "string",
              "description": "Description of the automated check that surfaces violations."
            }
          },
          "additionalProperties": true
        },
        "exceptions": {
          "type": "string",
          "description": "Conditions under which exceptions may be granted. Should reference a DecisionRecord with a sunset date and a named risk owner."
        },
        "relatedPrinciples": {
          "type": "array",
          "description": "Other principles in the same family or that this principle composes with.",
          "items": { "$ref": "_common.json#/$defs/identifier" }
        },
        "relatedStandards": {
          "type": "array",
          "description": "TechnologyStandard catalogues that realize this principle.",
          "items": { "$ref": "_common.json#/$defs/identifier" }
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}