Skip to main content
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.

​
Canonical payload (HSI 1.0)

An HSI payload is a single JSON object with required top-level fields:
  • hsi_version: "1.0" (contract version).
  • observed_at_utc: RFC 3339 timestamp (event-time; typically aligns with the latest window end).
  • computed_at_utc: RFC 3339 timestamp (processing-time; must be (\ge) observed_at_utc).
  • producer: identity of the producing system (non-PII).
  • window_ids and windows: declared time windows (required).
  • privacy: privacy assertions (required; contains_pii must be false).
Optional top-level fields:
  • axes: human-state axis readings grouped by domain.
  • source_ids and sources: declared sources and their quality/degraded status.
  • embeddings: window-scoped latent vectors (sensitive; optional).
  • meta: extra non-normative metadata (string/number/bool/null only).

​
Example: full payload

{
  "hsi_version": "1.0",
  "observed_at_utc": "2025-12-28T00:02:00Z",
  "computed_at_utc": "2025-12-28T00:02:00Z",
  "producer": {
    "name": "Example Producer",
    "version": "1.0.0",
    "instance_id": "d9776c5c-7a2e-4f7e-a827-7db9b2e2edc1"
  },
  "window_ids": ["w1", "w2"],
  "windows": {
    "w1": { "start": "2025-12-28T00:01:50Z", "end": "2025-12-28T00:02:00Z", "label": "10s_window" },
    "w2": { "start": "2025-12-28T00:01:00Z", "end": "2025-12-28T00:02:00Z", "label": "60s_window" }
  },
  "source_ids": ["s_wearable", "s_app"],
  "sources": {
    "s_wearable": { "type": "sensor", "quality": 0.83, "degraded": false, "notes": "Generic sensor source; no device assumptions." },
    "s_app": { "type": "app", "quality": 0.74, "degraded": false }
  },
  "axes": {
    "affect": {
      "readings": [
        { "axis": "stress", "score": 0.31, "confidence": 0.64, "window_id": "w2", "direction": "higher_is_more", "evidence_source_ids": ["s_wearable", "s_app"] },
        { "axis": "calm", "score": 0.69, "confidence": 0.61, "window_id": "w2", "direction": "higher_is_more", "evidence_source_ids": ["s_wearable"] }
      ]
    },
    "behavior": {
      "readings": [
        { "axis": "attention", "score": 0.73, "confidence": 0.58, "window_id": "w1", "direction": "higher_is_more", "evidence_source_ids": ["s_app"] }
      ]
    }
  },
  "embeddings": [
    { "window_id": "w1", "vector": [0.12, -0.03, 0.44, 0.09], "dimension": 4, "encoding": "float32", "confidence": 0.52, "model": "example.invalid/model/example-embed-1" }
  ],
  "privacy": {
    "contains_pii": false,
    "raw_biosignals_allowed": true,
    "derived_metrics_allowed": true,
    "embedding_allowed": true,
    "consent": "explicit",
    "purposes": ["research", "personalization"],
    "notes": "Embedding included; treat as sensitive."
  },
  "meta": { "intent": "Valid example: affect + behavior + sources + embedding." }
}

​
Windows (required)

HSI uses named windows so multiple readings can reference a shared time scope without repeating timestamps.
  • Each window MUST have start and end (RFC 3339).
  • A producer MUST ensure end >= start.
  • For strict validation, window_ids must exactly match the keys of windows.

​
Axes (optional)

Human-state outputs are expressed as axis readings grouped by domain under axes. Each axis reading MUST include:
  • axis: name in lower_snake_case (e.g., valence, arousal, task_persistence).
  • score: number in ([0, 1]).
  • confidence: number in ([0, 1]).
  • window_id: must reference one of the declared windows.
Optional axis reading fields:
  • direction: one of higher_is_more, higher_is_less, bidirectional, categorical.
  • evidence_source_ids: list of declared sources used for this reading.
  • unit: optional free-form unit string (useful for behavior-like metrics).
  • notes: non-normative notes (MUST NOT contain PII).

​
Domain model

HSI 1.0 permits these domains under axes:
  • affect
  • engagement
  • behavior
Consumers MUST tolerate unknown axis names (axis values). Consumers SHOULD treat unknown domains as invalid for strict schema validation (the canonical schema sets additionalProperties: false for axes).

​
Sources (optional, but paired)

Sources describe input channels used (or expected) by the producer. They are not device claims and MUST NOT contain PII.
  • If either sources or source_ids is present, both MUST be present.
  • For strict validation, source_ids must exactly match the keys of sources.
  • A source MUST include:
    • type: sensor | app | self_report | observer | derived | other
    • quality: number in ([0, 1])
    • degraded: boolean
If evidence_source_ids is present on a reading, strict validation requires that sources/source_ids exist and all referenced source ids are declared.

​
Embeddings (optional, sensitive)

Embeddings are optional window-scoped vectors for latent state. Each embedding MUST include:
  • window_id: declared window id
  • dimension: integer
  • encoding: float32 | float64 | fp16 | int8
  • confidence: number in ([0, 1])
If vector is present, strict validation requires dimension == len(vector).

​
Privacy (required)

Every payload MUST include privacy, and privacy.contains_pii MUST be false. If a producer cannot guarantee contains_pii=false, it MUST NOT emit HSI payloads.

​
Validation & compliance

HSI defines two validator compliance levels:
  • HSI-VALIDATE-BASIC: Draft 2020-12 schema validation (structure + ranges).
  • HSI-VALIDATE-STRICT: basic validation plus cross-field integrity checks, including:
    • computed_at_utc >= observed_at_utc
    • window_ids exactly matches windows keys
    • source_ids exactly matches sources keys (when present)
    • every window_id reference is declared
    • evidence_source_ids only references declared sources (and requires sources to exist)
    • embedding.dimension == len(embedding.vector) when vector is present

​
Versioning

HSI uses Semantic Versioning as MAJOR.MINOR (patch is not used 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.
Also note:
  • Unknown top-level fields MUST be rejected under strict schema validation (additionalProperties: false).
  • Unknown axes (new axis values) MUST be tolerated.

​
Synheart Core implementation

If you’re using Synheart’s SDK, the HSI contract is implemented by Synheart Core:
HSI Version: 1.0
Last Updated: 2025-12-28