Tiro.health Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Provenance

Data Provenance Tracking

Overview

Atticus uses FHIR Provenance resources to track the origin and lifecycle of every field populated in a QuestionnaireResponse. This enables full auditability — whether a value was entered manually, extracted by AI, computed by a FHIRPath expression, or loaded from a preset.

​Each populated field receives its own FormProvenance resource. These are returned as repeated parameter[name="provenance"] entries alongside the QuestionnaireResponse in the $populate response.

How Provenance Is Linked to a Field

Each Provenance targets the enclosing QuestionnaireResponse and identifies the specific populated item via the standard targetElement extension:

Provenance.target[0].reference = "#"                        ← the QuestionnaireResponse
Provenance.target[0].extension[targetElement].valueUri      ← QuestionnaireResponse.item.id (a UUID)

Note: targetElement carries the item's id (a server-assigned UUID), not its linkId.

Activity Codes

Every Provenance carries at least one FormActivity code in activity.coding plus an optional ISO 21089 lifecycle code. For activities that have a specific child code, the backend also includes the parent code (e.g. definition + data-import).

User Input

Static Values

Calculations

AI-Powered

Data Import

ISO 21089 Lifecycle

Agents

All automated Atticus engines use provenance-participant-type#assembler as the agent type and a Device resource as agent.who. Source document authors (for AI clipboard) use provenance-participant-type#author.

Note: The backend uses integer Device IDs Device/1–Device/5; the IG uses descriptive IDs for readability.

The legacy AgentTypes CodeSystem (fhirpath-engine, population-engine, etc.) is retired. Existing persisted Provenance resources may still reference those codes.

AI Reasoning — ProvenanceWhy and activity.text

For AI-populated fields, the model's reasoning can be recorded in two places:

• activity.text: Plain-string reasoning. This is what the backend currently populates.
• extension[why] (ProvenanceWhy): Markdown reasoning — a pre-adoption of the R6 Provenance.why element. This is the intended location going forward.

AI Clipboard: Source Highlighting

When contextual-populate extracts a value from a clinical document, the Provenance includes an entity pointing to the source DocumentReference. The html-element-id extension on entity.what carries the IDs of the labeled HTML spans that contained the extracted text — enabling the UI to highlight the source passage:

Provenance.entity[0].role = "source"
Provenance.entity[0].what.reference = "DocumentReference/{id}"
Provenance.entity[0].what.extension[html-element-id][0].valueString = "label-001"
Provenance.entity[0].what.extension[html-element-id][1].valueString = "label-002"

The $populate Response Shape

​The $populate response is a Parameters resource with one entry per populated field:

Parameters
├─ parameter[name="response"].resource     → QuestionnaireResponse
├─ parameter[name="issues"].resource       → OperationOutcome (optional)
└─ parameter[name="provenance"].resource   → FormProvenance  ← repeated, one per field
   └─ parameter[name="provenance"].resource → FormProvenance
   ...

Contextual-Populate Flow

contextual-populate mode accepts clinical documents as context and drives the full AI pipeline:

1. Request supplies context[name="clinical-artifacts"] with one or more DocumentReference resources (HTML or PDF attachments).
2. The AI marking pipeline processes up to 5 documents in parallel: labels HTML spans, identifies which spans correspond to each questionnaire item, and extracts answer values.
3. Each extracted value gets a FormProvenance with:
   • activity.coding = ai-clipboard + data-import
   • agent.who = Device/atticus-ai-population-engine
   • entity.what.reference = the source DocumentReference
   • entity.what.extension[html-element-id] = span IDs for source highlighting
   • activity.text (and/or extension[why]) = the model's reasoning

Examples

User Input

