{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://piqi-alliance.org/schemas/piqi-model-schema.json",
  "title": "PIQI Model 2026",
  "description": "Schema describing a PIQI data model, comprised of a root entity and a set of data classes, each with attributes and optional attribute roles.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "mnemonic",
    "version",
    "modelTypeName",
    "rootEntityName",
    "rootEntityMnemonic",
    "dataClasses"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable name of the model.",
      "examples": ["Patient Clinical Model 1.0"]
    },
    "mnemonic": {
      "type": "string",
      "description": "Short, unique, upper-case code identifying the model.",
      "pattern": "^[A-Z0-9_]+$",
      "examples": ["PAT_CLINICAL_V1"]
    },
    "description": {
      "type": ["string", "null"],
      "description": "Free-text description of the model, its scope, and review status."
    },
    "version": {
      "type": "integer",
      "minimum": 1,
      "description": "Integer version number of the model."
    },
    "modelTypeName": {
      "type": "string",
      "description": "Classification of the model type.",
      "examples": ["Standard base"]
    },
    "baseModel": {
      "type": ["string", "null"],
      "description": "Name/reference of the base model this model extends, if any."
    },
    "rootEntityName": {
      "type": "string",
      "description": "Human-readable name of the root entity represented by this model.",
      "examples": ["patient"]
    },
    "rootEntityMnemonic": {
      "type": "string",
      "description": "Mnemonic code for the root entity.",
      "pattern": "^[A-Z0-9_]+$",
      "examples": ["PATIENT"]
    },
    "dataClasses": {
      "type": "array",
      "description": "The set of data classes that make up the model.",
      "items": { "$ref": "#/$defs/dataClass" },
      "minItems": 1
    }
  },
  "$defs": {
    "cardinality": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "mnemonic"],
      "properties": {
        "name": {
          "type": "string",
          "enum": ["One", "Zero to One", "Zero to Many", "One to Many"],
          "description": "Human-readable cardinality label."
        },
        "mnemonic": {
          "type": "string",
          "enum": ["ONE", "ZERO_TO_ONE", "ZERO_TO_MANY", "ONE_TO_MANY"],
          "description": "Mnemonic code for the cardinality."
        }
      }
    },
    "attributeType": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "mnemonic"],
      "properties": {
        "name": {
          "type": "string",
          "enum": [
            "Data Class",
            "Element",
            "Simple Attribute",
            "Codeable Concept",
            "Range Value",
            "Observation Value"
          ],
          "description": "Human-readable attribute type label."
        },
        "mnemonic": {
          "type": "string",
          "enum": ["CLS", "ELM", "ATR", "CC", "RV", "OBSVAL"],
          "description": "Mnemonic code for the attribute type."
        }
      }
    },
    "attribute": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "mnemonic",
        "shortName",
        "fieldName",
        "description",
        "sequence",
        "autoGenerated",
        "isInherited",
        "attributeType"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Human-readable name of the attribute."
        },
        "mnemonic": {
          "type": "string",
          "pattern": "^[A-Z0-9_]+$",
          "description": "Short, unique mnemonic code for the attribute."
        },
        "shortName": {
          "type": "string",
          "description": "Abbreviated display name for the attribute."
        },
        "fieldName": {
          "type": "string",
          "description": "camelCase field/property name used in data payloads."
        },
        "description": {
          "type": ["string", "null"],
          "description": "Free-text description of the attribute's meaning."
        },
        "sequence": {
          "type": "integer",
          "minimum": 1,
          "description": "Ordering position of the attribute within its data class."
        },
        "autoGenerated": {
          "type": "boolean",
          "description": "Whether the attribute is system-generated (e.g., the implicit Data Class / Element entries) rather than user-defined."
        },
        "isInherited": {
          "type": "boolean",
          "description": "Whether the attribute is inherited from a base model/data class."
        },
        "attributeType": { "$ref": "#/$defs/attributeType" }
      }
    },
    "role": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "roleTypeName",
        "roleTypeMnemonic",
        "attributeName",
        "attributeMnemonic"
      ],
      "properties": {
        "roleTypeName": {
          "type": "string",
          "description": "Human-readable name of the semantic role played by the referenced attribute.",
          "examples": ["Start Datetime", "End Datetime"]
        },
        "roleTypeMnemonic": {
          "type": "string",
          "pattern": "^[A-Z0-9_]+$",
          "description": "Mnemonic code for the role type.",
          "examples": ["START_DATETIME", "END_DATETIME"]
        },
        "attributeName": {
          "type": "string",
          "description": "Name of the attribute (within this data class) that fulfills the role."
        },
        "attributeMnemonic": {
          "type": "string",
          "pattern": "^[A-Z0-9_]+$",
          "description": "Mnemonic of the attribute (within this data class) that fulfills the role."
        }
      }
    },
    "dataClass": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "mnemonic",
        "description",
        "shortName",
        "fieldName",
        "isInherited",
        "sequence",
        "cardinality",
        "attributes",
        "roles"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Human-readable name of the data class.",
          "examples": ["Demographics", "Provenance"]
        },
        "mnemonic": {
          "type": "string",
          "pattern": "^[A-Z0-9_]+$",
          "description": "Short, unique mnemonic code for the data class."
        },
        "description": {
          "type": ["string", "null"],
          "description": "Free-text description of the data class."
        },
        "shortName": {
          "type": "string",
          "description": "Abbreviated display name for the data class."
        },
        "fieldName": {
          "type": "string",
          "description": "camelCase field/property name used in data payloads."
        },
        "isInherited": {
          "type": "boolean",
          "description": "Whether the data class is inherited from a base model."
        },
        "sequence": {
          "type": "integer",
          "minimum": 1,
          "description": "Ordering position of the data class within the model."
        },
        "cardinality": { "$ref": "#/$defs/cardinality" },
        "attributes": {
          "type": "array",
          "description": "The attributes belonging to this data class.",
          "items": { "$ref": "#/$defs/attribute" },
          "minItems": 1
        },
        "roles": {
          "type": "array",
          "description": "Semantic role assignments mapping specific attributes in this data class to well-known roles (e.g., start/end datetime).",
          "items": { "$ref": "#/$defs/role" }
        }
      }
    }
  }
}