Composition Profile

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

Nexus EMR profile for an AUTHORED clinical note -- principally the encounter note (progress note, consult note, telephone note) written by an EMR user or drafted by an AI scribe and attested by a clinician.

FSH

The authored source of truth: resources/StructureDefinition-nexus-emr-core-composition.fsh (edit on GitHub). One FSH file may define several related artifacts.

// StructureDefinition-nexus-emr-core-composition.fsh
// Authored clinical notes -- the encounter note, and the documents an EMR user WRITES.
//
// SCOPE. Documents whose narrative lives IN FHIR. Three populations share this profile as of
// 2026-08-19, and `category` is what tells them apart:
//
//   * the AUTHORED ENCOUNTER NOTE (LOINC 34109-9) -- what this profile was built for, and still
//     the shape everything else is measured against;
//   * a GENERATED SUMMARY (LOINC 34133-9) -- day-sheet and inter-visit summaries the AI harness
//     pre-generates and the EMR loads from the store like any other resource;
//   * a LETTER (LOINC 51852-2) -- letters and letter templates.
//
// They share this profile because they share a shape: authored narrative, sectioned, attributed,
// with a lifecycle. They are NOT interchangeable, and a consumer that ignores `category` will
// render a summary as though a clinician wrote it. See the `category` element.
//
// An earlier, broader Composition surface in this IG modelled four section kinds (text / form /
// canvas / file) with recursive containment and coordinate annotations; it was withdrawn in August
// 2026 as speculative, and this is deliberately not that surface returning -- three named document
// kinds with one classifier is not a generic document framework.
//
// Textual encounter notes were previously mapped to DocumentReference. Composition is the
// better model for them, so DocumentReference NARROWS to what it is good at -- an attached
// binary document (PDF, scan, Word, fax) -- and the two profiles now divide the space
// cleanly. See the boundary rule below, and the same rule restated on the DocumentReference
// profile.
//
// THE BOUNDARY RULE (the one thing to get right when choosing between the two):
//   Composition       = a note this EMR's user AUTHORED. Narrative lives IN FHIR, as XHTML in
//                       `section.text`, queryable and renderable without fetching a blob.
//   DocumentReference = a document that ARRIVED as an opaque file, or is only meaningful as
//                       one. Content is bytes with a MIME type; FHIR holds metadata + a
//                       pointer.
// The test is not "is it clinical" -- both are. It is "did we write it, and is the content
// text we control?" A scanned consult letter is a DocumentReference even though a human wrote
// it, because what we hold is a TIFF. A dictated-then-transcribed progress note is a
// Composition even though a machine produced the text, because we hold the text.
//
// WHAT THIS PROFILE COMMITS TO:
//   - `status` carries the signed/draft lifecycle: preliminary (draft) -> final (signed) ->
//     amended (edited after signing).
//   - Amendments are VERSION HISTORY, not new resources. See the long note on `status`: this
//     is the subtlest part of the model, and it depends on server capabilities the IG does
//     not yet declare.
//   - `author` admits a Device, so an AI-drafted note can say so on the resource itself. An
//     AI agent is referenced as a LOGICAL Device -- `Reference.identifier` under the
//     `nexus-harness-graph` NamingSystem with `Reference.type = "Device"`, needing no Device
//     resource on the server. See that NamingSystem and the Task profile.
//   - A Composition whose content a machine produced also carries the `AIAST` security label
//     in `meta.security` -- generated summaries, and AI-scribed notes including after a
//     clinician edits and signs one. `author` names WHICH graph produced it; the label answers
//     the coarser question, is searchable, and is the same on every resource type in this
//     specification. A note a clinician typed carries no label, and conversion from a source
//     EMR is not authorship, so converted notes carry none either. Attestation is a separate
//     axis: a signed AI-scribed note carries both `attester` and the label. See the AI
//     Attribution pattern in the handbook.
//
// OPEN MODELLING QUESTIONS -- do not read this file as a decision on any of these:
//   1. ORIGIN (typed vs scribed). For the COARSE question -- was any of this machine-produced
//      -- read the `AIAST` security label; that is settled and is spec-wide. What remains open
//      is which mechanism a consumer should read for the FINER question of what a machine
//      contributed and from where: (a) `author` carrying a Device alongside the human, or
//      (b) a Provenance record (`NexusEmrCoreProvenance`, itself a first pass). That depends
//      on what consuming code actually needs, and nothing here forecloses either.
//   2. RELATIONSHIP TO ClinicalImpression. `NexusEmrCoreClinicalImpression` already models
//      "the Assessment section of a SOAP encounter note" as a separate resource. A note that
//      is both a Composition and a source of ClinicalImpression has two homes for its 'A'
//      text, and the IG does not yet state which wins.
//
// DELIBERATE DIVERGENCE FROM US CORE. US Core models clinical notes as DocumentReference.
// This IG models AUTHORED notes as Composition and reserves DocumentReference for attached
// binary documents. The divergence is intentional: FHIR's document architecture (and its
// C-CDA lineage) is the deeper prior art for authored, sectioned, attested narrative, and
// `Composition.status` expresses the note lifecycle natively -- indeed
// `DocumentReference.docStatus` borrows the *CompositionStatus* value set, so Composition is
// that lifecycle's native home. Implementers coming from a US Core background should expect
// to find progress notes here, not on DocumentReference.

Alias: $NexusEmrCoreComposition = ../StructureDefinition/nexus-emr-core-composition

// `identifier` is 0..1 in R4 and this profile leaves it there, with no profile-wide requirement
// standing over it. It was 1..1 when this profile modelled ONE document kind; the widening to
// three took that justification with it, and the element definition below names the populations
// that must populate it instead of enforcing it profile-wide.

// A note with no readable body is not a note. R4 makes both `section` and `section.text`
// optional, so a Composition can legally carry a title, a status and nothing to read. For an
// encounter note that is a silent data-loss shape -- it renders as an empty chart entry
// rather than as a visible error. Phrased as a warning rather than an error because a
// legitimately empty draft (created, not yet typed into) is a real state.
Invariant:     composition-has-narrative
Description:   "SHOULD carry readable narrative -- at least one section with `text`, or a resource-level `text`. A note with no body renders as a blank chart entry rather than a visible error"
Severity:      #warning
Expression:    "section.where(text.exists()).exists() or text.exists()"

