atlas-iac/services/hermes/contracts/hux/citation.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hermes.bstein.dev/contracts/hux/v1/citation.schema.json",
  "title": "HUX sources, passages, citations, research notebook",
  "description": "Research model (HUX-08). A source is where evidence came from; a passage is the exact excerpt; a citation ties a claim in a message to passages with an explicit support verdict; a notebook collects them per research question with assumptions and unresolved questions kept visible.",
  "$defs": {
    "source": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "id",
        "kind",
        "title",
        "classification",
        "retrieved_at"
      ],
      "properties": {
        "schema": {
          "const": "hux.source.v1"
        },
        "id": {
          "$ref": "common.schema.json#/$defs/id"
        },
        "kind": {
          "type": "string",
          "enum": [
            "web",
            "document",
            "artifact",
            "memory",
            "tool_output",
            "dataset"
          ]
        },
        "uri": {
          "type": "string",
          "maxLength": 2000
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        },
        "publisher": {
          "type": "string",
          "maxLength": 200
        },
        "published_at": {
          "$ref": "common.schema.json#/$defs/timestamp"
        },
        "retrieved_at": {
          "$ref": "common.schema.json#/$defs/timestamp"
        },
        "classification": {
          "type": "string",
          "enum": [
            "primary",
            "secondary",
            "unknown"
          ]
        },
        "content_hash": {
          "$ref": "common.schema.json#/$defs/sha256"
        },
        "provenance": {
          "$ref": "common.schema.json#/$defs/provenance"
        },
        "dedupe_key": {
          "type": "string",
          "description": "Stable key used to merge duplicates: sha256 of normalised uri (source), of source_id+text hash (passage), of message_id+claim+passages (citation).",
          "pattern": "^sha256:[0-9a-f]{64}$"
        },
        "revision": {
          "$ref": "common.schema.json#/$defs/revision"
        }
      }
    },
    "passage": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "id",
        "source_id",
        "text",
        "hash"
      ],
      "properties": {
        "schema": {
          "const": "hux.passage.v1"
        },
        "id": {
          "$ref": "common.schema.json#/$defs/id"
        },
        "source_id": {
          "$ref": "common.schema.json#/$defs/id"
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        },
        "hash": {
          "$ref": "common.schema.json#/$defs/sha256"
        },
        "locator": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "page": {
              "type": "integer",
              "minimum": 1
            },
            "selector": {
              "type": "string",
              "maxLength": 500
            },
            "line_start": {
              "type": "integer",
              "minimum": 1
            },
            "line_end": {
              "type": "integer",
              "minimum": 1
            },
            "char_start": {
              "type": "integer",
              "minimum": 0
            },
            "char_end": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "dedupe_key": {
          "type": "string",
          "description": "Stable key used to merge duplicates: sha256 of normalised uri (source), of source_id+text hash (passage), of message_id+claim+passages (citation).",
          "pattern": "^sha256:[0-9a-f]{64}$"
        },
        "revision": {
          "$ref": "common.schema.json#/$defs/revision"
        }
      }
    },
    "citation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "id",
        "message_id",
        "claim",
        "passage_ids",
        "support"
      ],
      "properties": {
        "schema": {
          "const": "hux.citation.v1"
        },
        "id": {
          "$ref": "common.schema.json#/$defs/id"
        },
        "message_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "claim": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1000
        },
        "passage_ids": {
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "uniqueItems": true,
          "items": {
            "$ref": "common.schema.json#/$defs/id"
          }
        },
        "support": {
          "type": "string",
          "enum": [
            "supports",
            "partially_supports",
            "contradicts",
            "unverified"
          ]
        },
        "note": {
          "type": "string",
          "maxLength": 500
        },
        "dedupe_key": {
          "type": "string",
          "description": "Stable key used to merge duplicates: sha256 of normalised uri (source), of source_id+text hash (passage), of message_id+claim+passages (citation).",
          "pattern": "^sha256:[0-9a-f]{64}$"
        },
        "revision": {
          "$ref": "common.schema.json#/$defs/revision"
        }
      }
    },
    "notebook": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "id",
        "conversation_id",
        "question",
        "status",
        "source_ids",
        "passage_ids",
        "citation_ids",
        "assumptions",
        "unresolved_questions",
        "updated_at",
        "notes",
        "revision"
      ],
      "properties": {
        "schema": {
          "const": "hux.research_notebook.v1"
        },
        "id": {
          "$ref": "common.schema.json#/$defs/id"
        },
        "conversation_id": {
          "$ref": "common.schema.json#/$defs/id"
        },
        "question": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1000
        },
        "status": {
          "type": "string",
          "enum": [
            "open",
            "answered",
            "abandoned"
          ]
        },
        "source_ids": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "$ref": "common.schema.json#/$defs/id"
          }
        },
        "passage_ids": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "$ref": "common.schema.json#/$defs/id"
          }
        },
        "citation_ids": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "$ref": "common.schema.json#/$defs/id"
          }
        },
        "assumptions": {
          "type": "array",
          "maxItems": 64,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        },
        "unresolved_questions": {
          "type": "array",
          "maxItems": 64,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        },
        "updated_at": {
          "$ref": "common.schema.json#/$defs/timestamp"
        },
        "notes": {
          "type": "array",
          "maxItems": 128,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "at",
              "text"
            ],
            "properties": {
              "at": {
                "$ref": "common.schema.json#/$defs/timestamp"
              },
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "source_id": {
                "$ref": "common.schema.json#/$defs/id"
              }
            }
          }
        },
        "revision": {
          "$ref": "common.schema.json#/$defs/revision"
        }
      }
    }
  },
  "oneOf": [
    {
      "$ref": "#/$defs/source"
    },
    {
      "$ref": "#/$defs/passage"
    },
    {
      "$ref": "#/$defs/citation"
    },
    {
      "$ref": "#/$defs/notebook"
    }
  ]
}