{
  "$schema":                "https://json-schema.org/draft/2020-12/schema",
  "$id":                    "https://schemas.mpai.community/PGM1/V1.0/data/InteractionHistory.json",
  "title":                  "Interaction History V1.0",
  "description":            "Interaction History (PGM-IHI) is a data type representing the ordered record of turns exchanged during an A-User session.",
  "type":                   "object",
  "additionalProperties":   false,
  "required":               ["Header", "MInstanceID", "UEnvironmentID", "SessionID", "SessionStartTime", "TurnCount", "Turns", "DataXMData"],
  "properties":             {

    "Header":               { "type": "string", "pattern": "^PGM-IHI-V[0-9]{1,2}[.][0-9]{1,2}$", "description": "Interaction History Header – Standard PGM-IHI-Vx.y." },
    "MInstanceID":          { "type": "string", "description": "Identifier of the M-Instance in which the session occurred." },
    "UEnvironmentID":       { "type": "string", "description": "Identifier of the U-Environment associated with the session." },
    "SessionID":            { "type": "string", "description": "Identifier of the A-User session to which this history belongs." },
    "SessionStartTime":     { "$ref": "https://schemas.mpai.community/PTF/V1.0/data/SimpleTime.json", "description": "Timestamp of session initialisation." },

    "TurnCount":            { "type": "integer", "minimum": 0, "description": "Total number of turns recorded in this history instance." },
    "Turns":                { "type": "array", "items": { "type": "object",  "additionalProperties": false, "required": ["TurnIndex", "Timestamp", "Role", "PRCPrompt", "BKNResponse"], "properties": {
      "TurnIndex":          { "type": "integer", "minimum": 0, "description": "Ordinal position of the turn within the session, starting from 0." },
      "Timestamp":          { "$ref": "https://schemas.mpai.community/PTF/V1.0/data/SimpleTime.json", "description": "Timestamp at which the turn was initiated." },
      "Role":               { "type": "string", "enum": ["A-User", "H-User", "BKN"], "description": "Role of the producing entity: A-User | H-User | BKN." },
      "PRCPrompt":          { "type": "object", "description": "The PRC Prompt submitted to Basic Knowledge for this turn." },
      "BKNResponse":        { "type": "object", "description": "The response produced by Basic Knowledge for this turn." },
      "UserEntityState":    { "type": "object", "description": "Optional User Entity State at the time of the turn." },
      "AUCInstruction":     { "type": "object", "description": "Optional AUC Instruction that triggered this turn." } } },
                              "description": "Ordered array of Turn records representing the interaction history." },
    "DataXMData":           { "$ref": "https://schemas.mpai.community/PTF/V1.0/data/DataExchangeMetadata.json", 
                              "description": "MPAI-PTF Data Exchange Metadata providing provenance, authorisation, legal, security, and confidence information associated with this Interaction History instance in a trusted data exchange context." },
    "DescrMetadata":        { "type": "string", "maxLength": 2048, "description": "Human-readable descriptive metadata of the Interaction History instance (plain text, max 2048 characters)." } } }