HEART Part 3: Information Model#

What a HEART tells you, and in what shape

Author: Milind K. Patil, Syncaissa Systems Inc. Status: Working draft 1, November 2026. Part of the HEART Standards Family. Version: 1.0 (draft) Read first: Part 1: Basics, for the words used here. Track: Basic: "In one minute", Sections 2, 3.1, 3.2, 3.4, 4, 5.1 to 5.4, 5.6, 5.7, 7 and 9. Intermediate adds 3.3, 3.7, 5.8, 8, 10 and 11. Advanced adds 3.5, 3.6 and 6. Sections 5.5 and 12 to 14 are reference.

In one minute#

Every HEART says things about itself using seven main messages. Six travel as messages of their own; the Capability lives inside the Card:

Every message travels in the same envelope, and uses the same shared word lists. For example, health is always one of healthy, degraded, failing or unknown.

Problems are named with fault codes from one shared list, such as storage.full or sensors.drift. A fault code means the same thing on every product, the way OBD-II code P0300 means "engine misfire" on every car. Outside messages it is written HEART storage.full, and each standard code also has a short number, such as H-04002.

This part describes what is said. It does not say how messages travel (that is Part 4), so the same information can be carried by HTTP, MQTT or, later, industrial standards such as OPC UA.

1. What an "information model" is#

Think of a paper form, like a doctor's check-up form. It has fixed boxes: name, date, blood pressure, temperature, notes. Every doctor fills in the same boxes, so any other doctor can read it.

An information model is the same idea for machines. It says:

• which forms exist: Card, Pulse, Arrhythmia and so on,
• which boxes each form has, and which are required,
• what may be written in each box: a number, a date, or one word from a fixed list.

It does not say how the form is delivered: by post, by fax or by hand. That is Part 4.

Keeping the two apart matters. The forms stay the same while delivery methods change. A tiny sensor and a cloud server can fill in the same forms, and deliver them in completely different ways.

Where the exact definitions live#

This part explains the model in words. The exact, machine-checkable definitions are the JSON Schema files in schemas/1.0/, with one example of each message in examples/. If this part and a schema disagree, that is a mistake in the standard, and should be reported.

2. The envelope#

Every message a HEART sends about itself goes inside the same envelope. Like the outside of a parcel, the envelope says who it is from, what is inside and when it was sent. The message itself sits inside, in data.

HEART does not invent its own envelope. It uses CloudEvents, a widely used standard for event messages, so existing tools can already route HEART messages.

{
  "specversion": "1.0",
  "id": "c7f3a9e2-1b44-4d0e-9a51-2f6c8e1d7b90",
  "source": "/heart/com.example.cool-air.ac-controller/unit-12",
  "type": "heart.pulse",
  "time": "2026-11-08T10:00:00Z",
  "datacontenttype": "application/json",
  "heartversion": "1.0",
  "heartprivacy": "public",
  "data": {
    "system": { "id": "com.example.cool-air.ac-controller", "name": "CoolAir AC Controller", "version": "0.1.0" },
    "status": "healthy",
    "sequence": 90,
    "intervalSec": 60
  }
}

All of these are required except heartredacted, which is present only when something was removed.

Requests sent to a system, such as "invoke this capability", are not statements about the system, so they do not need the envelope over HTTP. Part 4 explains how they are carried.

3. The seven main messages#

Six of these have a type of their own. The Capability does not: it is a part of the Card. One more message belongs with them: Evolution (heart.evolution, schema evolution) says which AI model is pinned and how new candidates tested. It is part of the Full Feature Set ("AI model tracking", Section 7), so the API Standard lists it among its seven core types, in place of the Capability.

There are also smaller messages for optional modules (Section 8), such as heart.component and heart.property. The prefix heart. is reserved for the standard. A product may add its own message types, named with its own reversed domain name, such as com.coolair.service-report (Section 9).

In the tables below, a bold box name means the box is required.

3.1 Card: who I am#

The Card is the system's identity card. A consumer reads it first, and usually only once.

{
  "system": { "id": "com.example.cool-air.ac-controller", "name": "CoolAir AC Controller",
              "version": "0.1.0", "owner": "Example Climate Ltd" },
  "level": "full",
  "bindings": ["http-server", "unix-socket"],
  "pulse": { "intervalSec": 30 },
  "modules": ["control", "properties", "custom", "core"],
  "profiles": ["hvac"],
  "autonomy": { "level": 2, "higher": [ { "level": 4, "areas": ["connectivity", "storage"] } ] },
  "capabilities": [ { "name": "calibrate", "risk": "write", "...": "see Section 3.5" } ]
}

