DetectedIssue Profile

Canonical	../StructureDefinition/nexus-emr-core-detectedissue
Status	draft (experimental) · 1.26.0
Base	DetectedIssue (constraint)
Source	FSH · JSON

Nexus EMR profile for DetectedIssue -- drug-drug and drug-allergy interaction findings raised during prescribing, and the prescriber's recorded override of them. First pass: models the override audit trail; the severity mapping is not yet settled.

TypedFhir API / Pydantic schema

The typed accessor surface DetectedIssue exposes for DetectedIssue — 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 DetectedIssueSchema — model_json_schema() is a structured-output / tool definition; instantiating validates an extraction. Generated source.

class DetectedIssueSchema(BaseModel):
    """AI-facing shape of the DetectedIssue 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=(
            "registered | preliminary | final | amended | ... (observation-status). Indicates the "
            "status of the detected issue. Note: The Rx module writes `final` for a screening "
            "result it stands behind. This element is NOT the override axis -- an overridden "
            "issue stays `final` and gains a `mitigation`; it does not become `cancelled`. "
            "Readers must not infer 'resolved' from status. DetectedIssue.status — 1..1"
        ),
    )
    code: Concept | None = Field(
        None,
        description=(
            "The kind of issue detected (drug-drug interaction, drug-allergy, etc.). Identifies "
            "the general type of issue identified. Note: Currently written text-only by the "
            "screening layer. Text-only is conformant (CodeableConcept), so readers MUST NOT "
            "index positionally into `code.coding` -- see the text-only-concept rule. Coding this "
            "against `detectedissue-category` is first-pass follow-up, not settled. "
            "DetectedIssue.code — 0..1"
        ),
    )
    severity: Literal["high", "low", "moderate"] | None = Field(
        None,
        description=(
            "high | moderate | low. Indicates the degree of importance associated with the "
            "identified issue based on the potential impact on the patient. Note: ⚠ FIRST PASS -- "
            "NOT SETTLED. The screening engine has its own severity scale and the mapping onto "
            "the R4 `detectedissue-severity` required binding has not been agreed. Do not treat "
            "the current values as a contract. DetectedIssue.severity — 0..1"
        ),
    )
    patient: Reference | None = Field(
        None,
        description=(
            "The patient the issue was detected for. Indicates the patient whose record the "
            "detected issue is associated with. Note: 0..1 in R4 and left as such: a screening "
            "result computed before a patient context is established (e.g. a drug-pair lookup) "
            "legitimately has none. Anything persisted against a chart SHOULD carry it. "
            "DetectedIssue.patient — 0..1"
        ),
    )
    implicated: Reference | None = Field(
        None,
        description=(
            "The medication/allergy resources whose combination raised this issue. Indicates the "
            "resource representing the current activity or proposed activity that is potentially "
            "problematic. Note: For a drug-drug interaction this is the two or more "
            "MedicationRequests; for drug-allergy, the MedicationRequest and the "
            "AllergyIntolerance. Per the Nexus EMR logical-reference model these MAY be "
            "identifier-only, so consumers must not assume a resolvable literal reference. "
            "DetectedIssue.implicated — 0..*"
        ),
    )
    mitigation: dict | None = Field(
        None,
        description=(
            "The prescriber's recorded decision to proceed despite the issue. The action taken "
            "about the detected issue. In this EMR a mitigation means **a human overrode the "
            "warning and proceeded**, and `mitigation.action.text` carries the rationale they "
            "gave. This is a medico-legal record. It is written in the same transaction bundle as "
            "the MedicationRequest it concerns, so the prescription and the reason for accepting "
            "its risk are committed together or not at all. Note: ⚠ Cross-consumer convention, "
            "and the reason this profile exists: the PRESENCE of a mitigation is what marks an "
            "issue as accepted/overridden. `status` does NOT change. A reader that filters on "
            "status will show overridden interactions as live warnings. DetectedIssue.mitigation "
            "— 0..*"
        ),
    )
    date: FuzzyDate | None = Field(
        None,
        description=(
            "When identified. The date or period when the detected issue was initially "
            "identified. Salient field — identifiedDateTime | identifiedPeriod.start"
        ),
    )