Observation Profile

Canonical	../StructureDefinition/nexus-emr-core-observation
Status	draft · 1.26.0
Base	Observation (constraint)
Source	FSH · JSON

Nexus EMR profile for the Observation resource, based on CA-Core. Represents measurements, tests, and simple assertions originating from source EMRs for aggregation.

TypedFhir API / Pydantic schema

The typed accessor surface Observation exposes for Observation — generated from this IG's compiled profile; each typed accessor has a validating raw-FHIR twin (xRaw) where marked. The three ports are parity-enforced.

The AI-facing shape: from typed_fhir.facade.generated.schemas import ObservationSchema — model_json_schema() is a structured-output / tool definition; instantiating validates an extraction. Generated source.

class ObservationSchema(BaseModel):
    """AI-facing shape of the Observation profile: the facade's typed accessor
    surface (curated + salient fields) as a pydantic model. `model_json_schema()` is a
    structured-output / tool schema; instantiating validates an extraction."""

    model_config = ConfigDict(extra="forbid")

    status: Literal[
        "amended",
        "cancelled",
        "corrected",
        "entered-in-error",
        "final",
        "preliminary",
        "registered",
        "unknown",
    ] | None = Field(
        None,
        description=(
            "Where the result is in its lifecycle. The status of the result value. Indicates "
            "whether the observation is complete and verified. Note: This is a modifier element. "
            "Preliminary results should be interpreted with caution. Observation.status — 1..1"
        ),
    )
    category: Concept | None = Field(
        None,
        description=(
            "Classification of type of observation. A code that classifies the general type of "
            "observation being made. Common categories include vital-signs, laboratory, imaging, "
            "survey, exam, therapy, and activity. Note: This profile constrains category to "
            "exactly one (1..1) -- carry the observation's standard clinical category (e.g. "
            "vital-signs | laboratory | imaging | exam | social-history | survey). A prevention "
            "Observation is NOT distinguished by its category: it uses its normal clinical "
            "category and is marked as a prevention by a coding under the "
            "nexus-emr-prevention-catalog NamingSystem on Observation.code.coding. "
            "Observation.category — 1..1. codes (required): activity | exam | imaging | "
            "laboratory | procedure | social-history | survey | therapy | …"
        ),
    )
    code: Concept | None = Field(
        None,
        description=(
            "Observation type with raw code support. Type of observation (e.g., vital sign, "
            "laboratory test, imaging observation). REQUIRED: text element for human readability "
            "RECOMMENDED: LOINC code when available OPTIONAL: Raw EMR observation codes for "
            "source system preservation Nexus EMR does not mandate a specific coding system for "
            "observations. The text element ensures human readability even when coded values are "
            "not recognized. Where this code was mapped from a source system's own vocabulary, "
            "carry the raw coding alongside the mapped one, flagged `userSelected = true`. See "
            "[Carrying the raw code](../guide/patterns/raw-codes.md). "
            "Note: *All* code-value and, if present, component.code-component.value pairs need to "
            "be taken into account to correctly understand the meaning of the observation. "
            "Observation.code — 1..1"
        ),
    )
    value: Quantity | None = Field(
        None,
        description=(
            "Actual observation result. The actual value of the observation. The data type varies "
            "based on the nature of the observation. Note: Use the appropriate data type: "
            "Quantity for measurements, CodeableConcept for coded results, string for text "
            "results, etc. Observation.value[x] — 0..1"
        ),
    )
    date: FuzzyDate | None = Field(
        None,
        description=(
            "Clinically relevant time/time-period for observation. The time or time-period the "
            "observed value is asserted as being true. For biological subjects this is usually "
            "the time specimen was obtained. Note: For observations with a single point in time, "
            "use effectiveDateTime. For observations over a period, use effectivePeriod. "
            "Observation.effective[x] — 1..1"
        ),
    )
    interpretation: Concept | None = Field(
        None,
        description=(
            "High, low, normal, etc. A categorical assessment of an observation value. Common "
            "interpretations include high, low, normal, abnormal, critical. Note: Multiple "
            "interpretations may be provided for different aspects of the result. "
            "Observation.interpretation — 0..*. codes (extensible): < | > | A | AA | AC | B | CAR "
            "| Carrier | …"
        ),
    )
    low: Quantity | None = Field(
        None,
        description=(
            "Low Range, if relevant. The value of the low bound of the reference range. The low "
            "bound of the reference range endpoint is inclusive of the value (e.g. reference "
            "range is >=5 - <=9). If the low bound is omitted, it is assumed to be meaningless "
            "(e.g. reference range is <=2.3). Observation.referenceRange.low — 0..1"
        ),
    )
    high: Quantity | None = Field(
        None,
        description=(
            "High Range, if relevant. The value of the high bound of the reference range. The "
            "high bound of the reference range endpoint is inclusive of the value (e.g. reference "
            "range is >=5 - <=9). If the high bound is omitted, it is assumed to be meaningless "
            "(e.g. reference range is >= 2.3). Observation.referenceRange.high — 0..1"
        ),
    )
    data_absent_reason: Concept | None = Field(
        None,
        description=(
            "Why the result is missing. Provides a reason why the expected value in the element "
            "Observation.value[x] is missing. Note: Null or exceptional values can be represented "
            "two ways in FHIR Observations. One way is to simply include them in the value set "
            "and represent the exceptions in the value. For example, measurement values for a "
            "serology test could be \"detected\", \"not detected\", \"inconclusive\", or \"specimen "
            "unsatisfactory\". The alternate way is to use the value element for actual "
            "observations and use the explicit dataAbsentReason element to record exceptional "
            "values. For example, the dataAbsentReason code \"error\" could be used when the "
            "measurement was not completed. Note that an observation may only be reported if "
            "there are values to report. For example differential cell counts values may be "
            "reported only when > 0. Because of these options, use-case agreements are required "
            "to interpret general observations for null or exceptional values. "
            "Observation.dataAbsentReason — 0..1. codes (extensible): as-text | asked-declined | "
            "asked-unknown | error | masked | negative-infinity | not-a-number | not-applicable | "
            "…"
        ),
    )
    subject: Reference | None = Field(
        None,
        description=(
            "Who and/or what the observation is about. The patient, group, device, or location "
            "that this observation is about. For Nexus EMR, this must be a patient referenced by "
            "identifier. Note: References should use identifier-based references following Nexus "
            "EMR patterns. Observation.subject — 1..1"
        ),
    )
    value_text: str | None = Field(
        None,
        description=(
            "Actual observation result. The actual value of the observation. The data type varies "
            "based on the nature of the observation. Note: Use the appropriate data type: "
            "Quantity for measurements, CodeableConcept for coded results, string for text "
            "results, etc. Salient field — valueString | valueCodeableConcept.text | "
            "valueCodeableConcept.coding.first().display | valueBoolean | valueInteger | "
            "valueDateTime | valuePeriod.start | valueTime"
        ),
    )