The Card is shown filtered. An anonymous caller sees only the public parts. A capability is shown only to callers allowed to use it.

3.2 Pulse: how I am#

The Pulse is a short message sent at a regular interval, or read on demand. Its first job is to say "I'm alive". Its second is to say how the system is.

So anyone can learn whether a system is healthy, and only the owner's side learns the details.

Vitals are a summary. Detailed measurements belong in a monitoring standard such as OpenTelemetry, not in the Pulse.

Flatline. If no Pulse has arrived for three intervals, a consumer MUST treat the system's status as unknown. A Gateway or monitoring system SHOULD then raise an Arrhythmia with code system.flatline (Section 5).

3.3 Rhythm: what happened#

The Rhythm is the system's history: a list of events, oldest first. Each event is one thing that happened.

The event names starting with system., state., component., ai., tending., evolving., valve., circulation. and security. are reserved for the standard. Product events use any other name and the category domain.

The standard event types (the values of name reserved for the standard) are listed in Section 5.8. An event type says that something happened. It is not a fault code.

If old history has been deleted to save space, the system MUST say so (Part 4 explains how), so nobody mistakes a gap for "nothing happened".

3.4 Arrhythmia: something is wrong#

An Arrhythmia is an alert. It is the most important message, because it carries the system's own view of what is wrong.

It answers three questions:

1. What is wrong? The fault code, for example actuators.short-cycling.
2. Why? The cause, with its own fault code where known, for example sensors.drift.
3. What is being done? Its status, and any actions.

{
  "id": "5b1e0c9a-7d2f-4b8e-9c31-0a6f2e4d8b17",
  "code": "actuators.short-cycling",
  "severity": "warning",
  "status": "open",
  "detectedAt": "2026-11-08T09:58:00Z",
  "component": "compressor",
  "summary": "Compressor short cycling",
  "explanation": "The compressor is starting and stopping too often (12 times in the last hour). Cooling may be weak. Your installer has been told.",
  "cause": {
    "code": "sensors.drift",
    "component": "room-sensor",
    "text": "The room sensor reads 3 °C higher than the return-air sensor.",
    "confidence": "medium"
  },
  "evidence": [4012, 4013, 4019]
}

What is seen, and why. One problem often causes another. In the example, the compressor problem (code) is caused by a sensor problem (cause.code). Both come from the same list of fault codes. This is how a HEART tells you not only "something is wrong", but "this is the real reason".

An alert moves through these states:

open ──► acknowledged ──► tending ──► resolved
  │            │             │           ▲
  │            ▼             │           │
  └──────► escalated ◄───────┘           │
               └─────────────────────────┘

Any state may also move straight to resolved when the problem goes away by itself. acknowledged is reached through POST /arrhythmias/{id}/acknowledge. An escalated alert is resolved by the person it was handed to, or by the HEART once the problem is gone.

3.5 Capability: what you can ask me to do#

A capability is something the system can be asked to do. Its boxes are a superset of an MCP tool, so any capability can also be offered to AI assistants as an MCP tool without changes.

{
  "name": "calibrate",
  "title": "Calibrate a sensor",
  "description": "Recalibrates one temperature sensor against the reference sensor. Takes about 2 minutes.",
  "inputSchema": { "type": "object", "required": ["sensor"], "properties": { "sensor": { "type": "string" } } },
  "risk": "write",
  "physical": false,
  "reversible": true,
  "idempotent": true,
  "privacy": "internal",
  "callers": ["human", "rule", "ai"],
  "kind": "standard"
}

3.6 Action: what I am doing#

When anyone asks for a capability, the system creates an Action. The Action records the whole story: who asked, who approved, what happened.

awaiting-approval ──► approved ──► running ──► succeeded
        │                │            │     └─► failed
        ├──► denied      │            └──► cancelling ──► cancelled
        ├──► expired     └──► refused
        └──► cancelled

denied: a person said no. refused: the system said no (a guard, a precondition or the autonomy mode). cancelling: a cancel takes effect at the next safe point; see API Standard 6.3, rule 5.