{
  "resourceType" : "Provenance",
  "id" : "prov-001",
  "meta" : {
    "profile" : [
      🔗 "http://fhir.tiro.health/StructureDefinition/form-provenance"
    ]
  },
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: Provenance prov-001</b></p><a name=\"prov-001\"> </a><a name=\"hcprov-001\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-form-provenance.html\">Form Provenance</a></p></div><p>Provenance for <a href=\"QuestionnaireResponse-qr-123.html\">Response to Questionnaire 'http://fhir.tiro.health/Questionnaire/example' about 'Unspecified Subject'</a></p><p>Summary</p><table class=\"grid\"><tr><td>Recorded</td><td>2025-10-29 10:30:00+0000</td></tr><tr><td>Activity</td><td><span title=\"Codes:{http://fhir.tiro.health/CodeSystem/form-activity user}, {http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle originate}\">Manually entered data by the user</span></td></tr></table><p><b>Agents</b></p><table class=\"grid\"><tr><td><b>who</b></td></tr><tr><td><a href=\"Practitioner-pract-789.html\">Practitioner Dr. Example</a></td></tr></table></div>"
  },
  "target" : [
    {
      🔗 "extension" : [
        {
          "url" : "http://hl7.org/fhir/StructureDefinition/targetElement",
          "valueUri" : "item-456"
        }
      ],
      "reference" : "QuestionnaireResponse/qr-123"
    }
  ],
  "recorded" : "2025-10-29T10:30:00Z",
  "activity" : {
    "coding" : [
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "user",
        "display" : "User input"
      },
      {
        "system" : "http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle",
        "code" : "originate",
        "display" : "Originate/Retain Record Lifecycle Event"
      }
    ],
    "text" : "Manually entered data by the user"
  },
  "agent" : [
    {
      "who" : {
        🔗 "reference" : "Practitioner/pract-789"
      }
    }
  ]
}

AI Clipboard Population

{
  "resourceType" : "Provenance",
  "id" : "prov-002",
  "meta" : {
    "profile" : [
      🔗 "http://fhir.tiro.health/StructureDefinition/form-provenance"
    ]
  },
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: Provenance prov-002</b></p><a name=\"prov-002\"> </a><a name=\"hcprov-002\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-form-provenance.html\">Form Provenance</a></p></div><p>Provenance for <a href=\"QuestionnaireResponse-qr-123.html\">Response to Questionnaire 'http://fhir.tiro.health/Questionnaire/example' about 'Unspecified Subject'</a></p><p>Summary</p><table class=\"grid\"><tr><td>Recorded</td><td>2025-10-29 10:32:00+0000</td></tr><tr><td>Activity</td><td><span title=\"Codes:{http://fhir.tiro.health/CodeSystem/form-activity ai-clipboard}, {http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle originate}\">CT toont massa van 4.2cm in rechter bovenkwab met thoraxwandinvasie → cT3 (AJCC 8th)</span></td></tr></table><p><b>Agents</b></p><table class=\"grid\"><tr><td><b>Type</b></td><td><b>who</b></td></tr><tr><td><span title=\"Codes:{http://terminology.hl7.org/CodeSystem/provenance-participant-type assembler}\">Assembler</span></td><td><a href=\"Device-atticus-ai-population-engine.html\">Device: displayName = Atticus AI Population Engine</a></td></tr></table></div>"
  },
  "extension" : [
    {
      "url" : "http://fhir.tiro.health/StructureDefinition/provenance-why",
      "valueMarkdown" : "The clinical note states: \"CT thorax toont een massa van 4.2cm in de rechter bovenkwab met invasie van de thoraxwand.\"\nThis indicates a tumor >4cm with chest wall invasion, corresponding to cT3 per AJCC 8th edition staging criteria."
    }
  ],
  "target" : [
    {
      🔗 "extension" : [
        {
          "url" : "http://hl7.org/fhir/StructureDefinition/targetElement",
          "valueUri" : "item-789"
        }
      ],
      "reference" : "QuestionnaireResponse/qr-123"
    }
  ],
  "recorded" : "2025-10-29T10:32:00Z",
  "activity" : {
    "coding" : [
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "ai-clipboard",
        "display" : "AI Clipboard"
      },
      {
        "system" : "http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle",
        "code" : "originate",
        "display" : "Originate/Retain Record Lifecycle Event"
      }
    ],
    "text" : "CT toont massa van 4.2cm in rechter bovenkwab met thoraxwandinvasie → cT3 (AJCC 8th)"
  },
  "agent" : [
    {
      "type" : {
        "coding" : [
          {
            "system" : "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code" : "assembler",
            "display" : "Assembler"
          }
        ]
      },
      "who" : {
        🔗 "reference" : "Device/atticus-ai-population-engine"
      }
    }
  ],
  "entity" : [
    {
      "role" : "source",
      "what" : {
        🔗 "extension" : [
          {
            "url" : "http://fhir.tiro.health/StructureDefinition/html-element-id",
            "valueString" : "label-001"
          },
          {
            "url" : "http://fhir.tiro.health/StructureDefinition/html-element-id",
            "valueString" : "label-002"
          }
        ],
        "reference" : "DocumentReference/doc-001",
        "display" : "Referral letter from AZ Monica"
      }
    }
  ]
}

