Composition Billing Extension

Canonical	../StructureDefinition/composition-billing
Status	draft · 1.26.0
Base	Extension (constraint)
Context	Composition (element)
Source	FSH · JSON

The billing raised for the visit this note documents: the service code, the diagnostic codes supporting it, and the units where the fee code is charged per unit.

FSH

The authored source of truth: extensions/CompositionNoteExtensions.fsh (edit on GitHub). One FSH file may define several related artifacts.

// CompositionNoteExtensions.fsh
// Three complex extensions an encounter note carries on `Composition` itself: the billing raised for
// the visit, where a signed note has been shared, and the editor setup a draft was opened on.
//
// WHY THESE ARE DECLARED HERE. All three are written by production code today and none was described
// anywhere. A reader of this guide saw a Composition profile with no billing concept, no sharing
// concept and no record of what a draft was opened from, while live notes carried all three. An
// undeclared extension is not a smaller commitment than a declared one -- it is the same commitment
// with no description attached, and it makes the divergence permanent by default. Declaring them is
// what closes that.
//
// ────────────────────────────────────────────────────────────────────────────────────────────────
// THE CANONICALS HERE ARE NOT THE ONES THE SOFTWARE WRITES TODAY, AND THAT IS DELIBERATE.
//
// These three publish under `../StructureDefinition/...`, the base
// `conventions.md` names for everything in this guide. The EMR front end writes them under
// `http://services.well.com/fhir/StructureDefinition/...`, and this specification does not follow
// it there.
//
// That is a deliberate reversal of how the block extensions were handled. Those were declared at
// the address the software already wrote, on the reasoning that declaring an extension at an
// address nothing emits documents a fiction -- then moved to this base a commit later, while the
// move was still free. These three cannot take that route: they have filed clinical data behind
// them, so the address they carry cannot be changed by editing a constant.
//
// The specification therefore states where they belong and the software is, for now, nonconformant
// on the URL. That is the honest way round: a guide that adopts every address its implementation
// happens to have minted has no canonical base at all, and the alternative -- publishing each of
// them again on a foreign host to match -- would ratify the divergence in the one document that
// could still name it.
//
// WHAT A WRITER SHOULD DO. Write the canonicals declared here. A writer still emitting the
// `services.well.com` URLs is producing notes this guide does not describe; the two are the same
// extension under two names, and nothing reconciles them automatically.
//
// WHAT A READER SHOULD EXPECT. Both addresses, for as long as filed notes carry the old one. A
// reader that resolves only the canonicals below will silently miss billing, sharing and the editor
// setup on every note written before the writers move. Matching on the URL suffix
// (`composition-billing`, `composition-ehr-share`, `composition-note-setup`) is what reads both.
//
// THE MIGRATION IS NOT SCOPED HERE and is larger than these three extensions: `Composition` is not
// the only resource carrying `services.well.com` identifiers and extensions, and the general
// question of what happens to that namespace is an estate-wide one. What this file settles is where
// these three belong, which is the part that could be settled without moving data.
//
// MOVING THE WRITER, AND THE STORED NOTES BEHIND IT, IS TRACKED AS FHIR-370. The handbook states
// the rule and indexes every published artifact in this position: see
// `docs/guide/patterns/canonical-urls.md`.
// ────────────────────────────────────────────────────────────────────────────────────────────────

Extension: CompositionBilling
Id: composition-billing
Title: "Composition Billing Extension"
Description: """
The billing raised for the visit this note documents: the service code, the diagnostic codes
supporting it, and the units where the fee code is charged per unit.

**A complex extension rather than a `Claim`.** R4 gives `Composition` no element for billing, and a
separate `Claim` has its own lifecycle: it is submitted, adjudicated, reassessed and can be written
off, all without the note changing. Carrying the billing on the note keeps what the clinician
entered at closeout attached to what they wrote, which is the question this element answers. A
`Claim` raised from it answers a different one and is expected to exist alongside.

**Code systems are provincial and are not constrained here.** The service and diagnostic codes are
`Coding`, and the system names the provincial schedule they were drawn from. A guide-level binding
would have to pick a province.

**FIRST PASS.** This extension is declared from its production shape rather than from a modelling
pass. See the file comment for the canonical it publishes under and why that is not the URL the
software writes today.

**MIGRATION.** Nexus EMR writes this extension today at
`http://services.well.com/fhir/StructureDefinition/composition-billing`. That address is live in
stored notes and in code, and is under migration to the canonical declared here (FHIR-370). Write
the canonical; when reading, match on the URL suffix `composition-billing` so that notes filed
under either address are seen.
"""
* ^url = "../StructureDefinition/composition-billing"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "Composition"
* value[x] 0..0
* extension contains
    code 1..1 MS and
    dx 0..* MS and
    units 0..1 MS
* extension[code] ^short = "The service (fee) code billed for the visit"
* extension[code].value[x] 1..1 MS
* extension[code].value[x] only Coding
* extension[code].valueCoding ^definition = "The service code, with `system` naming the provincial fee schedule it was drawn from."
* extension[dx] ^short = "A diagnostic code supporting the claim; repeats"
* extension[dx].value[x] 1..1 MS
* extension[dx].value[x] only Coding
* extension[dx].valueCoding ^definition = "A diagnostic code supporting the claim. REPEATS: a claim routinely carries more than one, and a reader taking only the first has a different claim than the clinician entered."
* extension[units] ^short = "Units billed; present only for a per-unit fee code"
* extension[units].value[x] 1..1 MS
* extension[units].value[x] only unsignedInt
* extension[units].valueUnsignedInt ^definition = "Units billed. Absent means the fee code is not charged per unit, NOT that one unit was billed."