An Action that needs no approval starts at running. The rules for who must approve what are in Part 6.

3.7 Receipt: what data I sent#

Whenever non-public data leaves the system, to an AI provider, a Gateway or another system, the HEART writes a Receipt. It records who received the data, why, how private it was, how many bytes were sent, and a salted commitment to exactly what was sent: SHA-256 over a fresh random salt followed by the payload. The salt goes to the recipient, never into the Receipt, so nobody can guess short values back from it. A Receipt never contains the data itself.

Part 5 explains Receipts fully.

4. Shared word lists#

Many boxes accept only words from a fixed list. That is what lets a program understand any HEART without guessing.

The four statuses mean exactly this:

5. Fault codes#

5.1 Why fault codes#

A message like "error 0x3F" means nothing outside one company. A message like "something is wrong" means nothing to a program. A fault code fixes both. It is a short, readable name for one specific problem, with one fixed meaning on every product.

A building dashboard watching 500 different devices can then count every storage.full across all of them, without knowing any of the brands.

HEART fault codes are words, not numbers. sensors.drift is easier to read and remember than S0402, and still easy for programs. For a small screen, a blinking light or a phone call, each standard code also has a short fixed number, its H-number, such as H-08005 for sensors.drift (Section 5.7). The name stays the main form.

5.2 How a code is built#

A fault code has two parts, separated by a dot:

     sensors . drift
     ───┬───   ──┬──
      area    problem

The area is where the problem is. The areas are the same as in Part 2, plus system for the whole system:

The number is the first part of the H-number of every code in that area (Section 5.7). A new area takes the next free number, 12 to 99.

The problem is one or more lower-case words joined by hyphens, such as nearly-full.

5.3 Three kinds of code#

Rules:

1. A system MUST use a standard code when one fits.
2. If none fits, it SHOULD use a profile code, and only then a product code.
3. Product codes MUST start with a domain the maker owns, so two makers never clash.
4. A product code SHOULD be described in the Card's events, with a sentence saying what it means.
5. Only standard codes have an H-number (Section 5.7). Profile and product codes have none: they are always written by name.

5.4 The standard fault codes#

This is the starting list. It will grow through the registry process (Section 11). Each code has its H-number beside it (Section 5.7). These codes are all faults: things that are wrong. Things that simply happen, such as a start or a restart, are event types (Section 5.8).

A page for each code, with its likely causes, how to fix or prevent it, and what a HEART does by itself, is at https://heartcortex.ai/faults/<code>, such as /faults/storage.full. The same facts are in one machine-readable file, fault-codes/1.0/fault-codes.json, checked against the tables below by tools/validate.py.

system: the whole system

power

connectivity

storage

performance

software

ai

sensors

actuators

data

security

5.5 The older kind box#

Before fault codes, alerts had a kind: one of 11 broad types. To keep existing software working, a system SHOULD send both code and kind during the change-over, when an old kind fits:

kind will be removed in version 2.0.

5.6 Writing a code outside messages#

Inside a message, a code is written bare:

"code": "storage.full"

Outside messages, in logs, tickets, documents, screens and searches, it is written with HEART and a space in front: HEART storage.full. The word tells a reader, or a search engine, which list the code comes from. The same holds for profile and product codes, such as HEART hvac.refrigerant-low.

A program reading a message MUST NOT expect the prefix. A program writing a message MUST NOT add it.

5.7 H-numbers#

Each standard fault code has a short number for places where a name does not fit: a two-digit display, a blinking light, a code read out over the phone. It is written H-AACCC:

So H-04002 is storage.full, and H-01001 is system.main-function-lost.

Rules:

1. An H-number is fixed for ever. It is never changed, never reused, and never given to another code, even if its code is deprecated.
2. A new code takes the next free number in its area. A new area takes the next free area number.
3. Only standard codes have H-numbers. Profile codes, product codes and event types have none.
4. The name is the main form. Messages carry the name, never the H-number. A screen, label or manual MAY show the H-number beside the name, or alone where the name does not fit.
5. A person can look up any H-number at https://heartcortex.ai/system-code/H-AACCC, such as /system-code/H-04002. A part of a number, such as H-04, lists every code that starts with it.

5.8 Event types: not fault codes#

An event type names something that happened: the system started, a part was restarted, a message arrived. It is the name of a Rhythm event (Section 3.3). It is not a fault, and MUST NOT be used as an alert's code or cause.code.

