Summary Payload Extension

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

A generated summary's structured result, as a JSON string, on the Composition that files it.

FSH

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

// SummaryPayloadExtension.fsh
// The generated summary's own structured result, carried as a JSON string on the Composition that
// files it.
//
// WHAT IT CARRIES. A machine-generated summary is produced as a set of fields, each holding one or
// more claims: a statement plus the source references and verbatim quotes backing it. The
// Composition renders those claims as narrative sections and the accompanying Provenance carries
// them again, one `nexus-attributed-fact` per claim. This extension carries the same result a
// third time, as the producing capability's own object, so a consumer can render the summary field
// by field without reconstructing structure from prose.
//
// IT IS TRANSITIONAL AND IT IS DECLARED ANYWAY. Nothing in it is a fact the narrative and the
// attributed facts do not already carry, and it exists only because this guide does not yet
// specify a structured read model for a generated summary. What would settle it is that model:
// once a consumer can read a summary's fields and citations from declared elements, this extension
// is withdrawn. Until then it is live on every generated summary in the store, and an undeclared
// extension is the same commitment as a declared one with no description attached -- which is the
// worse of the two, because a reader meets it either way and learns nothing.
//
// SO: A NEW CONSUMER SHOULD READ THE NARRATIVE AND THE ATTRIBUTED FACTS. `section.text` is
// complete on its own and needs no extension to be understood, and `nexus-attributed-fact` on the
// summary's Provenance is the declared, per-claim citation trail. Build on those. Read this only
// where a field-by-field structured view is needed today and the two declared surfaces will not
// give it to you.
//
// THE OBJECT'S SHAPE IS NOT SPECIFIED HERE, DELIBERATELY. Its keys are the summary type's own
// fields, they differ per type, and they move with the producing capability rather than with this
// guide's release cadence. Pinning a snapshot of them into a published artifact would state a
// contract this specification cannot keep. Treat the value as the producer's object: parse it
// defensively, tolerate keys you do not know, and tolerate a missing or unparsable value by
// falling back to the narrative rather than by failing.
//
// IT DOES NOT ANSWER THE AI-ATTRIBUTION QUESTION, and must not be read as if it did. Whether a
// machine produced this content is the `AIAST` security label in `meta.security`, which every
// machine-produced Composition carries and which is the same on every resource type in this
// specification. Which graph produced it is the logical Device on `author`. This extension is the
// summary's content, nothing more; a Composition carrying it is not thereby AI-produced, and a
// Composition without it may well be.
//
// THE CANONICAL HERE IS NOT THE ONE THE SOFTWARE WRITES TODAY. The migration note is in the
// Description below, which is the text that travels inside the package; the handbook states the
// rule and indexes every published artifact in this position, in
// `docs/guide/patterns/canonical-urls.md`.

Extension: NexusSummaryPayload
Id: nexus-summary-payload
Title: "Summary Payload Extension"
Description: """
A generated summary's structured result, as a JSON string, on the `Composition` that files it.

**THE CARRIER IS WRONG, AND THIS GUIDE SAYS SO ELSEWHERE IN THE SAME RELEASE. It should be an
`Attachment` with `contentType = application/json`, not a `valueString`.** The composition-block
payload extension states the rule plainly: *"A JSON string in a `valueString` is self-describing to
nobody: a reader cannot tell what it holds without recognising the render kind first, and no
published international IG carries editor state that way. `Attachment` is what R4 already provides
for an opaque payload, and `contentType` makes the envelope readable even where the contents are
not."*

Every word of that applies here. This payload is opaque by design -- its keys are the producing
capability's own and are explicitly not specified below -- so a consumer that does not recognise the
summary kind cannot tell a JSON object from a sentence, and nothing in the element says which it is.
`Attachment` answers that without saying anything about the contents: `contentType` declares the
envelope, `data` carries the bytes, and `language` and `creation` are there if ever wanted.

One release, one question, two answers. The other one is right, and it was argued at length forty
lines away from this file.

**Transitional.** It carries no fact the summary's own narrative and its `nexus-attributed-fact`
citations do not also carry. It exists because this guide does not yet specify a structured read
model for a generated summary, and it is withdrawn once one is declared. A new consumer should read
`section.text` -- which is complete on its own -- and the per-claim citation trail on the summary's
`Provenance`, and should reach for this only where a field-by-field structured view is needed today.

**The object's shape is not specified here.** Its keys are the summary type's own fields, they
differ between summary kinds, and they move with the producing capability rather than with this
guide. Parse defensively, tolerate unknown keys, and fall back to the narrative when the value is
missing or unparsable rather than failing.

**It is not an AI-attribution signal.** Whether a machine produced the content is the `AIAST`
security label in `meta.security`; which graph produced it is the logical `Device` on `author`.
Presence or absence of this extension says nothing about either.

**Readers should expect two canonicals.** This publishes under this guide's base; Nexus EMR writes
it today at `https://nexus.awaremd.com/summary-id/StructureDefinition/summary-payload` (FHIR-377),
an address this specification does not publish. It is live in stored `Composition.extension` values
and in code, and is under migration to the canonical declared here. Match both addresses exactly.
The two do not share a final segment, so a suffix rule does not reach the pre-migration one and a
reader built on it misses every summary written before the writer moves.
"""
* ^url = "../StructureDefinition/nexus-summary-payload"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "Composition"
* extension 0..0
* url 1..1
// STILL `string`, DELIBERATELY, AND THIS IS THE ONE THING NOT FIXED IN THE SPEC HERE. The frontend
// writes a valueString today (frontend/lib/fhir/.../generated-summary.ts). Retyping the element to
// `Attachment` in the guide alone would publish a contract no producer meets and make every stored
// summary nonconformant on re-validation, for a reader that does not exist yet. The description
// above states the target; the element follows the writer rather than leading it, and both move in
// the same change.
* value[x] 1..1 MS
* value[x] only string
* valueString ^short = "The summary's structured result, as a JSON object serialized to a string"
* valueString ^definition = "The producing capability's own summary object, serialized as JSON. Keys are the summary type's own fields and are not specified by this guide. Not base64, not a pointer -- the JSON text itself."