{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ontology.dev.hiolly.com/schema/concept.json",
  "title": "Olly Ontology Concept",
  "description": "Schema for a single concept YAML file in the Olly ontology (ontology/concepts/**/*.yaml).",
  "type": "object",
  "required": ["id", "type", "labels"],
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "Fully-qualified CURIE identifier, e.g. olly:Policy.",
      "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*:[a-zA-Z][a-zA-Z0-9_]*$"
    },
    "type": {
      "type": "string",
      "description": "OWL class type, e.g. owl:Class.",
      "examples": ["owl:Class"]
    },
    "labels": {
      "type": "object",
      "description": "Human-readable labels keyed by BCP-47 language tag.",
      "minProperties": 1,
      "additionalProperties": { "type": "string" }
    },
    "description": {
      "type": "string",
      "description": "Free-text description of the concept."
    },
    "synonyms": {
      "type": "array",
      "description": "Alternate names this concept is known by.",
      "items": { "type": "string" },
      "uniqueItems": true
    },
    "deprecated_names": {
      "type": "array",
      "description": "Names that were previously used but are now deprecated.",
      "items": { "type": "string" },
      "uniqueItems": true
    },
    "layer": {
      "type": "string",
      "description": "Architectural layer this concept belongs to.",
      "enum": ["domain", "contracts", "data", "infra"]
    },
    "owner_service": {
      "type": "string",
      "description": "The Go microservice that owns this concept's authoritative data store."
    },
    "subclass_of": {
      "type": "array",
      "description": "Parent classes (CURIEs). May reference olly: concepts or external ontology terms.",
      "items": { "type": "string" },
      "uniqueItems": true
    },
    "equivalent_class": {
      "type": "array",
      "description": "OWL equivalentClass assertions (CURIEs).",
      "items": { "type": "string" },
      "uniqueItems": true
    },
    "disjoint_with": {
      "type": "array",
      "description": "OWL disjointWith assertions (CURIEs). The named class and this class share no instances.",
      "items": { "type": "string" },
      "uniqueItems": true
    },
    "properties": {
      "type": "array",
      "description": "OWL properties owned by this concept.",
      "items": { "$ref": "#/$defs/Property" }
    },
    "alignments": {
      "type": "object",
      "description": "Crosswalk to external ontologies. Key is the standard name, value is a CURIE.",
      "properties": {
        "fhir":       { "type": "string" },
        "fibo":       { "type": "string" },
        "schema_org": { "type": "string" },
        "snomed":     { "type": "string" },
        "socotra":    { "type": "string" },
        "skos":       { "type": "string" }
      },
      "additionalProperties": { "type": "string" }
    },
    "examples": {
      "type": "array",
      "description": "Concrete example instances of this concept.",
      "items": { "$ref": "#/$defs/Example" }
    },
    "lifecycle": {
      "$ref": "#/$defs/Lifecycle",
      "description": "State machine definition for concepts with explicit lifecycle."
    },
    "referenced_in": {
      "type": "object",
      "description": "Map of surface name to list of references where this concept is materialised.",
      "properties": {
        "postgres":  { "type": "array", "items": {} },
        "openapi":   { "type": "array", "items": {} },
        "kafka":     { "type": "array", "items": {} },
        "mcp":       { "type": "array", "items": {} },
        "socotra":   { "type": "array", "items": {} },
        "docs":      { "type": "array", "items": {} },
        "snapshot":  { "type": "array", "items": {} }
      },
      "additionalProperties": { "type": "array", "items": {} }
    },
    "status": {
      "type": "string",
      "description": "Maturity status of this concept.",
      "enum": ["aspirational", "deprecated", "code-backed"]
    }
  },
  "$defs": {
    "Property": {
      "type": "object",
      "description": "An OWL property declared on a concept.",
      "required": ["id", "type"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "CURIE identifier for the property, e.g. olly:premium.",
          "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*:[a-zA-Z][a-zA-Z0-9_]*$"
        },
        "type": {
          "type": "string",
          "description": "OWL property type.",
          "enum": ["owl:DatatypeProperty", "owl:ObjectProperty", "owl:AnnotationProperty"]
        },
        "range": {
          "type": "string",
          "description": "CURIE of the range type (xsd: primitive or olly: concept)."
        },
        "cardinality": {
          "$ref": "#/$defs/Cardinality"
        },
        "inverse": {
          "type": "string",
          "description": "CURIE of the inverse property."
        },
        "fhir": {
          "type": "string",
          "description": "Corresponding FHIR element path."
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of the property."
        }
      }
    },
    "Cardinality": {
      "type": "object",
      "description": "OWL cardinality constraint.",
      "additionalProperties": false,
      "properties": {
        "min": { "type": "integer", "minimum": 0 },
        "max": { "type": "integer", "minimum": 0 }
      }
    },
    "Example": {
      "type": "object",
      "description": "A concrete example instance.",
      "required": ["id"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Example instance identifier."
        },
        "description": {
          "type": "string",
          "description": "Description of the example."
        }
      }
    },
    "Lifecycle": {
      "type": "object",
      "description": "State machine definition.",
      "required": ["states"],
      "additionalProperties": false,
      "properties": {
        "states": {
          "type": "array",
          "items": { "type": "string" },
          "minItems": 1,
          "description": "Ordered list of lifecycle states."
        },
        "state_machine_ref": {
          "type": "string",
          "description": "Reference to a state machine definition document."
        }
      }
    }
  }
}