Reportable Fields: the Nexus Field CodeSystem¶
A report asks the same question of every chart: which patients have this, and what is its value.
To ask it, a report needs a name for "this" that does not change when a screen is relabelled, and
a precise statement of where the answer is stored. The
Nexus Field CodeSystem (nexus-field) is that list of
names. Each concept is one reportable field: a code that never changes, a label in English and
French, the FHIR element that holds the value, and the conditions under which a resource counts.
This page explains how the code system is organised, what each property means, how a field is evaluated against a patient's record, what is generated from it, and which questions it answers today. It is written for report authors, for teams building a report builder or a query engine on this specification, and for app partners who want to ask the same questions of the same data.
Draft
nexus-field and its two grouping systems are draft. Codes are permanent (see
Lifecycle), but properties can still be added, and the French and the identifier
classification are first passes.
What it is¶
One concept per reportable field¶
A concept in nexus-field names one fact a report can filter on or return: a patient's date of
birth, a problem on the problem list, the value of a lab result, the date a document was received.
The code is what a saved report or cohort stores, so the label can be improved without breaking
anything that was saved under it.
A code reads <category>.<field>, so it says where it belongs before it is looked up:
conditions.problem-diagnosis
| |
| +-- the field
+------------- the category it belongs to
A code identifies the field, not a FHIR element. Several fields can read the same element:
every lab result is Observation.value[x], and what tells them apart is the condition attached to
the field, not the path.
Most fields are about a patient. The directory category is the exception: it holds fields about
practitioners, roles, locations and organisations, which no single patient owns.
Category, subcategory, field¶
Fields are grouped twice, and each grouping is its own published code system, so a picker can render the groups in either language without inventing labels.
flowchart TD
CAT["nexus-field-category<br/><b>conditions</b><br/>Problem List, Conditions and Procedures"]
SUB1["nexus-field-subcategory<br/><b>conditions.problems</b><br/>Problems and conditions"]
SUB2["nexus-field-subcategory<br/><b>conditions.procedures</b><br/>Procedures"]
F1["nexus-field<br/><b>conditions.problem-diagnosis</b><br/>Problem/diagnosis"]
F2["nexus-field<br/><b>conditions.clinical-status</b><br/>Clinical status"]
F3["nexus-field<br/><b>conditions.onset-date</b><br/>Onset date"]
F4["nexus-field<br/><b>conditions.procedure-date</b><br/>Procedure date"]
CAT --> SUB1
CAT --> SUB2
SUB1 --> F1
SUB1 --> F2
SUB1 --> F3
SUB2 --> F4
The hierarchy for one category. A field carries its category and subcategory as Coding
properties pointing into the two sibling code systems; a subcategory carries its category the same
way.
| Code system | What a concept is | What it carries |
|---|---|---|
Nexus Field Category (nexus-field-category) |
A top-level heading in a field picker | Full title, a fr-CA designation, and a short label for a rail or chip in both languages (short, shortFr) |
Nexus Field Subcategory (nexus-field-subcategory) |
A group inside a heading; codes read <category>.<subcategory> |
Title, fr-CA designation, and its category |
Nexus Field (nexus-field) |
One reportable field | Everything in What a concept says |
Reporting Picker Id (legacy) (nexus-reporting-picker-id) |
A field id an earlier report builder shipped with | Frozen; see Legacy picker ids |
A field belongs to exactly one category and exactly one subcategory.
How a field relates to the profiles¶
A field names an element on a profile, and the profile is the authority on what that element is. The concept states where to look and how to choose; the profile states what is found there.
flowchart LR
subgraph CS["nexus-field concept"]
C1["code: conditions.problem-diagnosis"]
C2["fhirPath: Condition.code"]
C3["gate: problem-list-item, active"]
end
subgraph SD["Condition profile, compiled"]
E1["Condition.code"]
E2["type: CodeableConcept"]
E3["cardinality: 1..1"]
E4["binding, short text"]
end
C2 -- "names" --> E1
E1 --- E2
E1 --- E3
E1 --- E4
The concept names Condition.code on the
Condition profile; the type,
cardinality and binding are read from that element, not repeated on the concept.
So the English description of a field is the concept's own definition where it states one, and otherwise the element's short text; its pickable values are the element's bound value set, and its data type is the element's type. Where a fact is stored is a modelling decision the profiles make once; Where a Fact Is Stored lists the rules for facts with more than one plausible home, and the fields read exactly those elements.
What a concept says¶
Every property below is declared on the code system and shown as a column of its
concept table. Some are always stated on the concept. Others are
derived: when the reporting outputs are generated, they are read from the compiled profile at
fhirPath, and a concept states one only to narrow or override the profile. The build refuses a
concept that states a value equal to the one the profile gives, so a stated value always means
something.
flowchart LR
STATED["<b>Stated on the concept</b><br/>display, fr-CA designation<br/>category, subcategory, domain<br/>fhirPath, via, selector, gate<br/>permission, identifierClass<br/>status, replacedBy<br/>clinicalCode, clinicalCodeSystem<br/>derived, cqlExpression, derivedFrom<br/>catalogName, requirementText, searchAlias<br/>descriptionFr"]
DERIVED["<b>Derived from the profile at fhirPath</b><br/><i>stated only to narrow or override</i><br/>profile<br/>dataType<br/>cardinality<br/>repeats<br/>pickerType<br/>codeSystemUri<br/>expectedUnit<br/>defaultAggregation<br/>meaningWhenMissing (never stated)"]
GEN["generator"]
OUT["one complete record<br/>per field, in each<br/>generated output"]
STATED --> GEN
DERIVED --> GEN
GEN --> OUT
classDef derived stroke-dasharray: 6 4
class DERIVED derived
The property map. The solid box is stated on the concept. The dashed box is supplied by the
generator from the compiled profile (or, for repeats and defaultAggregation, from the resource
type and the data type), and appear on a concept only as an override. A field with no fhirPath
has no element to read, so it states every derived property it needs.
The tables follow the column groups on the code system page. "Source" says whether the value is stated on the concept or derived when the outputs are generated. Every example is a real concept.
Placement¶
| Property | Type | What it means | Example | Source |
|---|---|---|---|---|
category |
Coding | The top-level heading, a code in nexus-field-category |
conditions on conditions.problem-diagnosis |
Stated |
subcategory |
Coding | The group inside the heading, a code in nexus-field-subcategory |
conditions.problems |
Stated |
domain |
string | The chart-data catalogue domain the field was catalogued under; absent on directory fields |
6.1 on demographics.dob |
Stated |
pickerType |
string | The comparison family a report builder offers: string, coded, enum, boolean, date, number, reference, attachment |
number on demographics.age (stated: no fhirPath); enum on demographics.sex-at-birth (an override) |
Derived from the data type and binding |
defaultAggregation |
string | Which of a patient's values a criterion reads when it names no quantifier: one of any, latest, earliest or count. A string, not a code: none of the four is a concept of this system |
latest on orders-results.result-value (derived); any on appointments.appointment-date-time (stated, overriding the date default) |
Derived for a repeating field: latest for a date or a number, any otherwise; stated where that is wrong |
FHIR element¶
| Property | Type | What it means | Example | Source |
|---|---|---|---|---|
fhirPath |
string | The element the value is read from, rooted at the resource type. Absent where this specification models no home for the field yet | Patient.birthDate on demographics.dob |
Stated |
profile |
string | The profile canonical a retrieve carries, where the resource type has several profiles | https://fhir.apps.health/StructureDefinition/nexus-core-referral on referrals.referral-date-sent |
Derived where the type has one profile; stated where it has several |
via |
string | The reference to follow first, where the value is on a referenced resource; fhirPath then names the element on the target. A criterion on it is a join |
Patient.generalPractitioner on demographics.family-provider-phone, with fhirPath Practitioner.telecom |
Stated |
selector |
string, repeats | Which entry of a repeating element the field means. See Selectors | telecom.system=phone and telecom.use=mobile on demographics.cell-phone |
Stated |
gate |
string, repeats | A condition on the resource under which it counts for this field. See Gates | status=completed on prevention.date-given |
Stated |
dataType |
string | The FHIR type of the value | dateTime on prevention.date-given (derived); Quantity on vitals.bp-systolic (narrows value[x]) |
Derived; stated to narrow a choice or a reference, or where there is no fhirPath |
cardinality |
string | How often the element occurs on one resource, read from the resource root: 0..* wherever any element on the path repeats |
1..1 on conditions.problem-diagnosis (Condition.code) |
Derived; stated only with no fhirPath |
repeats |
boolean | Whether a patient can have more than one value, across resources or within one | true on every Condition field; stated true on demographics.cell-phone because Patient defaults to false |
Derived from the resource type; stated where the default is wrong |
cardinality and repeats answer different questions. Condition.code is 1..1: one per
Condition. But a patient has many Conditions, so conditions.problem-diagnosis repeats. A report
builder uses repeats to decide whether to offer "latest", "count of" and "any".
Access¶
| Property | Type | What it means | Example | Source |
|---|---|---|---|---|
permission |
string | The coarse permission class needed to read the field: clinical, administrative or operational |
administrative on demographics.dob; clinical on conditions.problem-diagnosis |
Stated |
identifierClass |
string | How strongly the field identifies a person: direct (alone), quasi (narrows a population and re-identifies in combination) or none |
direct on demographics.first-name; quasi on demographics.dob |
Stated |
Identifier class is a first pass
It was assigned by rule and classified up wherever the call was arguable. Use it to find candidates for masking in a de-identified export; do not rely on it as the control that masks them until it has had a privacy review.
Lifecycle¶
| Property | Type | What it means | Example | Source |
|---|---|---|---|---|
status |
code | active (the default, shown as absent) or deprecated |
deprecated on history.past-surgical-history-date |
Stated |
replacedBy |
code | The code that supersedes a deprecated one, so a stored report can be migrated rather than fail | conditions.procedure-date on history.past-surgical-history-date |
Stated |
A code is never deleted. Adding a code is routine; removing or renaming one would invalidate every saved report and cohort that carries it, and the build fails if a published code disappears. A field is retired by deprecating it and naming its replacement.
Coding¶
These are hidden by default on the code system page.
| Property | Type | What it means | Example | Source |
|---|---|---|---|---|
clinicalCode |
string | In words, what identifies the field within its resource where the path alone does not | LOINC 8480-6 Systolic blood pressure (mmHg) on vitals.bp-systolic |
Stated |
clinicalCodeSystem |
string | The human name of the code system the field's codes come from | SNOMED CT; ICD-11 MMS; ICD-10-CA; ICD-9 (OHIP diagnostic) on conditions.problem-diagnosis-code |
Stated |
codeSystemUri |
string | The canonical of that code system, where exactly one is named: the string a query has to match | http://loinc.org on vitals.bp-systolic |
Derived where the profile pins one system; stated where it does not |
expectedUnit |
string | The UCUM unit a numeric value is expected in. A threshold in another unit is refused rather than converted | mm[Hg] on vitals.bp-systolic; kg on vitals.weight |
Derived where the profile fixes the unit; stated where it does not |
clinicalCode is the sentence a reader understands. selector and gate are the same idea said
as data a query engine can compile; where a field has both, the data form is the one to execute.
Derivation¶
| Property | Type | What it means | Example | Source |
|---|---|---|---|---|
derived |
boolean | The value is computed rather than stored, so "as of when" is a real question | true on demographics.age |
Stated |
cqlExpression |
string | For a computed field, where its definition is published: <Library canonical>\|<version>#<expression> |
Carried once a computed field's definition is published as a CQL Library | Stated |
derivedFrom |
string | The catalogue entry this field was split out of, where one catalogued entry named several fields | problem/diagnosis on conditions.problem-text |
Stated |
Source and search¶
| Property | Type | What it means | Example | Source |
|---|---|---|---|---|
catalogName |
string | The chart-data catalogue's own words for the field, kept for traceability even where the label reads better | DOB on demographics.dob (label: Date of birth) |
Stated |
requirementText |
string | The words of the chart-data requirement the field came from, quoted exactly, so the concept can be linked to the sentence | DOB + age on demographics.age |
Stated |
searchAlias |
string, repeats | Another name a search box should match | DOB on demographics.dob; family doctor phone on demographics.family-provider-phone |
Stated |
searchAlias is deliberately not the standard synonym concept property: that one means an
alternative code for the concept, and these are search words.
French¶
| Property | Type | What it means | Example | Source |
|---|---|---|---|---|
| fr-CA designation | designation | The label in French | Date de naissance on demographics.dob |
Stated |
descriptionFr |
string | The description in French; the English description is the concept's definition, or the profile element's short text where the concept states none | La date de naissance du patient on demographics.dob |
Stated |
French is a first pass
The French has not had a linguistic review. A concept with no French designation carries none, rather than English labelled as French, so a missing translation stays visible.
Carried only in the generated outputs¶
| Property | What it means | Example | Source |
|---|---|---|---|
meaningWhenMissing |
What an absent value means, where the element on the resource itself declares one | demographics.patient-status reads Patient.active; base FHIR says absent means the record is in active use, so a criterion "is active" counts an absent value as true |
Derived from ElementDefinition.meaningWhenMissing on the resource's own element; a data type's (such as Period.end's "the period is ongoing") is not carried onto a field that reads it. Never stated on the concept |
Gates¶
A gate is a condition on the resource: it decides whether a resource is one this field is about at all. It is what separates a problem-list Condition from an encounter diagnosis, a sent referral from a draft, or a dose given from a dose refused, when both carry the same element of the same type. The path is rooted at the resource.
flowchart TD
G["gate string"] --> Q1{"contains #lt;, #lt;=, #gt; or #gt;=?"}
Q1 -- yes --> DATE["<b>date comparison</b><br/>path op YYYY, YYYY-MM, YYYY-MM-DD or $today<br/>on a date-typed element that does not repeat,<br/>compared at the precision the value is written in"]
Q1 -- no --> Q2{"value is $exists?"}
Q2 -- "path=$exists" --> EX["<b>present</b>: the element exists"]
Q2 -- "path!=$exists" --> NEX["<b>absent</b>: the element does not exist"]
Q2 -- no --> Q3{"operator"}
Q3 -- "path=v1 #124; v2" --> M["<b>match</b>: the element holds one of the values"]
Q3 -- "path!=v1 #124; v2" --> NM["<b>no match</b>: it holds none of them;<br/>an absent element holds none, so it passes"]
The four forms of a gate. | separates alternative values. Values match by containment at the
depth the path names.
| Form | Meaning | Example |
|---|---|---|
<path>=<value> |
The element holds the value; \| separates alternatives |
intent=proposal (a referral); clinicalStatus.coding.code=active\|recurrence\|relapse |
<path>!=<value> |
The element holds none of the values; an absent element passes | status!=revoked |
<path>=$exists / <path>!=$exists |
The element is present / absent | performer=$exists |
<path><op><date> |
A date comparison, op one of <, <=, >, >=, against YYYY, YYYY-MM, YYYY-MM-DD or $today (the day the query runs), compared at the precision the literal is written in; a stored date coarser than the literal is treated as earlier than every date it could be, so a stored 2020 holds for <2020-03-15 and not for >=2020-03-15 |
authoredOn>=2020-01-01; authoredOn<=2020 keeps every day of 2020 |
Three rules complete the grammar:
- Gates are conjunctive. A field with several gates counts a resource only when all of them hold.
- Positive matches on the same element name one entry.
category.coding.system=Xtogether withcategory.coding.code=Ymeans one coding carrying both, not one coding with the system and another with the code. This is how a short code is tied to its system: the requisition fields gate oncategory.coding.code=108252007|363679005withcategory.coding.system=http://snomed.info/sct, so the laboratory or imaging code counts only as a SNOMED CT code. - A resource marked entered-in-error fills no field. That is one rule over the resource type,
not a gate on each field. The elements it reads are found from the profile: every top-level code
or CodeableConcept element with a required binding to a value set containing
entered-in-error. That isstatusorverificationStatuson most resources, and alsoGoal.lifecycleStatusandDocumentReference.docStatus. A resource holding it on any of them is excluded before any gate is read.
The fields published today use the = form; the other forms are part of the grammar so a field can
use them without a change to any consumer.
Selectors¶
A selector chooses within a repeating element, where a gate qualifies the whole resource. It
reads <element>.<discriminator>=<value>, where <element> is a prefix of fhirPath.
flowchart LR
P["Patient.telecom"] --> T1["system: email<br/>use: home"]
P --> T2["system: phone<br/>use: home"]
P --> T3["system: phone<br/>use: mobile"]
S["demographics.cell-phone<br/>selector: telecom.system=phone<br/>selector: telecom.use=mobile"] -. "one entry satisfying both" .-> T3
Selectors on demographics.cell-phone: both conditions must hold on the same telecom entry, so
a home phone and a mobile email never combine into a match.
- Several selectors are conjunctive over one entry, as above.
|separates alternatives, in at most one of them. - An absent discriminator can mean a value. Where base FHIR defines what an absent
discriminator means, a selector naming that value also selects an entry that leaves it out. An
Observation.referenceRangewith notypeis the normal range, soorders-results.reference-range, selectorreferenceRange.type.coding.code=normal, selects a range typednormalwhere there is one, and otherwise a range with no type. Writers still state the type; see Where a Fact Is Stored. $nonesays theclinicalCodetext describes the field rather than choosing among entries, so the path alone is the field (orders-results.result-value: the test is identified byObservation.code, not by choosing withinvalue[x]).- No selector where one is needed means the field is not yet usable that way. A consumer must not assume the first entry is the right one; treat the field as unavailable rather than guess.
How a field is evaluated¶
Every field is evaluated the same way, from the patient's resources to one answer per patient.
flowchart TD
R["The patient's resources of the field's type<br/>(on the field's profile, where the type has several)"]
E["Drop any marked entered-in-error"]
G["Keep those where every gate holds"]
V["via: follow the reference to the target resource"]
S["selector: choose the entry within the repeating element"]
P["Read the value at fhirPath<br/>(absent: meaningWhenMissing says what it means, where stated)"]
A["Aggregate the patient's values: any, latest, earliest or count<br/>(defaultAggregation unless the criterion names one)"]
C["Compare with the criterion's operator and value<br/>(the unit must match expectedUnit where one is set)"]
OUT["True or false for this patient,<br/>or the value itself as an output column"]
R --> E --> G --> V --> S --> P --> A --> C --> OUT
classDef optional stroke-dasharray: 6 4
class V,S optional
The evaluation flow for one field and one patient. The dashed steps apply only to a field that
carries via or selector.
For conditions.problem-diagnosis that reads: take the patient's Conditions on the
Condition profile; drop any whose
verificationStatus
is entered-in-error; keep those whose
category
has a coding with system http://terminology.hl7.org/CodeSystem/condition-category and code
problem-list-item, and whose
clinicalStatus
is active, recurrence or relapse; read
Condition.code;
and since the field repeats and is coded, the default is any: the patient matches if any of
those codes matches.
From FSH to the outputs¶
The three code systems are hand-written in FHIR Shorthand. Nothing generates them, and they are the source of truth. Everything downstream is generated from them, joined with the compiled profiles.
flowchart TD
FSH["FSH, hand-written<br/>nexus-field, -category, -subcategory,<br/>nexus-reporting-picker-id and its ConceptMap"]
PFSH["FSH profiles"]
SUSHI["SUSHI compile"]
CS["Compiled CodeSystems"]
SD["Compiled profiles (snapshots)"]
SITE["This site and the IG package:<br/>CodeSystem and ConceptMap pages and JSON"]
GEN["Reporting generator: reads the profile at each fhirPath,<br/>supplies the derived properties,<br/>checks every path, gate and override"]
FC["Field catalogue: how to SHOW a field"]
RC["Reporting catalogue: how to RUN a criterion"]
PKG["TypedFhir package<br/>@awaremd/typed-fhir/reporting"]
MARTS["Marts: reporting tables"]
FSH --> SUSHI
PFSH --> SUSHI
SUSHI --> CS
SUSHI --> SD
CS --> SITE
CS --> GEN
SD --> GEN
GEN --> FC --> PKG
GEN --> RC --> MARTS
classDef out stroke-width:3px
class SITE,PKG out
The build pipeline. Thick boxes are published to partners; the reporting catalogue and the marts are built and used inside the Nexus EMR reporting service.
| Output | What it is for | What it carries | Where it is |
|---|---|---|---|
| The code systems | The published definition: what each field is and where it is stored | Exactly what the FSH states | The Nexus Field, Category and Subcategory pages, each linking its raw JSON, and the IG package (see IG metadata and Releases) |
| Field catalogue | What a field picker renders: groups, labels, comparison family, selectable values | Per field: code (the join key), label, group, type (the comparison family), single or multiple, definition, values or the bound value set, identifierClass, derived, search words, via, meaningWhenMissing, defaultAggregation, and the legacy ids that mean exactly this field; plus the operators per comparison family, in English and French |
FIELD_CATALOG from @awaremd/typed-fhir/reporting in the TypedFhir package |
| Reporting catalogue | What a query engine compiles a criterion against | Per field: the resource type and profile a retrieve binds to, path, compiled gates and selectors, data type, cardinality, whether it repeats, code system, expected unit, permission tag | Inside the Nexus EMR reporting service; not published |
| Marts | Relational reporting tables built from the reporting catalogue | One table per domain (mart_6_1 to mart_6_19) plus mart_directory for the directory fields, so a table can hold fields of several categories and rows of several resource types; one row per resource (keyed by resource type, id and row number), one or more columns per field (a Quantity as value and unit, a CodeableConcept as system, code and text, a reference as the referenced id). A resource marked entered-in-error has no row; a field with no fhirPath has no column. An extension is read at its canonical address and also at any older address its own description names while stored records migrate: billing.claim-date-of-service reads nexus-invoice-service-date and https://apps.health/InvoiceLineItem/service-date |
Inside the Nexus EMR reporting service; not published |
A partner who wants the same answers as the reporting service reads the code system and the
profiles, or the field catalogue, which carries the derived properties already resolved. Key every
stored criterion on the field code; the field catalogue's id exists only for the shape an
earlier picker used.
What the build checks, so a consumer does not have to:
- every
fhirPathlands on an element of the named profile, and every gate on an element of the resource; - a stated
dataTypeis one the element admits, and a narrowed reference names only targets the element admits; - a stated derived property differs from what the profile gives (a copy is refused);
- no published code has disappeared.
Questions it answers¶
Each example below names the fields, the gates they carry, the aggregation, and the shape of the answer. Codes in the examples (SNOMED CT, LOINC) are illustrations of what a report author would choose, not part of the field.
Patients with an active diabetes problem¶
flowchart TD
C["Condition"] --> EIE["not entered-in-error"]
EIE --> G1["gate: category = problem-list-item<br/>(system and code on one coding)"]
G1 --> G2["gate: clinicalStatus =<br/>active, recurrence or relapse"]
G2 --> V["value: Condition.code"]
V --> A["any: one matching code is enough"]
A --> R["criterion: code in a diabetes value set"]
R --> OUT["a set of patients"]
conditions.problem-diagnosis, end to end.
- Field:
conditions.problem-diagnosis(Condition.code, coded, repeats). - Gates: problem-list category and an active clinical status. Past medical history is the same
resource with an inactive, resolved or remission status, and is a different field,
history.past-medical-history. - Aggregation:
any. - Criterion: the code is in a set of diabetes codes, for example SNOMED CT 73211009 (Diabetes
mellitus) and its descendants. A problem list can be coded in more than one system
(
conditions.problem-diagnosis-codenames SNOMED CT, ICD-11, ICD-10-CA and the OHIP diagnostic codes), so the value set has to cover every system the clinic codes problems in. - Answer: a set of patients. As an output column, the matching codes.
Patients whose latest HbA1c is over 8%¶
flowchart TD
O["Observation"] --> EIE["not entered-in-error"]
EIE --> T["test-name: Observation.code<br/>has LOINC 4548-4"]
T --> V["result-value: Observation.value[x]<br/>(selector $none)"]
V --> L["latest, by the result's own date"]
L --> U["unit = % (result-unit)"]
U --> CMP["value #gt; 8"]
CMP --> OUT["patients, with the value and its date"]
Two fields read from the same Observation: the test that identifies it, and its value.
- Fields:
orders-results.test-name(Observation.code.coding:loinc) identifies the test;orders-results.result-value(Observation.value[x], selector$none) is the value, read on the Observation profile;orders-results.result-unit(Observation.valueQuantity.code, UCUM) is the unit. - Same resource. The test and the value have to be read from the same Observation. Two independent criteria ("has an HbA1c" and "has a result over 8") would match a patient whose HbA1c is normal and whose other result is over 8.
- Aggregation:
latestis the default forresult-value; the most recent HbA1c is the one compared. - Unit:
result-valueholds every test's value, so it has noexpectedUnit. A threshold has to be stated with its unit (%), and a result in another unit (for examplemmol/mol) is refused, not converted. - Answer: a set of patients; as output columns, the value, its unit, and the result's date.
Patients with a referral sent in the last 90 days¶
flowchart TD
SR["ServiceRequest<br/>(Referral profile)"] --> EIE["not entered-in-error"]
EIE --> G1["gate: intent = proposal"]
G1 --> G2["gate: status = active, on-hold,<br/>completed or revoked"]
G2 --> V["value: authoredOn"]
V --> L["latest"]
L --> CMP["on or after today minus 90 days"]
CMP --> OUT["a set of patients"]
V -. "not yet decided: authoredOn is the creation date" .-> CMP
referrals.referral-date-sent, with the open question marked.
- Field:
referrals.referral-date-sent, on the Referral profile (profileis stated, because ServiceRequest has more than one profile), readingServiceRequest.authoredOn. - Gates: a referral is a ServiceRequest with
intentproposal; a sent one has one of the statuses that follow sending. - Aggregation:
latest. - Not yet decided. The Referral profile defines
authoredOnas when the referral was created, and no element records when it was sent. Whether a referral is always a ServiceRequest, or may instead be a letter, a form or a scanned document, is also not settled, and this field reads the ServiceRequest only. Until both are decided, this question is answered by creation date on referrals that have since been sent. See Where a Fact Is Stored and Referrals. - Answer: a set of patients; as an output column, the date.
Documents received this month¶
flowchart TD
D["DocumentReference"] --> EIE["not entered-in-error"]
EIE --> G["gate: a category coding from<br/>document-category"]
G --> V["value: DocumentReference.date<br/>(when it was filed here)"]
V --> CMP["on or after the first of the month"]
CMP --> CNT["count, per patient"]
CNT --> OUT["patients with a count,<br/>or one row per document"]
documents.document-received-date, counting rather than taking the latest.
- Field:
documents.document-received-date, readingDocumentReference.date: when the document was filed to this chart. - Not the date on the document. That is
documents.document-date,content.attachment.creation. A letter dated last month and received today is received this month. - Gate: the
categorycarries a coding fromdocument-category, which every filed document has. Adddocuments.document-typeto narrow by kind. - Aggregation: the default is
latest; for "how many", namecount. - Answer: per patient, a count of documents; or, as a list, one row per document.
Vaccines given¶
flowchart TD
I["Immunization"] --> EIE["not entered-in-error"]
EIE --> G["gate on both fields: status = completed"]
G --> V1["vaccine-code: vaccineCode"]
G --> V2["date-given: occurrence[x]"]
V1 --> CMP["vaccine code in the chosen set"]
V2 --> W["date in the reporting window"]
CMP --> OUT["patients, doses or a count"]
W --> OUT
A dose given is a completed Immunization; both fields carry the gate.
- Fields:
prevention.vaccine-code(Immunization.vaccineCode) andprevention.date-given(occurrence[x]), on the Immunization profile. - Gates:
prevention.vaccine-code,prevention.vaccine-nameandprevention.date-givenare each gated onstatuscompleted, so a dose recorded asnot-donefills none of them.prevention.immunization-statusreads the status itself, coded in HL7 event-status through the immunization-status value set. - Codes: a vaccine is coded in the National Vaccine Catalogue or SNOMED CT Canadian Edition, or with the Nexus prevention catalog code; CVX appears only as received on an import.
- Why it was not given:
prevention.not-given-reason, gated onstatus=not-done. - Aggregation:
anyfor the code,latestfor the date; namecountfor doses per patient. - Answer: patients who received a vaccine, one row per dose, or a count of doses.
Active patients¶
- Field:
demographics.patient-status,Patient.active, boolean, does not repeat. - Missing values count. Base FHIR defines an absent
activeas a record in active use (the profile's comment repeats it), and the field carries that asmeaningWhenMissing. "Patient status is true" has to count patients with no value; a query that tests only fortruemisses every record converted without the element.
What it does not answer yet¶
A field is catalogued even where it cannot be evaluated yet, so a report builder can show it as unavailable instead of silently lacking it.
- No
fhirPath. A field with no path has no element in this specification to read: it is listed, typed and grouped, but nothing reads it and the marts have no column for it. Its definition says why where the reason is known: for examplebilling.claim-dx-code(the claim line's code is the fee code; the diagnosis travels on an extension this guide does not yet declare) andmedications.signed-date(no element records when a prescription was signed). A computed field (derived, for exampledemographics.age) has no path either; its definition is referenced throughcqlExpressiononce it is published. - Who entered or filed a record.
vitals.entered-byanddocuments.filed-byhave no path. Who entered a resource, or filed a document to a chart, is anentereragent on a Provenance that targets it, and a field reads only what is reached forward from the resource it reports, so it cannot reach a Provenance that points back.Observation.performeris who made the observation and a document'sauthenticatoris the sender's signer; neither is read in their place. See Where a Fact Is Stored. - Undecided storage. The referral fields and the consult letter fields depend on whether a referral or a consult report is a request, a report or a document. Their definitions say so; see Where a Fact Is Stored and Incoming Reports.
- No selector where one is needed. Treat the field as unavailable; do not take the first entry.
- No expected unit. A numeric threshold on a field without
expectedUnithas to carry its own unit, and is refused where it does not match. - First passes. The French and
identifierClasshave not been reviewed (see the warnings above).
Legacy picker ids¶
The Reporting Picker Id CodeSystem (legacy)
holds the field ids an earlier report builder shipped with, so that a report saved with one can
still be resolved. It is closed: nothing is ever added to it, and a new field gets a code in
nexus-field only.
The Reporting Picker Id to Nexus Field ConceptMap
(https://fhir.apps.health/ConceptMap/nexus-reporting-picker-id) maps each legacy id
to a nexus-field code, and the grade is what matters:
flowchart LR
L["legacy picker id"] --> Q{"equivalence"}
Q -- equivalent --> E["same field:<br/>re-point the saved report unattended"]
Q -- wider --> W["our field asks more:<br/>show the change to a person first;<br/>dependsOn states the narrowing condition, where expressible"]
Q -- unmatched --> U["no counterpart yet:<br/>report the criterion as unavailable"]
Migrating a saved report off a legacy id.
- equivalent means the same field; a saved report can be re-pointed without review.
- wider means the
nexus-fieldconcept is the broader of the two. Re-pointing silently would widen the question and return more patients, so a person has to see it. Where the difference is a condition on another element ("this field, but only where the relationship is care-giver"), the target carries it asdependsOn, naming the profiled element; the grade stayswiderso a consumer that ignoresdependsOndoes not apply the broader question unattended. - unmatched means nothing in
nexus-fieldmeans that field yet.
The field catalogue carries the same mapping: each field lists the legacy ids that are equivalent to it, and the catalogue lists the wider and unmatched ones separately.
Reading the code system page¶
The Nexus Field CodeSystem page shows every concept as one row of a wide table, with every property as a column.

The default view: the Coding, Derivation, Source and search, and French groups start hidden, and the sentence above the toggles always says so.
- Groups. Columns are grouped as in What a concept says: Definition, Placement, FHIR element, Access, Lifecycle, Coding, Derivation, Source and search, and French. Every property is placed in one of them; a property added later and not yet placed shows in a visible Other properties group. The group row above the header names each one.
- Toggles. One button per group shows or hides its columns. All columns shows everything; Default columns goes back to the default. Your choice is remembered in your browser for this code system. Without JavaScript there are no toggles and every column shows.
- Scrolling. The table scrolls inside its own box. The code and display columns stay pinned on the left and the header stays pinned on top, so every cell can be read against its row and column.
- Column headers. Hover a property's header for its declared description.
- Links. A category or subcategory cell links to that code system's page and shows the display beside the code.
- The property legend under the table lists every declared property, its type, its group, and how many concepts carry it, including any no concept carries yet. See Properties.

Only the FHIR element group showing, scrolled to the gate column. Each gate is one line; lines
on the same element name one entry.
The category and subcategory pages use the same table, and are narrow enough to read whole.
Related¶
- Where a Fact Is Stored: the element that holds a fact with more than one plausible home, which the fields read.
- Clinical Criteria (CQL) and Across a Population: criteria written in CQL, and the packs a population query is generated from.
- Salient Fields: the per-profile list of fields that matter in a summary, a different list for a different job.