Event types look like fault codes, area.name, but they are a separate list. They have no H-number. When an event shows that something is wrong, the HEART raises an alert with a fault code. For example, a component.failed event three times in 30 seconds may raise connectivity.dependency-unreachable, and a restart nobody asked for raises system.unexpected-restart beside the system.started event.

These standard event types are defined so far. Each has the category of its prefix (Section 3.3).

More event types are added through the registry (Section 11).

6. Standard action names#

If a product offers one of these actions, it SHOULD use the name given here. Then one command, such as "restart that", works across a whole building or fleet of different products.

halt stops a machine or one of its parts. It is not the HEART's Stop, which stops only automatic action and leaves the machine as it is (Part 6, Section 6).

Product profiles (Part 8) add names for their own kind of product.

7. Feature Sets: how much a system must say#

A Feature Set says how much of the information model a system offers. There are three. Each includes everything in the one before it.

The full Card means the Card served at the caller's clearance (GET /heart/v1/card), and not only its public view (Part 4). | Full | Capabilities and Actions with approval, the stop control, AI model tracking, AI reasoning in the standard format | Systems that fix themselves or act on request |

A system states its Feature Set in its Card. If something is asked for that is above its Feature Set, it MUST answer "not implemented" (Part 4 says how).

Every Feature Set, even Basic, MUST also meet Autonomy Level A1 (Part 2). A system that only reports, without noticing problems and telling someone, is not a HEART.

Feature Sets and Autonomy Levels are different scales. The Feature Set says how much you can ask. The Autonomy Level says how much it does on its own. See Part 1, Section 5.6.

8. Modules: optional extras#

Feature Sets stay small, so a tiny sensor can take part. Everything else is an optional module. A system lists its modules in the Card's modules. It MUST offer all of a module, or none of it.

Two of the most useful module messages:

• Component (inventory): one part of the system, with an id, a kind (Section 4), its own status, and optionally its parent, version, maker and what it depends on.
• Property (properties): one value, with its name, value, unit (UCUM), whether it is writable, a quality of good, uncertain or bad (the three severities of OPC UA's StatusCode), the time it was measured, and its privacy level. The value takes the level given in privacy; this is the only box whose level is set per message (its schema marks it dynamic).

9. Naming rules#

Names are how systems find each other and avoid clashes. These rules keep them unique and readable.

Using a reversed domain name works the way Java packages and Android apps do. Only the owner of coolair.com can create names starting com.coolair, so names never clash.

10. Rules for change#

Products will mix HEART versions for years. These rules make sure old and new keep understanding each other.

1. Ignore what you don't know. A consumer MUST ignore boxes it does not recognise. It MUST NOT fail.
2. Missing means "not available to you". A missing box never means zero, false or empty. It may have been filtered out for privacy.
3. Versions 1.x only add. A minor version may add boxes, words and codes. It MUST NOT remove anything or change what something means. Removing or changing needs version 2.0.
4. Codes are forever. A fault code, its H-number, an action name or an event type, once published, never changes meaning and is never reused. It can only be marked deprecated (no longer recommended).
5. Extras go in ext. A product's own extra boxes go inside ext, under the maker's reversed domain name, so they never clash with future standard boxes. They are private unless the Card says otherwise.

"ext": { "com.coolair": { "filterHours": 412 } }

11. Registries: the shared lists#

A registry is an official, shared list that everyone uses, such as the list of country codes or of internet port numbers. HEART keeps these registries:

How to add an entry#

Anyone may propose an entry. A proposal gives:

1. the name,
2. one sentence saying exactly what it means,
3. an example from a real product,
4. why no existing entry fits.

An entry is accepted when it is clear, does not overlap an existing entry, and is likely to be useful to more than one maker. Until HEART has a neutral home (see the Standards Family), the editor of this standard keeps the registries in this repository.

12. Carrying the model in other standards#

The model in this part is the meaning. Part 4 defines the main ways to carry it: HTTP and JSON, MQTT, local sockets and in-process use.

Other carriers can be added later without changing the model, as long as they follow one rule:

Same boxes, same meanings, same privacy. Any carrier MUST keep every box with the meaning given here, and MUST apply the Valve's filtering (Part 5) before anything leaves the system.

Planned carriers:

Each needs work with the group that owns that standard.

13. Changes needed in other files#

14. Open items#