// A signed note must say who signed it. `status = final | amended` asserts sign-off; without
// an attester there is no one the record identifies as medico-legally responsible. Drafts are
// deliberately exempt -- an unsigned note has, correctly, no attester.
//
// GENERATED SUMMARIES ARE ALSO EXEMPT, added 2026-08-19 with the classification widening, and the
// reason is worth stating because the exemption looks like a loophole and is not. Nobody signs a
// day-sheet summary. It is machine-produced, regenerated whenever its inputs change, and no
// clinician attests to it -- so `final` on a summary means "this generation is complete", not
// "a human has taken responsibility for this". Requiring an attester would force writers either
// to leave summaries permanently `preliminary` (false: they are complete) or to name an attester
// who never attested (worse: a fabricated medico-legal signature). Letters are NOT exempt: a
// letter goes out over a clinician's name and is signed like any other authored document.
//
// THE TEST IS ONE CLAUSE, and it is worth recording that it did not used to be. While the document
// CLASS could live on either `type` or `category`, the exemption had to read "either classifier says
// summary, AND `category` says nothing else", and each half of that was patching a real hole:
//
//   * `category` is 0..*, so a clinician's note carrying BOTH 34109-9 and an added 34133-9 came out
//     exempt -- an unsigned final note, one extra coding away.
//   * a summary that classified only on one of the two elements was not exempt, and failed.
//   * requiring the summary code on a specific element rejected the shape the guide's own prose
//     told writers to produce.
//
// All three were the same defect wearing three hats: the question "is this a summary" had two
// possible homes, so no single expression could answer it. Putting the CLASS on `type`, which is
// 1..1 and therefore always present, gives the question exactly one home. The expression below reads
// the class off the element that always carries it, and none of the three holes can be spelled any
// more. A note does not become exempt by gaining a `category`, because `category` is not consulted.
//
// The general lesson survives the simplification, and it is the reason this comment is long: the
// invariant encoded an assumption true of every document this profile held when it was written --
// that documents are signed by people -- and widening the population meant making that assumption
// explicit rather than silently breaking it.
Invariant:     composition-signed-has-attester
Description:   "A note or letter with status `final` or `amended` SHALL identify who signed it -- `attester` with mode `legal` or `professional`. Generated summaries are exempt: nothing attests to a machine-generated summary, and naming an attester who never attested would fabricate a medico-legal signature. A summary is one whose `type` carries LOINC 34133-9. `category` is not consulted, so a note cannot buy the exemption by acquiring a refinement, and a converted summary must be remapped to say 34133-9 on `type` rather than carrying a source constant there."
Severity:      #error
Expression:    "(status = 'final' or status = 'amended') implies (type.coding.where(system = 'http://loinc.org' and code = '34133-9').exists() or attester.where(mode = 'legal' or mode = 'professional').exists())"

Profile:        NexusEmrCoreComposition
Parent:         Composition
Id:             nexus-emr-core-composition
Title:          "Composition Profile"
Description:    """
Nexus EMR profile for an AUTHORED clinical note -- principally the encounter note (progress
note, consult note, telephone note) written by an EMR user or drafted by an AI scribe and
attested by a clinician.

Narrative lives in FHIR as XHTML in `section.text`, not as an encoded attachment, so a note is
readable and queryable without dereferencing a blob. `status` carries the draft / signed /
amended lifecycle, and amendments are expressed as version history over one resource rather
than as a chain of related resources.

Use `DocumentReference` instead for documents that arrive as opaque files -- scans, PDFs,
faxes, Word documents -- where FHIR holds metadata and a pointer to bytes. The two profiles
partition the clinical-document space; neither is a fallback for the other.

**Read machine authorship from the `AIAST` security label in `meta.security`.** Nexus EMR also
writes a `typed`/`scribe` marker in `meta.tag`, at an address this guide does not publish, which is
a second answer to the question the label already settles; that second axis is tracked as FHIR-385.
Read `meta.security`, and do not read the absence of the `meta.tag` marker as `human-typed` --
absent means the origin was not recorded.
"""
* ^url = $NexusEmrCoreComposition
* ^status = #draft
* obeys composition-has-narrative and composition-signed-has-attester

// THE effective date for this profile (see the EffectiveDate / NoEffectiveDate RuleSets).
// TWO ARMS, and their order is the point: `event.period.start` FIRST, `date` only as the fallback.
// `event.period.start` is when the documented care happened and it does not move; `date` is the
// composition's own editing time and MOVES when the note is amended.
//
// So a note that populates `event` dates to its care, and a note that does not falls back to
// `date` -- which under the amendment model re-sorts it to the amendment's date on any timeline
// built from the effective date. The fallback exists because `date` is 1..1 in R4 and no note
// should be undatable, NOT because `date` is an acceptable clinical date. Populate `event`.
//
// Where a stable "when was this note WRITTEN" is needed -- a further question that neither arm
// answers, and that `attester.time` (when it was SIGNED) does not answer either -- it is
// `encounter`'s period, or the earliest version's `date` via history, which is exactly the
// capability the IG has not yet declared. Recorded as a known sharp edge rather than papered over.
* insert EffectiveDate([[event.period.start | date]])

