{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "ucwm/schemas/facets.json",
  "title": "Facets",
  "description": "Typed partial views that attach to CanonicalObjects. Facets are optional and additive — not every object exists in every relation type.",
  "$defs": {
    "BaseFacet": {
      "type": "object",
      "required": ["facet_id", "facet_kind", "object_ref", "confidence", "source_module"],
      "properties": {
        "facet_id": {
          "type": "string",
          "description": "Unique identifier for this facet instance."
        },
        "facet_kind": {
          "type": "string",
          "enum": [
            "temporal",
            "spatial",
            "causal",
            "logical",
            "syntactic",
            "semantic",
            "social",
            "ownership",
            "code_structure",
            "quantity",
            "planning"
          ]
        },
        "object_ref": {
          "type": "string",
          "description": "The object_id this facet is attached to."
        },
        "confidence": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "source_module": {
          "type": "string",
          "description": "Specialist module that produced this facet."
        },
        "provenance_refs": {
          "type": "array",
          "items": { "type": "string" },
          "default": []
        }
      }
    },

    "TemporalFacet": {
      "allOf": [
        { "$ref": "#/$defs/BaseFacet" },
        {
          "type": "object",
          "description": "Temporal description: when this object exists, begins, ends, or recurs.",
          "properties": {
            "facet_kind": { "const": "temporal" },
            "time_point": {
              "type": "string",
              "description": "Absolute or relative time point. ISO 8601 when known."
            },
            "interval_start": { "type": "string" },
            "interval_end": { "type": "string" },
            "temporal_order_refs": {
              "type": "array",
              "items": { "type": "string" },
              "description": "IDs of constraint records expressing before/after/during relations."
            },
            "is_recurring": { "type": "boolean", "default": false },
            "recurrence_pattern": {
              "type": "string",
              "description": "Natural language or ISO 8601 recurrence expression."
            },
            "duration": { "type": "string" }
          }
        }
      ]
    },

    "SpatialFacet": {
      "allOf": [
        { "$ref": "#/$defs/BaseFacet" },
        {
          "type": "object",
          "description": "Spatial description: where this object is, was, or will be.",
          "properties": {
            "facet_kind": { "const": "spatial" },
            "location_label": { "type": "string" },
            "coordinates": {
              "type": "object",
              "properties": {
                "x": { "type": "number" },
                "y": { "type": "number" },
                "z": { "type": "number" }
              }
            },
            "containment_refs": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Constraint IDs expressing inside/outside/adjacent relations."
            },
            "reference_frame": {
              "type": "string",
              "description": "The coordinate system or reference object."
            }
          }
        }
      ]
    },

    "CausalFacet": {
      "allOf": [
        { "$ref": "#/$defs/BaseFacet" },
        {
          "type": "object",
          "description": "Causal description: what caused or was caused by this object.",
          "properties": {
            "facet_kind": { "const": "causal" },
            "cause_refs": {
              "type": "array",
              "items": { "type": "string" },
              "description": "IDs of objects or events that caused this one."
            },
            "effect_refs": {
              "type": "array",
              "items": { "type": "string" },
              "description": "IDs of objects or events caused by this one."
            },
            "enabling_refs": {
              "type": "array",
              "items": { "type": "string" }
            },
            "blocking_refs": {
              "type": "array",
              "items": { "type": "string" }
            },
            "causal_strength": {
              "type": "string",
              "enum": ["necessary", "sufficient", "contributing", "correlational"]
            }
          }
        }
      ]
    },

    "LogicalFacet": {
      "allOf": [
        { "$ref": "#/$defs/BaseFacet" },
        {
          "type": "object",
          "description": "Logical description: truth value, negation, quantification, implication.",
          "properties": {
            "facet_kind": { "const": "logical" },
            "truth_status": {
              "type": "string",
              "enum": ["true", "false", "unknown", "hypothetical", "negated", "asserted"]
            },
            "quantifier": {
              "type": "string",
              "enum": ["universal", "existential", "none"]
            },
            "implies_refs": {
              "type": "array",
              "items": { "type": "string" },
              "description": "IDs of propositions this object implies."
            },
            "negates_refs": {
              "type": "array",
              "items": { "type": "string" }
            },
            "contradicts_refs": {
              "type": "array",
              "items": { "type": "string" }
            }
          }
        }
      ]
    },

    "OwnershipFacet": {
      "allOf": [
        { "$ref": "#/$defs/BaseFacet" },
        {
          "type": "object",
          "description": "Ownership and possession description: who holds what, and when.",
          "properties": {
            "facet_kind": { "const": "ownership" },
            "owner_ref": {
              "type": "string",
              "description": "object_id of the current owner."
            },
            "owned_ref": {
              "type": "string",
              "description": "object_id of the thing owned."
            },
            "quantity_ref": {
              "type": "string",
              "description": "object_id of a quantity object if ownership is of a counted resource."
            },
            "temporal_ref": {
              "type": "string",
              "description": "Facet ID providing temporal scope for this ownership."
            },
            "transfer_type": {
              "type": "string",
              "enum": ["give", "sell", "take", "lose", "receive", "initial", "final"]
            }
          }
        }
      ]
    },

    "QuantityFacet": {
      "allOf": [
        { "$ref": "#/$defs/BaseFacet" },
        {
          "type": "object",
          "description": "Quantity description: numeric value, unit, precision.",
          "properties": {
            "facet_kind": { "const": "quantity" },
            "value": {
              "oneOf": [
                { "type": "number" },
                { "type": "string", "description": "Symbolic expression e.g. 'Q1 - 2'" }
              ]
            },
            "unit": { "type": "string" },
            "precision": { "type": "number" },
            "is_exact": { "type": "boolean" },
            "derived_from_refs": {
              "type": "array",
              "items": { "type": "string" },
              "description": "object_ids of quantities this was computed from."
            }
          }
        }
      ]
    },

    "SyntacticFacet": {
      "allOf": [
        { "$ref": "#/$defs/BaseFacet" },
        {
          "type": "object",
          "description": "Syntactic description: role in sentence structure.",
          "properties": {
            "facet_kind": { "const": "syntactic" },
            "grammatical_role": {
              "type": "string",
              "enum": ["subject", "object", "indirect_object", "adjunct", "predicate", "modifier", "other"]
            },
            "head_token": { "type": "string" },
            "dependency_arc": { "type": "string" }
          }
        }
      ]
    },

    "SocialFacet": {
      "allOf": [
        { "$ref": "#/$defs/BaseFacet" },
        {
          "type": "object",
          "description": "Social and agentive description: beliefs, intentions, obligations, roles.",
          "properties": {
            "facet_kind": { "const": "social" },
            "agent_ref": { "type": "string" },
            "social_act": {
              "type": "string",
              "enum": ["assert", "request", "promise", "threaten", "deceive", "inform", "ask", "other"]
            },
            "belief_about_ref": { "type": "string" },
            "belief_truth_status": {
              "type": "string",
              "enum": ["true", "false", "unknown"]
            },
            "obligation_refs": {
              "type": "array",
              "items": { "type": "string" }
            },
            "role": { "type": "string" }
          }
        }
      ]
    },

    "PlanningFacet": {
      "allOf": [
        { "$ref": "#/$defs/BaseFacet" },
        {
          "type": "object",
          "description": "Planning description: steps, goals, prerequisites, dependencies.",
          "properties": {
            "facet_kind": { "const": "planning" },
            "step_index": { "type": "integer" },
            "prerequisite_refs": {
              "type": "array",
              "items": { "type": "string" }
            },
            "goal_refs": {
              "type": "array",
              "items": { "type": "string" }
            },
            "blocks_refs": {
              "type": "array",
              "items": { "type": "string" }
            },
            "status": {
              "type": "string",
              "enum": ["pending", "in_progress", "complete", "blocked", "skipped"]
            }
          }
        }
      ]
    }
  },

  "oneOf": [
    { "$ref": "#/$defs/TemporalFacet" },
    { "$ref": "#/$defs/SpatialFacet" },
    { "$ref": "#/$defs/CausalFacet" },
    { "$ref": "#/$defs/LogicalFacet" },
    { "$ref": "#/$defs/OwnershipFacet" },
    { "$ref": "#/$defs/QuantityFacet" },
    { "$ref": "#/$defs/SyntacticFacet" },
    { "$ref": "#/$defs/SocialFacet" },
    { "$ref": "#/$defs/PlanningFacet" }
  ]
}