{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hbfnetwork.org/platform/science/validation-evidence.schema.json",
  "title": "HBF validation evidence artifact",
  "description": "The only accepted route for moving a subsystem above BENCHMARK_REPRODUCED. Phases 2-4 of the audit cannot be completed in software alone; this schema is the handoff interface so that when real data arrives it enters through a reviewed, checksummed path instead of being pasted into a UI string.",
  "type": "object",
  "required": [
    "evidence_id",
    "target",
    "study",
    "data",
    "review",
    "result",
    "declared_domain"
  ],
  "additionalProperties": false,
  "properties": {
    "evidence_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9._-]{4,63}$"
    },
    "target": {
      "type": "object",
      "required": [
        "subsystem",
        "model_id",
        "model_version",
        "observable"
      ],
      "additionalProperties": false,
      "description": "EXACTLY what this evidence supports. Never a whole lab, never 'the platform'.",
      "properties": {
        "subsystem": {
          "type": "string"
        },
        "model_id": {
          "type": "string"
        },
        "model_version": {
          "type": "string"
        },
        "observable": {
          "type": "string"
        }
      }
    },
    "study": {
      "type": "object",
      "required": [
        "kind",
        "preregistered",
        "blinded",
        "frozen_hashes_before_reveal"
      ],
      "additionalProperties": false,
      "properties": {
        "kind": {
          "enum": [
            "code_to_code",
            "benchmark_reproduction",
            "retrospective_comparison",
            "prospective_blinded",
            "accelerator_measurement",
            "plasma_measurement"
          ]
        },
        "preregistered": {
          "type": "boolean"
        },
        "preregistration_url": {
          "type": "string"
        },
        "blinded": {
          "type": "boolean"
        },
        "frozen_hashes_before_reveal": {
          "type": "object",
          "description": "Model, data and code hashes recorded BEFORE the data were seen.",
          "required": [
            "model_sha256",
            "code_sha256",
            "data_sha256"
          ],
          "properties": {
            "model_sha256": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            },
            "code_sha256": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            },
            "data_sha256": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            }
          }
        },
        "facility": {
          "type": "string"
        },
        "date_utc": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "data": {
      "type": "object",
      "required": [
        "source_kind",
        "license",
        "retrieved_utc",
        "sha256"
      ],
      "additionalProperties": false,
      "properties": {
        "source_kind": {
          "enum": [
            "experimental_primary",
            "evaluated_library",
            "independent_code",
            "partner_dataset"
          ]
        },
        "license": {
          "type": "string"
        },
        "retrieved_utc": {
          "type": "string"
        },
        "sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "exfor_accession": {
          "type": "string"
        },
        "doi": {
          "type": "string"
        }
      }
    },
    "review": {
      "type": "object",
      "required": [
        "transcriber",
        "independent_reviewer",
        "review_state"
      ],
      "additionalProperties": false,
      "description": "Two distinct named humans. Never auto-populated.",
      "properties": {
        "transcriber": {
          "type": "string"
        },
        "independent_reviewer": {
          "type": "string"
        },
        "review_state": {
          "enum": [
            "pending",
            "accepted",
            "rejected"
          ]
        },
        "review_notes": {
          "type": "string"
        },
        "reviewed_utc": {
          "type": "string"
        }
      }
    },
    "result": {
      "type": "object",
      "required": [
        "agreement_metric",
        "value",
        "residuals_published",
        "failures_published"
      ],
      "additionalProperties": false,
      "properties": {
        "agreement_metric": {
          "type": "string"
        },
        "value": {
          "type": "number"
        },
        "uncertainty": {
          "type": "number"
        },
        "residuals_published": {
          "type": "boolean"
        },
        "failures_published": {
          "type": "boolean",
          "description": "Successes AND failures must both be published (audit Phase 4 item 4)."
        },
        "post_hoc_changes": {
          "type": "string"
        }
      }
    },
    "declared_domain": {
      "type": "object",
      "required": [
        "applies_within",
        "does_not_apply_beyond"
      ],
      "additionalProperties": false,
      "properties": {
        "applies_within": {
          "type": "string"
        },
        "does_not_apply_beyond": {
          "type": "string"
        }
      }
    },
    "grants_maturity": {
      "enum": [
        "CROSS_CODE_BENCHMARKED",
        "EXPERIMENTALLY_VALIDATED"
      ],
      "description": "Honoured ONLY if review.review_state == 'accepted', study.blinded is true for EXPERIMENTALLY_VALIDATED, and frozen hashes are present."
    }
  }
}