{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/welkaim/ea-codex/schemas/v1/business-object.json",
  "title": "BusinessObject",
  "description": "Typed enterprise data object: the canonical definition of what a piece of business data means, who governs it, and which semantic rules any instance must satisfy. BusinessObject sits one level above DataProductContract: where the contract scopes a federated unit of access for one purpose, the object defines the canonical concept and its semantic rules. Semantic rules (identity, lifecycle, cross-attribute, classification-derivation) are the operative content of the kind; they are evaluated by fitness functions and Rego packages, and they apply regardless of which contract exposes the object.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata", "spec"],
  "properties": {
    "apiVersion": { "$ref": "_common.json#/$defs/apiVersion" },
    "kind": { "type": "string", "const": "BusinessObject" },
    "metadata": {
      "type": "object",
      "required": ["id", "name", "title", "status", "version"],
      "properties": {
        "id": { "$ref": "_common.json#/$defs/identifier" },
        "name": { "$ref": "_common.json#/$defs/slug" },
        "title": {
          "type": "string",
          "minLength": 3
        },
        "status": { "$ref": "_common.json#/$defs/lifecycleStatus" },
        "version": { "$ref": "_common.json#/$defs/version" },
        "owners": { "$ref": "_common.json#/$defs/owners" }
      },
      "additionalProperties": true
    },
    "spec": {
      "type": "object",
      "required": ["statement", "domain", "classification", "semanticRules"],
      "properties": {
        "statement": {
          "type": "string",
          "minLength": 20,
          "description": "Plain-language definition of what this object represents in the business."
        },
        "domain": {
          "type": "string",
          "description": "Data domain (e.g., 'patient-safety', 'product-master', 'finance', 'hr')."
        },
        "attributes": {
          "type": "array",
          "description": "Canonical attributes of the object. This is the business-level shape, not a physical schema. Physical schemas live in DataProductContract instances and downstream system schemas.",
          "items": {
            "type": "object",
            "required": ["name", "type"],
            "properties": {
              "name": { "type": "string" },
              "type": {
                "type": "string",
                "description": "Logical type (e.g., 'identifier', 'date', 'enumeration', 'free-text', 'reference')."
              },
              "required": { "type": "boolean" },
              "description": { "type": "string" },
              "sensitivity": {
                "type": "string",
                "enum": ["public", "internal", "confidential", "restricted", "pii", "phi"]
              }
            },
            "additionalProperties": true
          }
        },
        "semanticRules": {
          "type": "array",
          "minItems": 1,
          "description": "Business semantic rules that any instance of this object must satisfy. Rules are the operative content of a BusinessObject: they are read by fitness functions and Rego packages and apply across every DataProductContract that materializes the object. A BusinessObject without at least one semantic rule is descriptive metadata and should be modeled in the EA platform's catalogue instead.",
          "items": {
            "type": "object",
            "required": ["id", "type", "rule"],
            "properties": {
              "id": {
                "$ref": "_common.json#/$defs/identifier",
                "description": "Stable rule identifier, conventionally SR-<OBJECT>-<NUMBER> (e.g., SR-AE-001 for the first semantic rule on AdverseEvent)."
              },
              "type": {
                "type": "string",
                "enum": [
                  "identity",
                  "lifecycle",
                  "cross-attribute",
                  "classification-derivation",
                  "relationship",
                  "value-range",
                  "uniqueness",
                  "temporal"
                ],
                "description": "Category of semantic rule. identity rules govern uniqueness and immutability of identifiers; lifecycle rules govern allowed state transitions; cross-attribute rules govern conditional dependencies between attributes; classification-derivation rules govern how sensitivity tags propagate; relationship rules govern referential integrity; value-range rules constrain numeric or enumerated values; uniqueness rules govern global or scoped uniqueness; temporal rules govern timing constraints (deadlines, validity windows)."
              },
              "rule": {
                "type": "string",
                "minLength": 10,
                "description": "Plain-language statement of the rule. The executable form lives in the Rego package or workflow engine named in enforcedBy."
              },
              "enforcedBy": {
                "type": "string",
                "description": "Where and how the rule is evaluated. Typically a RegoPackage identifier (e.g., REGO-ADVERSE-EVENT-LIFECYCLE), a workflow-engine reference, or a database constraint identifier."
              },
              "severity": {
                "type": "string",
                "enum": ["blocking", "warning", "advisory"],
                "description": "Whether a rule violation blocks the operation, raises a warning, or is logged as advisory."
              }
            },
            "additionalProperties": true
          }
        },
        "classification": {
          "type": "string",
          "enum": ["public", "internal", "confidential", "restricted"],
          "description": "Highest classification level applied to instances of this object as a whole."
        },
        "dataSensitivity": {
          "type": "array",
          "description": "Sensitivity tags applied to instances (e.g., 'pii', 'phi', 'financial', 'health', 'sox').",
          "items": { "type": "string" }
        },
        "governanceOwner": {
          "type": "string",
          "description": "Single accountable role or group for the canonical definition."
        },
        "dataSteward": {
          "type": "string",
          "description": "Operational steward for the data."
        },
        "sourceSystem": {
          "type": "string",
          "description": "System of record for instances of this object."
        },
        "supportedCapabilityRefs": {
          "type": "array",
          "description": "Free-text references to business capabilities that depend on this object. Capability identifiers live in the EA platform's capability map (the EA platform's capability map, Ardoq capability nodes, etc.); the family references them as strings rather than typing them, by design.",
          "items": { "type": "string" }
        },
        "jurisdictionConstraints": {
          "type": "array",
          "description": "Jurisdictional constraints on storage, processing, or transfer (e.g., 'eu-only-storage', 'us-eu-transfer-with-scc'). Constraints propagate into any DataProductContract that materializes this object; the contract narrows but does not relax them.",
          "items": { "type": "string" }
        },
        "retentionPolicy": {
          "type": "string",
          "description": "Retention rule expressed as duration or as a named policy reference."
        },
        "eaToolMapping": {
          "type": "object",
          "description": "Pointer to the equivalent fact sheet in the EA tool (typically a DataObject fact sheet).",
          "properties": {
            "factSheet": { "type": "string" },
            "factSheetId": { "type": "string" }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}