Extension: CompositionEhrShare
Id: composition-ehr-share
Title: "Composition EHR Share Extension"
Description: """
One completed share of this signed note to an EHR outside the practice. Repeats: a note shared three
times carries three.

**Completed shares only.** A share still in flight is not recorded. This element is read back to
patients as a disclosure record, and listing a pending share would tell a patient their record went
somewhere it has not yet gone.

**The destination is a string, not `Reference(Organization)`.** It is routinely an external system
with no Organization in this practice's directory, and a reference that cannot resolve is worse than
a name that can be read.

**FIRST PASS.** This extension is declared from its production shape rather than from a modelling
pass. See the file comment for the canonical it publishes under and why that is not the URL the
software writes today.

**MIGRATION.** Nexus EMR writes this extension today at
`http://services.well.com/fhir/StructureDefinition/composition-ehr-share`. That address is live in
stored notes and in code, and is under migration to the canonical declared here (FHIR-370). Write
the canonical; when reading, match on the URL suffix `composition-ehr-share` so that notes filed
under either address are seen.
"""
* ^url = "../StructureDefinition/composition-ehr-share"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "Composition"
* value[x] 0..0
* extension contains
    sharedWith 1..1 MS and
    sharedAt 1..1 MS
* extension[sharedWith] ^short = "The EHR the note was shared with"
* extension[sharedWith].value[x] 1..1 MS
* extension[sharedWith].value[x] only string
* extension[sharedWith].valueString ^definition = "The EHR the note was shared with, named as a string because the destination is routinely external to this practice's directory."
* extension[sharedAt] ^short = "When the share completed"
* extension[sharedAt].value[x] 1..1 MS
* extension[sharedAt].value[x] only dateTime
* extension[sharedAt].valueDateTime ^definition = "When the share completed. Required: an undated disclosure cannot be reported to a patient truthfully."

Extension: CompositionNoteSetup
Id: composition-note-setup
Title: "Composition Note Setup Extension"
Description: """
The editor setup an encounter note was opened on: the visit type the provider chose, and the
template the note started from. Present so that a draft reopens on the footing it was left on
rather than as a blank note.

**Both parts or neither.** A reader that finds only one of the two has no usable setup -- a
template without its visit type cannot be offered again, and a visit type without its template
does not say what the note started as -- so both sub-extensions are required when the extension is
present. The extension itself is optional and is absent on notes written before it existed.

**It records what the note was OPENED FROM, not what it contains.** A provider may switch templates
mid-note, delete every heading the template gave, or type their own. The authoritative structure of
a note is always `Composition.section`; this element is editor state, and a consumer reconstructing
the note's content from the template code rather than from the sections will be wrong.

**The two vocabularies are separate systems, and the template one is NOT the stored template
registry.** `encounter-note-template` names the fixed catalogue of note structures compiled into the
application. `CodeSystem/nexus-template` is a different value space -- the per-tenant slugs of
template `List` resources, which a letter carries on `meta.tag` to say which stored template it was
composed from. Both are kebab-case slugs and they are not interchangeable.

**Both bindings are extensible, deliberately.** Each set is closed in the application today, but a
required binding would make this guide a release gate on the note editor: ship a template and every
note carrying one is nonconformant until the guide cuts a release. A reader that meets an
unrecognised code MUST write it back unchanged; normalising it destroys the record of what the
provider actually started from.

**FIRST PASS.** This extension is declared from its production shape rather than from a modelling
pass. See the file comment for the canonical it publishes under and why that is not the URL the
software writes today.

**MIGRATION.** Nexus EMR writes this extension today at
`http://services.well.com/fhir/StructureDefinition/composition-note-setup`. That address is live in
stored notes and in code, and is under migration to the canonical declared here (FHIR-370). Write
the canonical; when reading, match on the URL suffix `composition-note-setup` so that notes filed
under either address are seen.
"""
* ^url = "../StructureDefinition/composition-note-setup"
* ^status = #draft
* ^date = "2026-09-07"
* ^context[0].type = #element
* ^context[0].expression = "Composition"
* value[x] 0..0
* extension contains
    visitType 1..1 MS and
    template 1..1 MS
* extension[visitType] ^short = "The visit type the note was opened on"
* extension[visitType].value[x] 1..1 MS
* extension[visitType].value[x] only code
* extension[visitType].valueCode from EncounterVisitTypesVS (extensible)
* extension[visitType].valueCode ^definition = "The visit type the provider chose before writing, which is what selects the templates offered. It is NOT `Encounter.class` and makes no claim about the care setting. Required alongside `template`: a template without its visit type cannot be offered again."
* extension[template] ^short = "The template the note was opened from"
* extension[template].value[x] 1..1 MS
* extension[template].value[x] only code
* extension[template].valueCode from EncounterNoteTemplatesVS (extensible)
* extension[template].valueCode ^definition = "The template the note started from, naming a structure in the application's note catalogue -- NOT a slug in the stored template registry that `CodeSystem/nexus-template` names. It records what the note was opened from and not what it now contains: the authoritative structure is `Composition.section`."