FHIRPath Calculation

{
  "resourceType" : "Provenance",
  "id" : "prov-003",
  "meta" : {
    "profile" : [
      🔗 "http://fhir.tiro.health/StructureDefinition/form-provenance"
    ]
  },
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: Provenance prov-003</b></p><a name=\"prov-003\"> </a><a name=\"hcprov-003\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-form-provenance.html\">Form Provenance</a></p></div><p>Provenance for <a href=\"QuestionnaireResponse-qr-123.html\">Response to Questionnaire 'http://fhir.tiro.health/Questionnaire/example' about 'Unspecified Subject'</a></p><p>Summary</p><table class=\"grid\"><tr><td>Recorded</td><td>2025-10-29 10:33:00+0000</td></tr><tr><td>Activity</td><td><span title=\"Codes:{http://fhir.tiro.health/CodeSystem/form-activity calculation}, {http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle originate}\">A value computed from a FHIRPath calculatedExpression</span></td></tr></table><p><b>Agents</b></p><table class=\"grid\"><tr><td><b>Type</b></td><td><b>who</b></td></tr><tr><td><span title=\"Codes:{http://terminology.hl7.org/CodeSystem/provenance-participant-type assembler}\">Assembler</span></td><td><a href=\"Device-atticus-fhirpath-engine.html\">Device: displayName = Atticus FHIRPath Engine</a></td></tr></table></div>"
  },
  "target" : [
    {
      🔗 "extension" : [
        {
          "url" : "http://hl7.org/fhir/StructureDefinition/targetElement",
          "valueUri" : "item-999"
        }
      ],
      "reference" : "QuestionnaireResponse/qr-123"
    }
  ],
  "recorded" : "2025-10-29T10:33:00Z",
  "activity" : {
    "coding" : [
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "calculation",
        "display" : "Calculation"
      },
      {
        "system" : "http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle",
        "code" : "originate",
        "display" : "Originate/Retain Record Lifecycle Event"
      }
    ],
    "text" : "A value computed from a FHIRPath calculatedExpression"
  },
  "agent" : [
    {
      "type" : {
        "coding" : [
          {
            "system" : "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code" : "assembler",
            "display" : "Assembler"
          }
        ]
      },
      "who" : {
        🔗 "reference" : "Device/atticus-fhirpath-engine"
      }
    }
  ]
}

Definition-Based Import

