> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/data/clinical-data-contracts.md).

# Reusable Clinical Data

Define reusable clinical inputs with explicit meaning, units, time, provenance, and validation so workflows can share calculations across source systems.

A clinical workflow is easier to reuse when its calculations depend on agreed inputs rather than each customer's field names and units. A weight reported in grams and one reported in kilograms can support the same calculation after a tested conversion. A missing unit, an old measurement, or a patient report still needs its own treatment.

A **clinical data contract** is the team's agreement about those inputs and their meaning. It connects the [world model's source evidence](https://docs.concurrence.com/data/world-model.md) to a particular workflow. The implementation team owns the mappings and validation; clinical owners approve the definitions and how the results are used.

## Separate Connection, Meaning, and Decision

<figure><img src="https://3635224444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvcLyiHRcwv7g83p6vxAd%2Fuploads%2Fgit-blob-a7ab15f73c66d3e860b31538fcf1e03fd16d5d62%2Fclinical-data-contract.svg?alt=media" alt="Source-specific mappings produce agreed clinical inputs with retained provenance. A reusable calculation consumes those inputs, and a separately governed workflow decides how to use the result."><figcaption><p>This is an implementation pattern. Each mapping, calculation, and action needs its own validation.</p></figcaption></figure>

| Layer                  | Question it answers                          | Example                                                                    |
| ---------------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
| Connection             | How does authorized data reach the workflow? | FHIR import, dataset intake, or an integration lookup                      |
| Structural mapping     | Which source field represents the input?     | A source weight field becomes the agreed weight input                      |
| Semantic normalization | What does the value mean?                    | Preserve the original unit and convert a recognized mass unit to kilograms |
| Calculation            | Which defined operation uses the inputs?     | Compute BMI from an eligible weight and height pair                        |
| Workflow policy        | What action is appropriate?                  | Apply the organization's reviewed eligibility and escalation rules         |

FHIR supplies resource structures for exchange. Receiving a FHIR Observation or using the same field name does not by itself establish compatible units, equivalent measurement methods, or suitability for a calculation. Define those requirements explicitly.

Use supported resource fields when they fit. [Registered enrichment keys](https://docs.concurrence.com/data/world-model.md#entity-enrichment) can hold additional workflow attributes, but a key name and value type do not define a clinical measure. Keep repeated measurements with their dates and source references rather than reducing a longitudinal requirement to one current value.

## Define the Inputs Before the Rule

Start with one workflow and the smallest set of inputs it needs. Record the following alongside its mappings and tests:

| Requirement          | What to specify                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Meaning and identity | Measure or clinical concept, coding system where applicable, subject, source-scoped identifier, and relevant encounter |
| Representation       | Value type, accepted units or codes, target unit, precision, and conversion rules                                      |
| Time                 | Measurement or effective time, timezone or date precision, acceptable age, and receipt time when available             |
| Evidence             | Source record, original value and unit, measured versus reported versus derived, and correction links where supported  |
| Usability            | Required inputs, supported ranges, missingness, incompatible methods, and handling of unresolved disagreements         |
| Derivation           | Mapping and calculation versions, selected input references, evaluation time, and output meaning                       |

Keep an unknown value distinct from zero, a negative finding, and a value the reader cannot access. An inferred unit or model-derived interpretation needs its own provenance and validation. Do not silently convert an unknown unit into a measured fact.

## Define Freshness for the Decision <a href="#freshness-for-the-decision" id="freshness-for-the-decision"></a>

Freshness has several meanings. Define which one the workflow needs and how it obtains the supporting evidence.

<figure><img src="https://3635224444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvcLyiHRcwv7g83p6vxAd%2Fuploads%2Fgit-blob-90a22ec9a3ef9ceb8f6734e43fcdec96ce73c1f3%2Fdata-freshness-questions.svg?alt=media" alt="Evaluate three separate questions: when the measurement happened, when the source copy was current, and whether the intended consumer can read the value. Record receipt time separately. These are requirements for an implementation&#x27;s evidence, not a universal API response shape."><figcaption><p>Use the timestamps and read evidence available to the selected integration. Treat missing evidence as unknown.</p></figcaption></figure>

**Clinical age** uses measurement or effective time. A height measured a year ago remains a year-old measurement when its record is uploaded today. The clinical owner defines whether it is eligible for the calculation.

**Source freshness** concerns the state the source supplies. When reading a reporting copy, preserve its refresh time when available. The time a query runs does not establish when that copy was current in the authoritative system. If a decision needs a current value, use an authorized lookup that can supply the required evidence or route the uncertainty for review.

**Reader visibility** concerns the selected consumer. Check that it can retrieve the intended record and value after processing or projection. Record receipt time separately to investigate transport and processing; receipt alone does not establish clinical age, source freshness, or visibility.

These are recommended input-contract requirements. Keep the evidence with the workflow even when it comes from several interfaces. For end-to-end evaluation, see [Design for Measured Freshness](https://docs.concurrence.com/data/healthcare-interoperability.md#design-for-measured-freshness).

## Worked Example: A BMI Input Contract

The following synthetic example checks arithmetic and mapping. It defines no screening threshold or clinical recommendation. The workflow's clinical owner determines which measurements are eligible, how closely their times must align, and whether BMI is appropriate for the intended population and use.

For eligible measurements, calculate `BMI = weight_kg / (height_m × height_m)`. Keep the unrounded result for subsequent calculations and apply the agreed rounding only for presentation.

| Synthetic source record                  | Mapping                                | Result                                                         |
| ---------------------------------------- | -------------------------------------- | -------------------------------------------------------------- |
| Weight 70 kg and height 175 cm           | Keep weight and divide height by 100   | 70 kg and 1.75 m, with BMI displayed as 22.86 kg/m²            |
| Weight 70,000 g and height 1.75 m        | Divide weight by 1,000 and keep height | The same normalized inputs and displayed BMI                   |
| Weight 70 with no unit and height 175 cm | Weight unit is unresolved              | Withhold the calculation and obtain or review the missing unit |
| Weight 70 kg and height 0 m              | Height is invalid for this calculation | Reject the input pair and request a corrected measurement      |

Treat the first two rows as alternative representations of the same synthetic case, not two independent observations. Retain their source identifiers so duplicate deliveries do not add weight to an aggregate.

A source-reported BMI and a BMI calculated from weight and height are also distinct observations. Keep the calculation's input references and version, and define how the workflow selects between eligible results. A numerically matching answer does not prove that the measurements or patient association are correct.

### A Yearly Average Needs a Different Contract

Converting one known unit is a per-record operation. An average over a year requires a selected history and an evaluation point. Specify:

1. The anchor date, window boundaries, timezone, and whether the window uses measurement time or another explicitly defined time.
2. Which observations qualify, including source, measurement method, age, and subject association.
3. How duplicates, corrections, missing units, and weight/height pairing are handled.
4. Whether the result is an arithmetic mean of eligible BMI observations or a time-weighted measure, and the minimum coverage required.
5. How a late or corrected record affects a recomputed result and any pending workflow that used it.

Compute each eligible BMI from its selected input pair before taking an arithmetic mean. Averaging the weights and heights first can produce a different result. Report observation count, covered period, and evaluation time with the result. An average from one observation does not establish a year's coverage.

See [Time and Corrections](https://docs.concurrence.com/data/world-model.md#time-and-corrections) for the difference between a clinical event's time and when a consumer learns about it.

## Preserve a Derivation Trail

For a calculated result, retain enough evidence to trace the output to its selected inputs: source record references, original values and units, mapping and calculation versions, and evaluation time. Keep this with the implementation's evidence package using the storage and interfaces selected for that workflow.

Entity provenance identifies contributing sources. Explaining how several fields produce one output also requires the transformation's own evidence. A source identifier alone cannot explain a unit conversion or an aggregation window.

## Validate, Then Reuse

Use the same contract tests against each source mapping. Equivalent valid inputs should produce equivalent normalized values. Missing units, ambiguous identities, and invalid inputs should reach the specified recovery path. Test late records and corrections against the temporal definition as well as the arithmetic.

[Platform functions](https://docs.concurrence.com/agent/platform-functions.md) and workspace queries can expose reviewed calculations through supported tool interfaces. Keep source mapping and exact arithmetic in tested code or queries, and use agent guidance to explain results and follow the approved workflow. Registering a function does not establish clinical validation.

Continue with [Connect Data to a Verified Action](https://docs.concurrence.com/developer-guide/guides/data-to-verified-action) to verify source data, agent access, and the target outcome. Use [Connect Another Workflow](https://docs.concurrence.com/data/connect-another-workflow.md#package-the-reusable-parts) to carry the contract, configuration, and tests into the next implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/data/clinical-data-contracts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
