{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://healthwatch.id/.well-known/health-assertion.schema.json",
  "title": "HealthAssertion",
  "description": "HealthAssertion/v1 — the unit of trust HealthWatch returns. Every answer is a signed, versioned object rather than free prose: a claim, the evidence behind it, a calibrated confidence, an explicit verdict, and the provenance to verify it. Status: published contract; the MCP tool surface that emits it is in preview.",
  "type": "object",
  "required": ["contract", "claim", "verdict", "confidence", "evidence", "provenance", "not_medical_advice"],
  "additionalProperties": false,
  "properties": {
    "contract": {
      "type": "string",
      "const": "HealthAssertion/v1",
      "description": "Contract identifier and version."
    },
    "claim": {
      "type": "string",
      "description": "The single health claim this assertion is about.",
      "examples": ["Omega-3 modestly lowers ApoB."]
    },
    "verdict": {
      "type": "string",
      "enum": [
        "STRONG_SUPPORT",
        "MODERATE_SUPPORT",
        "WEAK_SUPPORT",
        "INSUFFICIENT_EVIDENCE",
        "CONTESTED",
        "AGAINST"
      ],
      "description": "Honest weight-of-evidence verdict. No false balance — a contested or thin literature is reported as such."
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Calibrated confidence in [0,1] (not a vibe). Reflects evidence quality and agreement, and is the signal an agent should route on."
    },
    "evidence": {
      "type": "array",
      "minItems": 0,
      "description": "The grounding behind the claim. Each item is a source with its trust tier and a resolvable reference.",
      "items": {
        "type": "object",
        "required": ["source", "tier"],
        "additionalProperties": true,
        "properties": {
          "source": { "type": "string", "description": "Human-readable source name." },
          "tier": {
            "type": "string",
            "description": "Evidence tier (e.g. meta-analysis, RCT, cohort, mechanistic, expert-curated)."
          },
          "url": { "type": "string", "format": "uri", "description": "Resolvable link to the source where one exists." }
        }
      }
    },
    "uncertainties": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Explicit, named uncertainties an agent must carry forward (e.g. heterogeneous effect size, small n, confounding)."
    },
    "provenance": {
      "type": "string",
      "description": "Opaque, walk-it-back provenance handle for the grounding (e.g. \"hw:rec:…\"). Lets a caller verify how the assertion was assembled."
    },
    "not_medical_advice": {
      "type": "boolean",
      "const": true,
      "description": "Always true. HealthWatch is educational/research and does not diagnose, prescribe, or act."
    }
  }
}