contracts/advisory_claim_register.v1.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://mparanza.com/schemas/clara/advisory-claim-register-v1.json",
  "title": "Clara advisory claim register",
  "description": "Append-only claims used in advisory analysis, with generation-time evidence and dependency references. Semantic contents are model-authored; deterministic code validates the declared graph.",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema_version", "claims"],
  "properties": {
    "schema_version": {"const": "1.0"},
    "claims": {
      "type": "array",
      "items": {"$ref": "#/$defs/claim"}
    }
  },
  "$defs": {
    "id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
    },
    "text": {
      "type": "string",
      "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$"
    },
    "textList": {
      "type": "array",
      "uniqueItems": true,
      "items": {"$ref": "#/$defs/text"}
    },
    "provenance": {
      "type": "object",
      "additionalProperties": false,
      "required": ["workflow", "step", "artifact", "locator"],
      "properties": {
        "workflow": {"type": "string", "pattern": "^clara:[a-z0-9-]+$"},
        "step": {"$ref": "#/$defs/text"},
        "artifact": {"type": "string"},
        "locator": {"$ref": "#/$defs/text"}
      }
    },
    "origin": {
      "type": "object",
      "additionalProperties": false,
      "required": ["source_case_id", "source_id", "exchange_id"],
      "properties": {
        "source_case_id": {"$ref": "#/$defs/text"},
        "source_id": {"$ref": "#/$defs/id"},
        "exchange_id": {"$ref": "#/$defs/text"}
      }
    },
    "evidenceLink": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "evidence_id",
        "relationship",
        "analysis",
        "proves",
        "does_not_prove"
      ],
      "properties": {
        "evidence_id": {"$ref": "#/$defs/id"},
        "relationship": {"enum": ["supports", "weakens", "contradicts", "creates", "context"]},
        "analysis": {"$ref": "#/$defs/text"},
        "proves": {"$ref": "#/$defs/text"},
        "does_not_prove": {"$ref": "#/$defs/text"},
        "directness": {"enum": ["direct", "indirect", "contextual", "unknown"]},
        "reliability": {"enum": ["high", "medium", "low", "unknown"]},
        "corroboration": {"enum": ["corroborated", "single_source", "contradicted", "unknown"]},
        "bias_or_limitation": {"type": "string"}
      }
    },
    "dependency": {
      "type": "object",
      "additionalProperties": false,
      "required": ["mode", "claim_ids", "derivation_type", "explanation", "calculation_evidence_id"],
      "properties": {
        "mode": {"enum": ["none", "all_of", "any_of"]},
        "claim_ids": {
          "type": "array",
          "uniqueItems": true,
          "items": {"$ref": "#/$defs/id"}
        },
        "derivation_type": {
          "enum": ["direct", "calculation", "reasoning", "aggregation", "quotation"]
        },
        "explanation": {"$ref": "#/$defs/text"},
        "calculation_evidence_id": {"type": "string"}
      }
    },
    "appearance": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "artifact",
        "path_reference",
        "artifact_sha256",
        "artifact_byte_count",
        "locator",
        "recorded_at"
      ],
      "properties": {
        "artifact": {"$ref": "#/$defs/text"},
        "path_reference": {"enum": ["case_relative", "absolute"]},
        "artifact_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
        "artifact_byte_count": {"type": "integer", "minimum": 0},
        "locator": {"$ref": "#/$defs/text"},
        "recorded_at": {"$ref": "#/$defs/text"},
        "format_claim_id": {"type": "string"}
      }
    },
    "claim": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "statement",
        "claim_type",
        "recorded_at",
        "recorded_by",
        "provenance",
        "evidence_links",
        "dependency",
        "decision_use",
        "uncertainty",
        "professional_judgement_required",
        "appearances",
        "state",
        "supersedes_claim_id"
      ],
      "properties": {
        "id": {"$ref": "#/$defs/id"},
        "statement": {"$ref": "#/$defs/text"},
        "claim_type": {
          "enum": [
            "observation",
            "assertion",
            "quotation",
            "calculation",
            "inference",
            "conclusion",
            "recommendation",
            "decision_condition"
          ]
        },
        "recorded_at": {"$ref": "#/$defs/text"},
        "recorded_by": {"$ref": "#/$defs/text"},
        "provenance": {"$ref": "#/$defs/provenance"},
        "evidence_links": {
          "type": "array",
          "items": {"$ref": "#/$defs/evidenceLink"}
        },
        "dependency": {"$ref": "#/$defs/dependency"},
        "decision_use": {"enum": ["direct", "supporting", "contextual"]},
        "uncertainty": {"$ref": "#/$defs/textList"},
        "professional_judgement_required": {"type": "boolean"},
        "appearances": {
          "type": "array",
          "items": {"$ref": "#/$defs/appearance"}
        },
        "state": {"enum": ["active", "superseded", "withdrawn"]},
        "supersedes_claim_id": {"type": "string"},
        "origin": {"$ref": "#/$defs/origin"},
        "decision_implication": {"type": "string"},
        "missing_evidence_that_would_change_position": {"type": "string"}
      }
    }
  }
}