// Salient fields -- the reader/render surface (see SalientField + the Salient RuleSet).
* insert Salient(status, status, code)
* insert Salient(type, type, coded)
* insert Salient(title, title, string)
* insert Salient(date, date, dateTime)
* insert Salient(author, [[author.first().display]], string)
// The note body. Unlike DocumentReference -- where the prose is base64 the accessor must
// decode -- a Composition's narrative is already text, so the accessor reads it directly.
//
// EVERY SECTION, JOINED -- NOT THE FIRST. This read was `section.first().text.div` on the stated
// grounds that multi-section notes were not the current shape. They are: a block-authored note is
// one section PER BLOCK, so a first-section read returns the first block of the note and silently
// drops the rest. That is the worst failure available to a salient field -- a plausible, non-empty
// value that is a fraction of the record -- and it gets worse, not better, as a provider writes
// more blocks. A four-section SOAP note filed before block authoring existed had the same defect
// and returned Subjective alone.
//
// The narrative is what carries a block's content whatever its kind (see
// `CompositionBlockExtensions.fsh`), so joining every section's `div` is the whole note body for
// every shape this profile admits. Separator is a space rather than a newline because the salient
// expression grammar's string literals are raw -- there is no escape processing -- and each `div`
// is a block-level element that already delimits itself for anything that parses the markup.
//
// Kind is `markdown`, NOT `string`, so it is recognised as LONG-FORM text (the harness's
// long_form_fields / cap_prose budget caps note bodies; the marker kinds are base64Binary and
// markdown). When the note body moved off DocumentReference's base64 attachment onto this inline
// narrative, a plain `string` kind would have made it a one-line attribute and left the whole note
// body uncapped in the chart context. `markdown` is the long-form marker for inline text.
//
// THE KEY IS `body` AND THE CHART NAME IS STILL `prose`. Those are different things and only the
// first moved. The chart attribute a renderer and a model read is unchanged, and
// DiagnosticReport publishes the same one from its own element. What changed is the accessor
// behind it: a joined string is a DERIVED value over the whole element, so it belongs on the
// collection `section` reads back as, and the accessor here delegates to it rather than compiling
// this expression a second time. This expression stays as the DEFINITION -- it is what the
// Salient-fields tab shows a consumer -- and there is one implementation of the join.
* insert SalientAs(body, [[section.text.div.join(' ')]], markdown, prose)
* insert SalientShort([[The whole note body, as XHTML -- every section's narrative, joined]])
* insert SalientDef([[The note text, as XHTML. **Complete on its own**: a consumer that reads nothing but this value, and no extension in this guide, must still get the clinically meaningful content of the note -- negative findings included. See the contract above `section.text`. This is the value the chart renders and the value an AI reads. It is TEXT IN FHIR -- not base64, not a blob pointer -- which is the substantive difference from the DocumentReference model this replaced for authored notes: it is greppable, diffable, and readable without a second fetch. DERIVED, and READ-ONLY. It is every section's narrative joined, so it exists nowhere in the resource and there is no way to redistribute an assigned string back across the sections it came from. To WRITE a note body, build the blocks and assign `section`.]])
* insert SalientComment([[Every section's narrative, in stored order, joined. A block-authored note stores one section per authoring block, so this is the whole note body rather than its first block; a note filed as SOAP sections reads the same way. A consumer needing the blocks apart -- their headings, their kinds, their structured values -- walks `section`, which reads back as a typed collection of authoring blocks, rather than reading this.]])

// SMART on FHIR exposure -- this resource is reachable by an app, and these are the
// permissions each operation costs (see SmartExposed + the SmartExposed RuleSet).
* insert SmartExposed(composition)

// --- Root Element ---

* . ^short      = "An authored clinical note (encounter note, consult note, telephone note)"
* . ^definition = """
A clinical note authored in this EMR: its narrative, its lifecycle state, who wrote it, who
signed it, and the encounter it belongs to.

Contrast `DocumentReference`, which references a document that exists as a file. A Composition
IS the note; a DocumentReference POINTS AT one.
"""

* meta.source 0..1 MS
* meta.source ^short = "Identifies EMR instance & pipeline version the resource came from"
* meta.source ^definition = "A URI that identifies the EMR pipeline and version from which this resource originated.  This tells you which EMR instance (recommend using the instance identifier), and the version of the pipeline code/transformations."

* text 0..1 MS
* text ^short = "Human-readable summary of the note"
* text ^definition = """
Resource-level narrative summarizing the note. Distinct from `section.text`, which is the note
CONTENT. For a single-section encounter note the two may be near-identical; where they differ,
`section.text` is authoritative for clinical content and this element is a summary.
"""

// Identifier: OPTIONAL as of 1.19.0. It was 1..1 while this profile modelled one document kind.
// NOT Must Support, and the reason is that nothing mints one. `identifier` here is
// RECOMMENDED but not required, under no mandated system -- and since the instance-scoped
// scheme was retired (FHIR-71) no producer writes a business identifier onto this type at
// all. Must Support asserts that an implementer can be expected to populate an element;
// claiming it for one the specification neither mandates nor produces states a guarantee
// that is not being made. The element stays available and documented -- a writer with a
// source-system identifier should still carry it.
* identifier 0..1
* identifier.system 1..1
* identifier.value 1..1
* identifier ^short = "Business identifier for the document -- stable across amendments"
* identifier ^definition = """
The source-system identifier for this document.

OPTIONAL (0..1), RELAXED FROM 1..1 IN 1.19.0. It was required when this profile modelled a single
document kind -- the encounter note, which is the unit source EMRs key on and the gateway must map
onto (OSCAR `casemgmt_note`), and an unidentified note cannot be reconciled across a sync boundary.
That case is still real and is still the reason to populate this element. What changed is the
population: the profile now holds three document kinds, and a document born here with no external
record to reconcile against has no identifier to carry. The server-assigned id already answers
"which document is this", and forcing a writer to mint a business identifier yields a meaningless
value that LOOKS like a key into something -- worse than absence. Letters shipped in exactly that
shape, off-profile, because the requirement could not be met honestly.

WHEN TO POPULATE IT -- stated rather than enforced, because the obligation differs by population:

* A document synced from, or reconciled to, a source system SHOULD carry that system's identifier.
  This is the encounter-note case the element was written for and it has not weakened.
* A generated summary MUST carry its harness business key under
  `NamingSystem/nexus-harness-key`. That key is what makes the summary update IN PLACE instead of
  minting a second resource on every run; without it, regeneration silently duplicates.
* A document that originated here and answers to neither case MAY omit it entirely.

WHICH identifier to put here: R4 gives Composition exactly ONE identifier slot, so where the
document came from a source system, that source identifier SHOULD be the one carried -- it is the
more useful of the two, being the only handle that reconciles back to the originating EMR.
Where the document originated here and has no source identifier, omit it: no canonical system is
mandated, and a document with a single free slot is better left empty than filled with an
identifier that reconciles to nothing.
Unlike the repeating-identifier profiles in this IG, there is no invariant enforcing a
preference, because with a single slot such an invariant would forbid rather than recommend.

STABLE ACROSS AMENDMENTS. This identifies the document, not the version of it. Amending a signed
note produces a new version of the same resource with the same identifier -- see `status`.

ONE SLOT, SO NO SECOND IDENTIFIER. Earlier text here invited implementers to carry a source 'raw
code' as an ADDITIONAL identifier, which the repeating-identifier profiles in this IG can do and
this one cannot: `Composition.identifier` is singular in R4. Where both a source identifier and a
raw code exist, the identifier above wins the slot and the raw code is not carried here.
"""

// Status: THE note lifecycle. This element is the answer to "is this note signed?"
* status 1..1 MS
* status ^short = "preliminary (draft) | final (signed) | amended (edited after signing) | entered-in-error"
* status ^definition = """
The note's lifecycle state. This is the element that answers "is this note a draft or is it
signed?" -- there is no extension for it and none should be created.

| Note state                  | status              |
|-----------------------------|---------------------|
| draft, being typed          | `preliminary`       |
| signed                      | `final`             |
| signed, then edited         | `amended`           |
| voided / created in error   | `entered-in-error`  |

AMENDMENTS ARE VERSION HISTORY, NOT NEW RESOURCES. When a signed note is edited, update THIS
resource in place and set `status` to `amended`. The server's version history preserves the
as-signed content. Do NOT create a second Composition and relate it back -- that leaves two
resources where the chart must know to display one, and every consumer must learn to filter.

`relatesTo` is deliberately left unprofiled. It stays available in core R4 if a true ADDENDUM
workflow later appears -- original untouched, new signed content appended, with its own author
and sign-off date -- which is a genuinely different clinical act from an in-place correction.
It is not the mechanism for ordinary amendment.

⚠ IMPLEMENTER WARNING -- this model depends on infrastructure this IG has not yet declared.
Version history is server-local: `_history` does not travel in bundles, `$everything`, or sync
pipelines, all of which move current versions only. Across a system boundary, an amended note
arrives as its amended text with the as-signed content absent. Furthermore this IG currently
publishes NO CapabilityStatement, so no versioning policy or supported-interaction set is
declared anywhere, and `meta.versionId` is type `id` -- server-opaque in R4 and unconstrained
here. Consumers MUST NOT infer ordering, authorship, or "which version was signed" by parsing
or sorting `versionId`. Reconstructing the as-signed note is, today, only reliable on the
authoring server. Declaring the version-history contract is tracked as outstanding IG work and
is a prerequisite for relying on this model across boundaries.
"""
* status from http://hl7.org/fhir/ValueSet/composition-status (required)

// Type: what kind of note. Extensible LOINC, per the removed profile and FHIR's own binding.
* type 1..1 MS
* type ^short = "What kind of document this is: note, summary or letter"
* type ^definition = """
What kind of document this is, at the coarsest useful level: an authored **note**, a generated
**summary**, or a **letter**. Three codes, and this element carries exactly one of them.

**This is the element to switch on, and the element to search.** It is 1..1, so it is always
present, and its vocabulary is small and closed enough that a consumer can branch on it exhaustively.
A surface that renders Compositions decides here whether it is showing clinician-authored content or
machine-generated content -- and `author` will not answer that, because a scribe-drafted note and a
generated summary both carry a Device author. `author` says who wrote it; this element says what it
is.

| code | what it is |
|---|---|
| LOINC 34109-9 "Note" | a clinician-authored note |
| LOINC 34133-9 "Summary of episode note" | a generated summary, of any kind |
| LOINC 51852-2 "Letter" | a letter |

**The finer question goes on `category`.** Which kind of note (progress, consult, discharge,
history and physical), and which kind of summary (day-sheet, interval, encounter recap), are
refinements of what this element already says. They are repeating and open-ended, which is why they
belong on a `0..*` element rather than this one. See `category`.

**Converted data usually needs remapping here.** In OSCAR, every `casemgmt_note` arrives with LOINC
11488-4 "Consult note" whatever the note actually is. That is a refinement code, not a class code: a
converter should write 34109-9 "Note" here and carry 11488-4 on `category`, rather than putting a
refinement in the class slot.

⚠ IMPLEMENTER WARNING -- an `extensible` binding is not silent in TypedFhir. A `required` binding
grades at ERROR; `extensible` and `preferred` both grade at WARNING; `example` is not checked. The
check fires only for a code OUTSIDE the bound set, so a document typed with something other than the
three codes above raises a validation warning. That is the intended signal here: the class axis is
small and this set enumerates it, so a code outside it is usually a refinement code in the wrong
slot. **A warning is not a rejection** -- `extensible` keeps a genuinely unclassifiable document
conformant.

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).
"""
// THE TWO ELEMENTS BIND THE TWO SETS, AND THE STRENGTHS DIFFER FOR A REASON.
//
// `type` is the CLASS axis. Its set enumerates that axis completely -- note, summary, letter -- so
// `extensible` is affordable and useful: a code outside the set is nearly always a refinement code
// written into the class slot, which is exactly the mistake worth warning about. Nothing is
// rejected, so a document that genuinely is none of the three stays conformant.
//
// `category` is the REFINEMENT axis, and no set here can enumerate it: LOINC's document axis is
// large and this guide should not copy it. A producer holding a more precise code than the ones
// listed should use it and must NOT earn a warning for being more precise. That is what `preferred`
// means, and it is why the finer element carries the weaker binding rather than the stronger one.
//
// The refinement set is a SUPERSET of the class set -- it contains all three class codes -- so
// repeating the `type` code on `category` always validates. `test:composition-vs` enforces that
// nesting; the relationship is not left to prose.
* type from NexusEmrCompositionClassificationVS (extensible)
* type ^binding.description = "The CLASS of document Nexus EMR stores -- note, summary or letter; extensible, so a document that is genuinely none of the three is still conformant"
* type.text 0..1 MS
* type.text ^short = "Local document class as the source EMR names it"

* category 0..* MS
* category ^short = "Refinements of the type: which kind of note, which kind of summary"
* category ^definition = """
The finer classification of a document, refining what `type` has already said at the class level.
Repeating and optional: a document may carry several refinements, or none.

**Switch on `type`, not on this element.** `type` is 1..1 and always present; `category` is 0..*
and may legitimately be absent. A consumer keying off `category` alone will miss documents.

What belongs here:

- **which kind of note** -- LOINC 11506-3 "Progress note", 11488-4 "Consult note", 18842-5
  "Discharge summary", 34117-2 "History and physical note"
- **which kind of summary** -- the codes in `nexus-composition-type`: a day-sheet summary written
  ahead of a clinic, an interval summary covering the gap since the last visit, a recap of a single
  encounter. LOINC has no concept for any of them, and they are not interchangeable
- a **repeat of the `type` code**, which is allowed: the bound value set contains all three class
  codes precisely so the repeat validates
- administrative or workflow labels a source system carries that have no place on `type`

**A refinement does not restate the class, it narrows it.** A progress note is `type` = 34109-9
"Note" and `category` = 11506-3 "Progress note". A day-sheet summary is `type` = 34133-9 "Summary of
episode note" and `category` = `nexus-daysheet-summary`. Reading `type` alone always tells a
consumer which of the three populations it is holding; reading `category` tells it which kind
within that population, when the producer knew.

**Bound `preferred`, deliberately weaker than the binding on `type`.** LOINC's document axis is
large and this guide does not enumerate it. A producer holding a more precise code than the ones
listed should write it here and should not earn a warning for being more precise.

**This profile and the DocumentReference profile differ on which element classifies, for a reason.**
That profile directs classification to `category` rather than `type`; this one puts the class on
`type`. The difference follows from the base cardinalities: `DocumentReference.type` is 0..1 and may
be absent, so `category` has to carry the load there. `Composition.type` is 1..1 and is always
present, so it carries it here.
"""
* category from NexusCompositionKindVS (preferred)
* category ^binding.description = "Refinements of the document class: note kinds, summary kinds, and the three class codes themselves so a repeat of `type` validates; preferred, so a more precise code is never penalised"
* category.text 0..1 MS
* category.text ^short = "Plain text refinement, where no code fits"

// Subject: patient-centric, matching the rest of this IG.
* subject 1..1 MS
* subject ^short = "Patient the note is about"
* subject ^definition = """
The patient this note documents. Required.

R4 permits any subject; this IG restricts to Patient, consistent with every other clinical
profile here. A note about something other than a patient has no home in this model.
"""
* subject only Reference(NexusEmrCorePatient)

// Encounter: the visit this note documents. THE reason encounter notes are the driving case.
* encounter 0..1 MS
* encounter ^short = "The encounter this note documents"
* encounter ^definition = """
The clinical encounter this note belongs to. Optional in R4 and left optional here, because
notes legitimately exist outside an encounter (a telephone note taken before the visit is
booked, a chart correction, a note migrated from a source EMR whose encounter linkage was
never recorded).

Where the note documents a visit, populate it: it is what groups notes onto the encounter in
the chart and what lets the day sheet find them.
"""
* encounter only Reference(NexusEmrCoreEncounter)

// ========== THE CLINICAL DATE ==========
//
// `event` is the element most readers actually want, and the one they do not find because `date`
// is sitting where they look first. `date` is editing metadata and MOVES when a note is amended;
// `event.period` is when the documented care actually happened, and it does not move.
//
// ⚠ THIS PROFILE AND DocumentReference DISAGREE ABOUT WHERE THE SAME FACTS LIVE, and the mismatch
// is inherited from base R4 rather than introduced here. A reader who learns one and assumes the
// other will look in the wrong place three times:
//
//     what                       Composition            DocumentReference
//     -------------------------  ---------------------  --------------------------
//     when the care happened     event.period           context.period
//     what kind of care          event.code             context.event
//     the visit                  encounter  (TOP level) context.encounter (NESTED)
//
// So Composition puts `event` at the top and `code` inside it; DocumentReference puts `context` at
// the top and `event` inside it -- the same two words, nested the opposite way round. And the
// encounter link sits at a different depth in each. Nothing here can fix that; it is written down
// so it costs a reader one paragraph instead of one debugging session.
* event 0..* MS
* event ^short = "The care being documented -- what happened, and WHEN it happened"
* event ^definition = """
The clinical service(s) this note documents. `event.period` is the CLINICAL date: the time the
documented care occurred, which is not the same as when the note was written, and not the same as
when it was last edited.

Populate it whenever the note is about care that happened at an identifiable time -- which for a
progress note, a consult note or a discharge summary is always. A note whose only date is `date`
cannot be placed on a clinical timeline correctly: an amendment moves it.

`event.detail` may reference the thing being documented; `event.code` says what kind of care it
was. Both are optional and neither substitutes for the period.
"""
* event.code 0..* MS
* event.code ^short = "What kind of care this note documents"
* event.period 0..1 MS
* event.period ^short = "WHEN the documented care happened -- the clinical date. Only 'start' expected"
* event.period ^definition = """
The period the documentation covers. This is the clinical relevance timeframe, not when the note
was created or last edited.

If only a point in time is relevant, use `start` only; for care spanning days (an admission), set
`end` as well. `start` is required when the period is present at all -- a period with no start
states nothing.
"""
* event.period.start 1..1 MS
* event.period.end 0..1
* event.detail 0..* MS
* event.detail ^short = "The thing being documented, when it is a resource"

* date 1..1 MS
* date ^short = "When the note was last logically changed"
* date ^comment = "Not the clinical date, and not the authored date."
* date ^definition = """
The composition editing time -- when the note was last logically changed.

Read the name carefully: this MOVES when the note is amended. It is not the authored date and it
is not the date the care happened. A timeline sorting notes by this element will re-position an
amended note to the date of its amendment.

Timing relationships on this profile:

- `date`: when this Composition was last edited (this element)
- `event.period`: when the documented CARE occurred -- the clinical date
- `encounter`: the visit the note belongs to, when there is one

Example. A progress note for an April 10 visit, written up the next morning and corrected a week
later:

- `event.period.start`: 2026-04-10 (the visit)
- `date` at first save: 2026-04-11
- `date` after the correction: 2026-04-18 -- and the visit is still April 10

**Sort a clinical timeline by `event.period.start`, not by `date`.**

This element is the FALLBACK arm of the profile's declared effective date, not the first one:
the declaration is `event.period.start | date`. A note that populates `event` dates to its care;
one that does not falls back to this element, which is a statement about resource metadata rather
than about clinical time. See the note on `event` above.
"""

// Author: who (or what) wrote it. This is one of the two candidate origin mechanisms.
* author 1..* MS
* author ^short = "Who or what wrote the note"
* author ^comment = "A Practitioner, or a Device for AI-drafted content."
* author ^definition = """
Who is responsible for the note's content. Required and repeating: a note has at least one
author, and may have several.

Practitioner is the primary provider identity in this IG; PractitionerRole is permitted where
the clinic/role binding is part of what is being asserted (Practitioner has no `organization`
and so cannot express it).

AI-DRAFTED NOTES. A Device may appear as an author alongside the human. This is one of the two
mechanisms for recording that a note was scribed rather than typed; the other is a Provenance
record (`NexusEmrCoreProvenance`), which carries the fuller trail -- model, inputs, supervising
human. They are not exclusive and the IG does not yet rule on which consumers should read.

Absent a Device author, the origin is UNKNOWN, not "typed". Legacy notes migrated from OSCAR
Pro carry no origin information and must not be inferred to be human-typed.

AN AI AGENT AUTHOR IS A LOGICAL DEVICE REFERENCE. `Reference.identifier` under the
`nexus-harness-graph` NamingSystem names the harness graph that produced the text, with
`Reference.type = "Device"`; no Device resource need exist on this server, and the granularity
is the graph/feature level. This is the same mechanism `NexusEmrCoreClinicalTask` uses for
`requester` and `owner`, so an AI-scribed note and the review Task carrying it name their agent
identically.

That is also why `author` admits **bare `Device`** alongside the two profiled Device types: a
logical, identifier-only reference cannot conform to `NexusEmrCoreAppDevice` or
`NexusEmrCoreEmrDevice`, because conforming to a profile presupposes a resource that exists to be
validated against it. The profiled targets remain for a Device actually registered in this
store; the bare target is what an AI agent uses.
"""
// Bare `Device` is deliberate and load-bearing, not laxity: it is the only Device target a
// logical identifier-only reference can satisfy. Allowing only the profiled Device types left
// AI-scribed authorship with NO conformant shape while the prose above described one. Mirrors
// Task.requester / .owner, which admit bare Device for exactly this reason.
* author only Reference(NexusEmrCorePractitioner or NexusEmrCorePractitionerRole or NexusEmrCoreAppDevice or NexusEmrCoreEmrDevice or Device or NexusEmrCoreOrganization)

* title 1..1 MS
* title ^short = "Human-readable label for the note"
* title ^definition = """
The note's label as shown in a chart list -- e.g. "Progress Note - 8 Apr 2025".

**Mandatory in base R4, not by this profile.** R4 makes `title` 1..1 on the reasoning that CDA left
it optional and no useful case for omitting it was known. A profile cannot relax a base cardinality,
so this element is required here whatever a primary care EMR would otherwise choose. Much of the
time there is no editorially meaningful title to write.

**When there is no meaningful title, write the display name of the `type` coding, exactly.** That is
the fallback R4's own guidance anticipates, and it is what downstream consumers expect to find. Do
not invent a label, and do not leave a placeholder string.

**Renderers may suppress a title that duplicates the type.** A consumer comparing `title` against
the display of `Composition.type.coding` and finding them equal may omit the title from its
presentation. The equality is the signal that no editorial title was authored.
"""

// Attester: who signed. Load-bearing -- see the composition-signed-has-attester invariant.
* attester 0..* MS
* attester ^short = "Who signed the note, and when"
* attester ^definition = """
Attestation -- the medico-legal signature.

REQUIRED ONCE SIGNED: a note with `status` of `final` or `amended` must carry an attester with
mode `legal` or `professional` (invariant `composition-signed-has-attester`). A signed note
with nobody identified as having signed it is not a record anyone can stand behind.

`attester.time` is when the signature happened -- distinct from `date` (last change) and from
the encounter's period (when care happened).

For AI-drafted notes, the attester is the CLINICIAN, never the Device. The Device may be an
author; it cannot attest. This asymmetry is the whole point of separating the two elements:
generation and responsibility are different acts.
"""
* attester.mode 1..1 MS
* attester.time 0..1 MS
* attester.party 1..1 MS
* attester.party only Reference(NexusEmrCorePractitioner or NexusEmrCorePractitionerRole or NexusEmrCoreOrganization)

* custodian 0..1 MS
* custodian ^short = "Organization responsible for maintaining the note"
* custodian ^definition = "The organization stewarding this note. Optional here (DocumentReference requires it) because an authored note's custodian is normally the clinic operating the EMR and is implied by tenancy."
* custodian only Reference(NexusEmrCoreOrganization)

// Section: the note body.
// STRUCTURED SECTIONS. A section carries its render kind and (where that kind has one) its own
// structured value in two extensions -- see `CompositionBlockExtensions.fsh`.
//
// Read that file before concluding this is the withdrawn four-section-type surface returning. It
// enumerates kinds as that one did -- `note-block-types` -- but it enumerates ones that have shipped
// rather than four that had not, which is the distinction the 1.11.0 removal actually turned on. A
// section is also ordered by R4's own `section` ordering rather than by recursive containment, and
// the carriers are two flat extensions rather than a sliced complex one. It clears the same bar this
// profile itself returned on in 1.14.0 -- a committed consumer exists.
//
// ────────────────────────────────────────────────────────────────────────────────────────────────
// THREE QUESTIONS PER SECTION, THREE SEPARATE ELEMENTS. They are independent, and collapsing any two
// of them is the mistake this profile most wants a producer to avoid:
//
//   * WHAT IS THIS SECTION CLINICALLY?  `section.code`. A problem list is LOINC 11450-4; a vitals
//     section is 8716-3. This is the element a consumer NAVIGATES by, and the reason C-CDA on FHIR
//     and IPS both put the weight here.
//   * WHO PRODUCED IT?                  `section.author`. A Practitioner, or a Device -- the element
//     already admits both, so an AI-produced section names its graph here.
//   * HOW DO I RENDER IT?               `composition-block-type`.
//
// KEEPING THEM APART IS WHAT MAKES THE THREE DOCUMENT KINDS ONE OBJECT. An encounter note, a letter
// and a generated summary all reduce to the same skeleton: a coded section, a readable narrative, an
// author, a render kind, and `entry` pointing at the structured content. A problem-list section is
// 11450-4 whether an editor widget, a letter template or a harness graph produced it, and a
// claims section renders identically whoever assembled it. Read `block-type` as "which editor widget
// wrote this" instead and a letter and a summary have no kind at all.
//
// TWO LEVELS OF "WHAT IS THIS", AND NEITHER IS THE SECTION. `type` is the class of the whole
// document and `category` the refinement under it; `section.code` is one section. A document code in
// a section slot -- LOINC 34109-9 "Note", which types DOCUMENTS -- is the error to watch for. 34109-9
// is not wrong, it belongs on `type`.
// ────────────────────────────────────────────────────────────────────────────────────────────────
//
// A structured section that has a clinical meaning SHOULD carry it in `section.code`, not leave
// it implied by the block kind. Coding every section with a document-type code -- LOINC 34109-9
// "Note" is the one to watch for, since it types DOCUMENTS rather than sections -- puts the only
// statement of what a section is inside a proprietary extension, where a consumer that does not
// implement this guide cannot reach it. C-CDA on FHIR and IPS both make `section.code` the element
// a consumer navigates by, and that is the behaviour to preserve.
//
// `section` is unconstrained by either extension: a section carrying neither is a plain narrative
// section exactly as described below.
* section 0..* MS
* section ^short = "The note body -- narrative in `section.text`"
* section ^definition = """
The note's content. For the common encounter note this is a single section carrying the whole
narrative; a structured note (SOAP, or a scribe template with headings) may carry several.

`section.code` is BOUND, `extensible`, to the Composition Section value set
(`nexus-composition-section`). **It is the element a consumer navigates a note by**, and where a
section has a clinical meaning it should say so here: a vital signs section is LOINC 8716-3.

It is NOT the place for a document-type code. LOINC supplies both document codes and section codes,
out of one system and in one format, so nothing about a code says which axis it belongs to -- 34109-9
"Note" types a document, not a section. That is the mistake the extensible strength exists to catch:
a code from the document axis warns. The cost is accepted -- a legitimate section kind the set does
not yet name warns too, and growing the set is one line.

`section.code` is also not interchangeable with the block-type extension, which says how to RENDER
the section rather than what the section is. Who produced it is a third question again, and
`section.author` answers that.

Note the overlap with `NexusEmrCoreClinicalImpression`, which models the Assessment ('A') of a
SOAP note as its own resource. A note carrying an assessment section AND a ClinicalImpression
has two homes for the same text; the IG does not yet rule which is authoritative.
"""

* section.title 0..1 MS
* section.title ^short = "Section heading as displayed"

* section.code 0..1
// BOUND AS OF 1.22.0, after being deliberately unbound while no producer populated it. There are
// producers now -- the note editor, the letters stream, the generated summaries and the seed corpus
// -- and the binding is what turns a rule this guide had only in prose into one a validator can
// catch.
//
// THE RULE IT CATCHES: LOINC supplies BOTH document codes and section codes, out of one system, in
// one format. `34109-9` ("Note", a document) and `8716-3` ("Vital signs", a section) are
// indistinguishable as data, and nothing about a LOINC code says which axis it belongs to. A
// document code in the section slot is therefore a mistake the format itself cannot prevent and no
// reader can detect after the fact.
//
// EXTENSIBLE rather than preferred, deliberately. Preferred documents a vocabulary and warns on
// nothing, which would not catch the error this binding exists for. Extensible warns on a code
// outside the set, and a document code in a section slot is exactly that. The cost is accepted: a
// legitimate section kind the set does not yet name also warns, and growing the set is one line.
* section.code from NexusCompositionSectionVS (extensible)
* section.code ^short = "What the section clinically IS -- a SECTION code, never a document code"

* section.code ^comment = """
⚠ IMPLEMENTER WARNING -- A DOCUMENT CODE IS IN CIRCULATION IN THIS ELEMENT, and a reader that
has not been told will lose content silently.

Block-structured note editors store one section per block. Where a block carried no code of its
own -- which was every block raised from a template that did not assign one -- the fallback
written here was LOINC 34109-9 "Note": the document code named as the example above, in the slot
this binding exists to keep it out of. It was the common shape on such a note rather than a rare
one.

WRITERS NO LONGER PRODUCE IT, AND STORED DATA IS NOT REWRITTEN. The editor now writes a section
code, and nothing recodes a note already on file: a filed record is not amended because an
unrelated release changed a default. Editing such a note preserves the code it was stored with,
by design. So this is a LEGACY shape rather than one still being created -- and the amount of it
in a deployment is fixed at whatever was written before that change, rather than growing.

READERS MUST TOLERATE IT. Do not treat a section as unclassified because its code is a document
code, and do not drop it. A reader that selects sections by section code will otherwise discard
that content without any signal: the binding raises its warning at VALIDATION, and a reader is
not a validator. Where a reader needs the whole note, take every section and use `section.title`
and the narrative when the code does not discriminate.

WRITERS SHOULD CODE A SECTION FOR WHAT IT CLINICALLY IS. Most blocks have an identity worth
recording -- an agenda, a reason for contact, a chronic-disease review -- and a template is the
right place to decide it once, rather than a fallback applied at save time. Where a block
genuinely has no clinical identity, `55752-0` "Clinical information" is the generic member of
the bound set. It is a section code, not a document code.

NOT `28562-7` "Chart section Set", which this release reserves. The `enclosures` slice below is
discriminated by `#pattern` on `code`, so a section carrying that code is INSIDE that slice by
content rather than by opting in -- it is then `0..1` for the whole document, and its `entry` is
typed to an attachment packet. Coding an authoring block `28562-7` therefore makes the document
invalid where a second one exists, and where it does not, a consumer resolving enclosures by code
reads that block as the document's attachment manifest.

MIGRATION -- WHAT IS NOT SETTLED. Notes already stored carry 34109-9 in this element. Whether
those are remapped, or readers are expected to accept both forms indefinitely, is open. A
remapping cannot be mechanical for the blocks that HAVE an identity: recovering it means reading
the block's title or its template, not rewriting one code to another.
"""

// ────────────────────────────────────────────────────────────────────────────────────────────────
// THE CONTRACT BETWEEN NARRATIVE AND STRUCTURED DATA, and it is the single most load-bearing rule
// in this profile.
//
// A section carries its content TWICE, deliberately:
//
//   * the STRUCTURED DATA (`section.entry`, and a render kind's own structured value) is the display
//     path -- what this EMR's own UI reads and renders;
//   * the NARRATIVE (`section.text`) is for everyone who is not that UI: another EMR, a partner app,
//     an export, a person opening the record, a model reading the chart.
//
// THE RULE IS: A RENDERER SHOWS THE STRUCTURED DATA AND IGNORES THE NARRATIVE. Nothing is displayed
// twice, and the duplication is not a display defect to be optimised away.
//
// THE CONSEQUENCE IS THAT BOTH SIDES MUST BE COMPLETE, and this is where producers get it wrong:
//
//   * anything the UI needs must be in the structured data -- a field that exists only in prose is
//     invisible to the surface that renders it;
//   * anything CLINICALLY MEANINGFUL must also be in the narrative, INCLUDING NEGATIVES. "No active
//     problems" is a finding, not filler, and a narrative that omits it reads as a section nobody
//     filled in. Booleans and scalars count: a value that lives only inside a structured payload
//     leaves every consumer who is not this UI reading an incomplete document.
//
// Only GENUINELY ABSENT fields are left out of both. Absent means the fact does not exist, not that
// it was inconvenient to render.
//
// A consumer that ignores every extension in this guide must still get a correct, readable document.
// That is the property this contract exists to preserve, and a section that breaks it -- clinical
// content in the structured value and nothing in `text` -- is malformed however well it round-trips.
// ────────────────────────────────────────────────────────────────────────────────────────────────

* section.text 0..1 MS
* section.text ^short = "The section's narrative, as XHTML"
* section.text ^comment = "Complete on its own, with negatives included."
* section.text ^definition = """
The note text, as XHTML. **Complete on its own**: a consumer that reads nothing but this element,
and no extension in this guide, must still get the clinically meaningful content of the section --
negative findings included. See the contract above `section.text` in the FSH.

This is the element the chart renders and the element an AI reads. It is TEXT IN FHIR -- not
base64, not a blob pointer -- which is the substantive difference from the DocumentReference
model this replaced for authored notes: it is greppable, diffable, and readable without a
second fetch.

XHTML, NOT ARBITRARY HTML. Content SHALL conform to the FHIR Narrative rules: no active
content, no scripts, no external references. A gateway converting source-EMR note text (which
in OSCAR is effectively plain text with newlines) MUST sanitize and wrap it, not pass it
through.
"""

// RESTATED, NOT NARROWED. `Narrative.status` is already 1..1 and bound required in base R4; this
// profile adds no constraint. It is declared here so the generated validators CHECK it, because
// they derive their element rules from what a profile constrains and had no rule for this one --
// a section written as `{"text": {"div": "..."}}` passed TypedFhir and failed the HL7 validator.
//
// The status is not decoration. `generated` asserts the narrative can be rebuilt from the
// resource's structured data, and a renderer that believes it may discard the narrative and
// render the structured data instead. For a clinician's note body, a letter, or an AI summary
// that is `additional`: the text IS the content and there is nothing to rebuild it from.
* section.text.status 1..1 MS
* section.text.status ^short = "generated | extensions | additional | empty -- a note body is `additional`"
* section.text.status ^definition = """
Whether the narrative can be regenerated from the resource's structured data. Required by R4 and
easy to omit, because a writer assembling `section.text` by hand thinks of the div as the value.

| what the narrative is | status |
|---|---|
| a clinician's note body, a letter, an AI summary | `additional` |
| text a machine can regenerate from this resource's own structured data | `generated` |
| a block the author raised and left blank | `empty`, with `section.emptyReason` |

`generated` is the one to be careful with: it is a claim that the narrative is disposable, and a
consumer entitled to act on it will render the structured data alone. A note body is not
regenerable from `section.entry`, whatever else a section carries.
"""

* section.author 0..* MS
* section.author ^short = "Per-section authorship, where sections have different authors"
// Same target list as `Composition.author`, bare `Device` included: a partly-scribed note names
// its agent per section, and that agent is a logical Device reference. See `author`.
* section.author only Reference(NexusEmrCorePractitioner or NexusEmrCorePractitionerRole or NexusEmrCoreAppDevice or NexusEmrCoreEmrDevice or Device or NexusEmrCoreOrganization)

* section.entry 0..* MS
* section.entry ^short = "Structured resources belonging to this section"
* section.entry ^definition = """
References to discrete resources that belong to this section -- the structured counterpart to
`section.text`.

Currently unconstrained by type and expected to be sparse: today's notes are narrative. This is
the element that carries structured note generation when it arrives (a scribe filling a
structured template, or SDC extraction promoting answers to Observation / Condition), which is
why it is declared now rather than left to be discovered later.
"""

* section.emptyReason 0..1
* section.emptyReason ^short = "Why an expected section is empty"
* section.emptyReason ^definition = "Where a template declares a section that has no content, this records why it is empty rather than leaving the reader to guess between 'nothing to report' and 'not asked'."

// ────────────────────────────────────────────────────────────────────────────────────────────────
// THE ENCLOSURES SECTION: HOW A DOCUMENT NAMES WHAT TRAVELS WITH IT.
//
// A letter can go out with chart items attached -- the recent bloodwork, the report that prompted a
// referral, an earlier letter from a colleague. Those items are a `List` profiled as
// NexusAttachmentPacket, and THE LETTER NAMES THE PACKET rather than the packet naming the letter,
// so that an attachment chosen before the letter was ever stored has somewhere to be recorded: the
// section rides the letter's own save.
//
// WHAT WAS MISSING UNTIL NOW WAS THE JOIN, not either half. LOINC 28562-7 has been in the section
// value set since 1.25.0 and the packet profile has been published just as long, and no artifact
// said the two go together -- so the only statement of how a document names its attachments lived in
// a private method of the client that reads them back. A consumer could read this whole guide and
// not discover the mechanism.
//
// RESOLVED BY THE CODE, NOT BY POSITION. The body is the only section written at a known index
// (`section[0]`); a producer that adds sections of its own puts the enclosures anywhere after it. So
// the discriminator is `code`, which is also how the reader in the product resolves it -- system AND
// code, because 28562-7 under somebody else's system is that producer's section.
//
// DO NOT WRITE "Enclosures" AS THE LOINC DISPLAY. 28562-7 resolves in LOINC 2.83 as "Chart section
// Set" and "Enclosures" is not a term of that concept. It is the SECTION HEADING, and it belongs on
// `section.title`, which is where the product puts it and where this guide's examples put it. This
// is the obvious wrong thing to write, which is why it is said here.
//
// `entry` IS NOT RAISED TO 1..* INSIDE THE SLICE, though every writer today produces at least one.
// An authoring block raised and left blank is a legitimate empty section -- that is what
// `section.emptyReason` is for, one element above -- and a minimum here would make that instance
// invalid to say something no consumer needs said. An enclosures section with no entry means no
// packet travels with the document.
//
// OPEN SLICING, and the slice is 0..1. Nothing about this makes a section required, changes what an
// existing letter validates as, or constrains a section that carries a different code.
//
// 11503-0 IS NOT THIS CODE. It is the document code for the rendered packet PDF and belongs on
// `DocumentReference.type` -- never in a section slot. The section value set's own comment carries
// the same warning.
// ────────────────────────────────────────────────────────────────────────────────────────────────
* section ^slicing.discriminator[0].type = #pattern
* section ^slicing.discriminator[0].path = "code"
* section ^slicing.rules = #open
* section ^slicing.ordered = false
* section ^slicing.description = "Sections this guide names by their code. Everything else -- the note body, a SOAP section, an authoring block -- is an ordinary unsliced section, PROVIDED it does not carry a code this slicing names: membership is decided by content, not by opting in."

* section contains enclosures 0..1 MS
* section[enclosures] ^short = "The attachment packets travelling with this document, one entry each"
* section[enclosures] ^definition = """
The document's own account of what is attached to it: a section coded LOINC `28562-7` whose `entry`
references one or more attachment packets (`List` resources profiled as Attachment Packet). A letter
sent with enclosures carries this section; a document sent with nothing carries no such section.

**This is the only record of a document's attachments.** The packets do not point back, so a
consumer asking what went out with a letter reads this section and nothing else.

**Resolve it by the coding, not by position.** The body is the section at a known index; this one
follows it and may sit anywhere after it. Match `system` and `code` together -- `28562-7` under
another producer's system is that producer's section, not this one.

**The heading is `section.title`.** Write "Enclosures" there. `28562-7` is named "Chart section Set"
in LOINC and "Enclosures" is not a term of that concept, so it does not belong in the coding's
`display`.

**Membership lives on the packet, not here.** `entry` names the packets; which chart items each
holds, in what order, and which of their pages are left out are all on the packet.
"""
* section[enclosures].code 1..1
* section[enclosures].code = http://loinc.org#28562-7
* section[enclosures].code ^short = "LOINC 28562-7 -- the enclosures section code (display: `Chart section Set`)"
* section[enclosures].title ^short = "The heading as displayed -- `Enclosures`"
* section[enclosures].entry only Reference(NexusAttachmentPacket)
* section[enclosures].entry ^short = "One attachment packet per entry"
* section[enclosures].entry ^comment = "Each entry is a `List` profiled as Attachment Packet. Nothing else belongs here: a document, a result or a note attached to the document is a MEMBER OF a packet, not an entry of this section, so that its order and its excluded pages have somewhere to live."

* confidentiality 0..1
* confidentiality ^short = "Confidentiality level, where the EMR distinguishes"