Skip to content

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
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=X together with category.coding.code=Y means 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 on category.coding.code=108252007|363679005 with category.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 is status or verificationStatus on most resources, and also Goal.lifecycleStatus and DocumentReference.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.referenceRange with no type is the normal range, so orders-results.reference-range, selector referenceRange.type.coding.code=normal, selects a range typed normal where there is one, and otherwise a range with no type. Writers still state the type; see Where a Fact Is Stored.
  • $none says the clinicalCode text describes the field rather than choosing among entries, so the path alone is the field (orders-results.result-value: the test is identified by Observation.code, not by choosing within value[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 fhirPath lands on an element of the named profile, and every gate on an element of the resource;
  • a stated dataType is 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-code names 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: latest is the default for result-value; the most recent HbA1c is the one compared.
  • Unit: result-value holds every test's value, so it has no expectedUnit. A threshold has to be stated with its unit (%), and a result in another unit (for example mmol/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 (profile is stated, because ServiceRequest has more than one profile), reading ServiceRequest.authoredOn.
  • Gates: a referral is a ServiceRequest with intent proposal; a sent one has one of the statuses that follow sending.
  • Aggregation: latest.
  • Not yet decided. The Referral profile defines authoredOn as 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, reading DocumentReference.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 category carries a coding from document-category, which every filed document has. Add documents.document-type to narrow by kind.
  • Aggregation: the default is latest; for "how many", name count.
  • 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) and prevention.date-given (occurrence[x]), on the Immunization profile.
  • Gates: prevention.vaccine-code, prevention.vaccine-name and prevention.date-given are each gated on status completed, so a dose recorded as not-done fills none of them. prevention.immunization-status reads 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 on status=not-done.
  • Aggregation: any for the code, latest for the date; name count for 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 active as a record in active use (the profile's comment repeats it), and the field carries that as meaningWhenMissing. "Patient status is true" has to count patients with no value; a query that tests only for true misses 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 example billing.claim-dx-code (the claim line's code is the fee code; the diagnosis travels on an extension this guide does not yet declare) and medications.signed-date (no element records when a prescription was signed). A computed field (derived, for example demographics.age) has no path either; its definition is referenced through cqlExpression once it is published.
  • Who entered or filed a record. vitals.entered-by and documents.filed-by have no path. Who entered a resource, or filed a document to a chart, is an enterer agent 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.performer is who made the observation and a document's authenticator is 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 expectedUnit has to carry its own unit, and is refused where it does not match.
  • First passes. The French and identifierClass have 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-field concept 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 as dependsOn, naming the profiled element; the grade stays wider so a consumer that ignores dependsOn does not apply the broader question unattended.
  • unmatched means nothing in nexus-field means 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 nexus-field concept table at its default columns: the sentence above it says how many columns are showing and which groups are hidden, the group toggles follow, and the table starts with the code, display, definition and placement columns for the first demographics fields.

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.

The same table with only the FHIR element group showing, scrolled sideways to the gate and dataType columns: the privacy-flag fields are gated on the privacy-directive consent family, and the problem-list fields on the problem-list-item category, with the active clinical statuses added on Problem/diagnosis and Onset date.

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.