ChatResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vera-health/json-schema/vera-health-chat-response-schema.json",
  "title": "ChatResponse",
  "description": "Returned when `stream` is `false`.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vera-health-openapi.json#/components/schemas/ChatResponse",
  "type": "object",
  "required": [
    "answer",
    "metadata",
    "vendor_metadata"
  ],
  "properties": {
    "answer": {
      "type": "string",
      "description": "The complete answer text (markdown)."
    },
    "metadata": {
      "$ref": "#/$defs/ChatMetadata"
    },
    "vendor_metadata": {
      "$ref": "#/$defs/VendorMetadata"
    }
  },
  "$defs": {
    "ChatMetadata": {
      "type": "object",
      "required": [
        "source",
        "thread_id",
        "message_id",
        "user_id",
        "timestamp"
      ],
      "description": "Your identifiers and routing fields. Returned **byte-identical** on every response event. Additional fields are accepted and echoed unchanged.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "metadata"
          ]
        },
        "source": {
          "type": "string",
          "description": "Your integration identifier. Echoed back unchanged on the non-streaming response. Pipeline routing is keyed off the API key, not this field — `metadata.source` cannot be used to select another partner's config."
        },
        "thread_id": {
          "type": "string",
          "description": "Your thread id. Vera does not interpret it."
        },
        "message_id": {
          "type": "string",
          "description": "Your message id."
        },
        "variation": {
          "type": "string",
          "description": "Free-form experiment / prompt variation tag."
        },
        "user_id": {
          "type": "string",
          "description": "Your end-user id (not a Vera user id)."
        },
        "timestamp": {
          "type": "string",
          "description": "ISO 8601 timestamp."
        }
      },
      "additionalProperties": true
    },
    "EvidenceLevel": {
      "type": "object",
      "description": "Structured Level-of-Evidence assessment for a cited paper. Populated from the offline `paper_loe` table (Babylon refs) or the legacy `references.evidence_level` JSONB (pre-Babylon refs, mapped through the v1→v2 transformer).\n\n**Rollout note:** during the v1→v2 client rollout window the server also emits the deprecated v1 fields (`study_characteristics.design`, `study_characteristics.multicenter`, `study_characteristics.randomized`, top-level `strength_factors`) derived from the v2 fields so old clients keep rendering chips. New integrations should ignore the deprecated fields.",
      "required": [
        "schema_version",
        "summary",
        "study_characteristics",
        "quality_assessment",
        "strength_tags",
        "strength_notes",
        "limitations",
        "overall_strength"
      ],
      "properties": {
        "schema_version": {
          "type": "integer",
          "enum": [
            2
          ],
          "description": "Wire-format version. Bumped when the shape changes."
        },
        "summary": {
          "type": "string",
          "description": "Long-form natural-language summary of the paper's methodology and evidence quality."
        },
        "study_characteristics": {
          "type": "object",
          "required": [
            "study_types",
            "design_label",
            "design_label_components",
            "is_guideline",
            "oxford_level",
            "sample_size",
            "follow_up_duration",
            "population"
          ],
          "properties": {
            "study_types": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "rct",
                  "cohort",
                  "case_control",
                  "cross_sectional",
                  "case_report",
                  "diagnostic_accuracy",
                  "systematic_review",
                  "meta_analysis",
                  "guideline",
                  "narrative_review",
                  "editorial",
                  "preclinical"
                ]
              },
              "description": "Primary-first canonical study-type enums. May be empty when no enum fits — in that case `design_label` carries the description."
            },
            "design_label": {
              "type": [
                "string",
                "null"
              ],
              "description": "Free-form design phrase. Set when `study_types=[]` or as a supplement to the enum array."
            },
            "design_label_components": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Server-formatted display components for the design row: `study_types` mapped through the canonical English label map plus `design_label` appended (if set). Render directly — as chips, or joined with ' · ' for a single-line label. Clients should not duplicate this formatting."
            },
            "is_guideline": {
              "type": "boolean",
              "description": "Pre-computed: true when this paper should be rendered as a guideline (either `study_types` contains 'guideline' or `design_label` mentions it). Clients use this to hide Oxford-level chips since Oxford CEBM levels do not apply to guidelines."
            },
            "oxford_level": {
              "type": "string",
              "enum": [
                "1a",
                "1b",
                "1c",
                "2a",
                "2b",
                "2c",
                "3a",
                "3b",
                "4",
                "5"
              ],
              "description": "Oxford CEBM level. Not meaningful for guidelines."
            },
            "sample_size": {
              "type": [
                "integer",
                "null"
              ]
            },
            "follow_up_duration": {
              "type": [
                "string",
                "null"
              ],
              "description": "Free-form, e.g. '12 weeks', '3.2 years'."
            },
            "population": {
              "type": [
                "string",
                "null"
              ]
            },
            "design": {
              "type": [
                "string",
                "null"
              ],
              "deprecated": true,
              "description": "Deprecated. Use `study_types[0]` / `design_label`. Server-derived for v1 client back-compat during rollout."
            },
            "multicenter": {
              "type": [
                "boolean",
                "null"
              ],
              "deprecated": true,
              "description": "Deprecated. Derived from `strength_tags.includes(\"multicenter\")`."
            },
            "randomized": {
              "type": [
                "boolean",
                "null"
              ],
              "deprecated": true,
              "description": "Deprecated. Derived from `study_types.includes(\"rct\")`."
            }
          }
        },
        "quality_assessment": {
          "type": "object",
          "required": [
            "risk_of_bias",
            "precision",
            "confounding_adjustment"
          ],
          "properties": {
            "risk_of_bias": {
              "type": "string",
              "enum": [
                "Low",
                "Moderate",
                "High",
                "Unknown"
              ]
            },
            "precision": {
              "type": "string",
              "enum": [
                "High",
                "Moderate",
                "Low",
                "Unknown"
              ]
            },
            "confounding_adjustment": {
              "type": "string",
              "enum": [
                "Adjusted",
                "Unadjusted",
                "Not applicable",
                "Unknown"
              ]
            }
          }
        },
        "strength_tags": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "adjusted_analysis",
              "blinded",
              "duplicate_review",
              "effect_size_ci",
              "evidence_based_guideline",
              "external_validation",
              "formal_sr_methodology",
              "large_sample",
              "long_followup",
              "matched_controls",
              "multicenter",
              "prospective",
              "randomized",
              "registered_protocol",
              "rob_assessment",
              "subgroup_sensitivity",
              "validated_measures"
            ]
          },
          "description": "Canonical strength-tag enums. Render via the client-side label map (`formatStrengthTag`)."
        },
        "strength_notes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Free-form notes that complement `strength_tags`. Rendered after the formatted tags in the snapshot view."
        },
        "strength_factors": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "deprecated": true,
          "description": "Deprecated alias of `strength_tags`. Populated identically during the rollout window."
        },
        "limitations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "overall_strength": {
          "type": "string",
          "enum": [
            "Very High",
            "High",
            "Moderate",
            "Low"
          ]
        }
      }
    },
    "TokenUsage": {
      "type": "object",
      "description": "Token counts for answer generation (input and output). Either may be null if the provider did not report it. Covers answer generation, not auxiliary retrieval/classification calls.",
      "properties": {
        "input_tokens": {
          "type": [
            "integer",
            "null"
          ]
        },
        "output_tokens": {
          "type": [
            "integer",
            "null"
          ]
        }
      }
    },
    "VendorMetadata": {
      "type": "object",
      "description": "Vera-owned provider data. Structure may evolve.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "vendor_metadata"
          ]
        },
        "workflow_run_id": {
          "type": "string",
          "description": "Run id — used for `GET /api/chat/v2/stream/{runId}` reconnect."
        },
        "thread_id": {
          "type": "string",
          "description": "Vera-side thread UUID."
        },
        "message_id": {
          "type": "string",
          "description": "Vera-side message UUID."
        },
        "references": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Cited papers with metadata."
        },
        "progress": {
          "type": "object",
          "properties": {
            "steps": {
              "type": "array",
              "items": {
                "type": "object"
              }
            }
          }
        },
        "doi_reference_map": {
          "type": "object",
          "description": "Maps inline citation numbers in the answer to DOI/PMID URLs."
        },
        "evidence_levels": {
          "type": "object",
          "description": "Map keyed by `paper_id`, `doi`, and `pmid` (each cited reference appears under all the keys it carries) → `EvidenceLevel`. Populated from offline-graded `paper_loe` data with a legacy fallback for pre-Babylon refs.",
          "additionalProperties": {
            "$ref": "#/$defs/EvidenceLevel"
          }
        },
        "usage": {
          "$ref": "#/$defs/TokenUsage"
        }
      },
      "additionalProperties": true
    }
  }
}