Skip to main content
HSI is at version 1.3. This page is a high-level orientation. The canonical schemas, RFCs, and validator live in the hsi repository:
  • Payload structure.
  • Canonicalization, content hashing, signatures (HSI-VALIDATE-INTEGRITY).
  • Canonical 5-axis domain set (physiological / kinematic / digital / cognitive / affective).
  • Multimodal attribution (modalities_used, confidence_breakdown).
Producers and consumers dispatch on hsi_version and validate against the schema for the declared version.
Human State Interface (HSI) is a language-agnostic, contract-only specification for exchanging human-state signals between independent systems (producers and consumers). HSI defines a canonical JSON payload, explicit time windows, normalized scores + confidence, an authoritative JSON Schema, and versioning rules so teams can interoperate without sharing implementation details.
HSI is a data contract. It does not specify models, sensor pipelines, SDKs, or device assumptions.

​
What HSI is (and is not)

  • HSI is: a stable, versioned payload contract; a schema you can validate against; and a compatibility policy for evolution.
  • HSI is not: an SDK, an inference model, a sensor pipeline, or a device specification.

​
Top-level structure (HSI 1.3)

An HSI 1.3 payload is a single JSON object. Required top-level fields:
  • hsi_version — "1.3".
  • observed_at_utc — RFC 3339 timestamp (event-time; typically aligns with the latest window’s end_utc).
  • computed_at_utc — RFC 3339 timestamp (processing-time; must be ≥ observed_at_utc).
  • producer — identity of the producing system (non-PII).
  • windows — map of window IDs to window descriptors (each requires start_utc and end_utc).
  • privacy — privacy assertions; contains_pii MUST be false, plus required raw_biosignals_allowed and derived_metrics_allowed.
Optional top-level fields:
  • axes — human-state axis readings grouped by domain (see canonical 5-axis set below).
  • embeddings — window-scoped latent vectors (sensitive; vector or vector_hash).
  • integrity — canonicalization + content hash + signature block.
  • meta — non-normative metadata, including meta.provenance (sources, providers, engine identifiers, equation IDs, SRM snapshot IDs).

​
Canonical 5-axis domain set

In HSI 1.3, the axes object is closed (additionalProperties: false) and permits exactly these five domains:
DomainWhat it carries
physiologicalCardiovascular, autonomic, sleep, recovery, and similar biosignals.
kinematicMotion, posture, activity-state classification.
digitalInteraction-derived signals (taps, scrolls, typing rhythm, app context).
cognitiveFocus, attention, capacity, fatigue.
affectiveValence, arousal, emotional state.
Consumers MUST tolerate unknown axis names (name values) within a known domain, but MUST reject unknown domains under strict validation.

​
Axis readings (HSI 1.3)

Each axis reading is an object with these required fields:
  • name — lower_snake_case (e.g. arousal, task_persistence, hr_rmssd).
  • score — number in [0, 1] (or label, see direction: categorical).
  • confidence — number in [0, 1].
  • direction — one of higher_is_more, lower_is_more, bidirectional, categorical.
  • window_ids — array of window IDs this reading covers.
  • evidence_source_ids — array of source IDs declared under meta.provenance.sources.
  • inference_mode — describes how the score was produced (e.g. model, heuristic, pass_through).
  • model_id — identifier of the model or rulepack used.
Optional fields include unit, notes (no PII), modalities_used, confidence_breakdown (per-channel attribution), and for direction: categorical, label and categories.

​
Example payload

A minimal but complete HSI 1.3 envelope with one window and one axis reading: 
{
  "hsi_version": "1.3",
  "observed_at_utc": "2026-01-15T10:30:00Z",
  "computed_at_utc": "2026-01-15T10:30:00.420Z",
  "producer": {
    "name": "synheart-runtime",
    "version": "5.4.0",
    "instance_id": "device_3f1c8b"
  },
  "windows": {
    "w_micro_30s": {
      "start_utc": "2026-01-15T10:29:30Z",
      "end_utc": "2026-01-15T10:30:00Z",
      "duration_seconds": 30
    }
  },
  "axes": {
    "cognitive": [
      {
        "name": "focus",
        "score": 0.72,
        "confidence": 0.81,
        "direction": "higher_is_more",
        "window_ids": ["w_micro_30s"],
        "evidence_source_ids": ["wear_hrv", "behavior_taps"],
        "inference_mode": "model",
        "model_id": "focus.v1",
        "modalities_used": ["physiological", "digital"]
      }
    ]
  },
  "privacy": {
    "contains_pii": false,
    "raw_biosignals_allowed": false,
    "derived_metrics_allowed": true
  },
  "meta": {
    "provenance": {
      "sources": [
        { "id": "wear_hrv", "kind": "wearable", "vendor": "apple_watch" },
        { "id": "behavior_taps", "kind": "behavior", "vendor": "synheart_behavior" }
      ]
    }
  }
}
The same envelope shape carries any combination of axes across the five canonical domains; consumers MUST validate against the schema for the declared hsi_version.

​
Privacy block

Every payload MUST include privacy with at minimum:
  • contains_pii: false
  • raw_biosignals_allowed: <bool>
  • derived_metrics_allowed: <bool>
If a producer cannot guarantee contains_pii=false, it MUST NOT emit HSI payloads.

​
Validation tiers

HSI defines three validator levels:
  • HSI-VALIDATE-BASIC — Draft 2020-12 schema validation (structure + ranges).
  • HSI-VALIDATE-STRICT — basic plus cross-field integrity (timestamp ordering, declared-window references, source-id references, embedding dimension equals vector length when present).
  • HSI-VALIDATE-INTEGRITY — strict plus canonicalization + content_hash + signature verification on the optional integrity block.

​
Versioning policy

HSI uses Semantic Versioning as MAJOR.MINOR (patch is unused for payload compatibility).
  • Major: breaking changes. Consumers supporting 1.x MUST reject 2.0+ unless explicitly updated.
  • Minor: backward-compatible additions/clarifications within the same major.
  • Unknown top-level fields MUST be rejected under strict validation (additionalProperties: false).
  • Unknown axes (new name values) MUST be tolerated.

​
Synheart Core implementation

If you’re using Synheart’s SDK, the HSI contract is implemented by the Synheart runtime and surfaced through Synheart Core:
Canonical HSI version: 1.3. See the hsi repo for schemas and RFCs HSI-0008 / HSI-0009 / HSI-0010 / HSI-0011.