{
  "resourceType" : "Provenance",
  "id" : "prov-004",
  "meta" : {
    "profile" : [
      🔗 "http://fhir.tiro.health/StructureDefinition/form-provenance"
    ]
  },
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: Provenance prov-004</b></p><a name=\"prov-004\"> </a><a name=\"hcprov-004\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-form-provenance.html\">Form Provenance</a></p></div><p>Provenance for <a href=\"QuestionnaireResponse-qr-123.html\">Response to Questionnaire 'http://fhir.tiro.health/Questionnaire/example' about 'Unspecified Subject'</a></p><p>Summary</p><table class=\"grid\"><tr><td>Recorded</td><td>2025-10-29 10:34:00+0000</td></tr><tr><td>Activity</td><td><span title=\"Codes:{http://fhir.tiro.health/CodeSystem/form-activity definition}, {http://fhir.tiro.health/CodeSystem/form-activity data-import}, {http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle originate}\">Definition-based import</span></td></tr></table><p><b>Agents</b></p><table class=\"grid\"><tr><td><b>Type</b></td><td><b>who</b></td></tr><tr><td><span title=\"Codes:{http://terminology.hl7.org/CodeSystem/provenance-participant-type assembler}\">Assembler</span></td><td><a href=\"Device-atticus-population-engine.html\">Device: displayName = Atticus Population Engine</a></td></tr></table></div>"
  },
  "target" : [
    {
      🔗 "extension" : [
        {
          "url" : "http://hl7.org/fhir/StructureDefinition/targetElement",
          "valueUri" : "item-444"
        }
      ],
      "reference" : "QuestionnaireResponse/qr-123"
    }
  ],
  "recorded" : "2025-10-29T10:34:00Z",
  "activity" : {
    "coding" : [
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "definition",
        "display" : "Definition-based import"
      },
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "data-import",
        "display" : "Data Import"
      },
      {
        "system" : "http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle",
        "code" : "originate",
        "display" : "Originate/Retain Record Lifecycle Event"
      }
    ]
  },
  "agent" : [
    {
      "type" : {
        "coding" : [
          {
            "system" : "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code" : "assembler",
            "display" : "Assembler"
          }
        ]
      },
      "who" : {
        🔗 "reference" : "Device/atticus-population-engine"
      }
    }
  ],
  "entity" : [
    {
      "role" : "source",
      "what" : {
        "reference" : "Observation/obs-789",
        "display" : "Serum Creatinine Lab Result"
      }
    }
  ]
}

Preset Population

{
  "resourceType" : "Provenance",
  "id" : "prov-005",
  "meta" : {
    "profile" : [
      🔗 "http://fhir.tiro.health/StructureDefinition/form-provenance"
    ]
  },
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: Provenance prov-005</b></p><a name=\"prov-005\"> </a><a name=\"hcprov-005\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-form-provenance.html\">Form Provenance</a></p></div><p>Provenance for <a href=\"QuestionnaireResponse-qr-123.html\">Response to Questionnaire 'http://fhir.tiro.health/Questionnaire/example' about 'Unspecified Subject'</a></p><p>Summary</p><table class=\"grid\"><tr><td>Recorded</td><td>2025-10-29 10:35:00+0000</td></tr><tr><td>Activity</td><td><span title=\"Codes:{http://fhir.tiro.health/CodeSystem/form-activity preset}, {http://fhir.tiro.health/CodeSystem/form-activity static}, {http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle originate}\">Preset</span></td></tr></table><p><b>Agents</b></p><table class=\"grid\"><tr><td><b>Type</b></td><td><b>who</b></td></tr><tr><td><span title=\"Codes:{http://terminology.hl7.org/CodeSystem/provenance-participant-type assembler}\">Assembler</span></td><td><a href=\"Device-atticus-preset-engine.html\">Device: displayName = Atticus Preset Engine</a></td></tr></table></div>"
  },
  "target" : [
    {
      🔗 "extension" : [
        {
          "url" : "http://hl7.org/fhir/StructureDefinition/targetElement",
          "valueUri" : "item-555"
        }
      ],
      "reference" : "QuestionnaireResponse/qr-123"
    }
  ],
  "recorded" : "2025-10-29T10:35:00Z",
  "activity" : {
    "coding" : [
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "preset",
        "display" : "Preset"
      },
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "static",
        "display" : "Static value"
      },
      {
        "system" : "http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle",
        "code" : "originate",
        "display" : "Originate/Retain Record Lifecycle Event"
      }
    ]
  },
  "agent" : [
    {
      "type" : {
        "coding" : [
          {
            "system" : "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code" : "assembler",
            "display" : "Assembler"
          }
        ]
      },
      "who" : {
        🔗 "reference" : "Device/atticus-preset-engine"
      }
    }
  ],
  "entity" : [
    {
      "role" : "source",
      "what" : {
        "reference" : "Basic/preset-mri-protocol",
        "display" : "MRI Protocol Preset"
      }
    }
  ]
}

Related Resources

• FormProvenance profile
• FormActivity CodeSystem
• ​$populate OperationDefinition
• ProvenanceWhy extension
• HtmlElementId extension
• ISO 21089 Lifecycle CodeSystem
• FHIR Provenance Resource