Requisition Signature Extension

Canonical	../StructureDefinition/nexus-requisition-signature
Status	draft · 1.26.0
Base	Extension (constraint)
Context	ServiceRequest (element)
Source	FSH · JSON

The clinician's electronic signature on a laboratory requisition: who signed it, and when.

FSH

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

// RequisitionSignatureExtension.fsh
// The clinician's electronic signature on a laboratory requisition: who signed it, and when.
//
// WHAT THIS RECORDS: the provincial laboratory requisition prints a signature line, and a sheet
// that has been signed is a different document from one that has not. What exists is an assertion
// by the authenticated user, recorded at the moment they signed, with no digest and no key.
//
// THE REASON RECORDED HERE FOR NOT USING R4's `Signature` DATATYPE WAS WRONG ON THE FACTS. It said
// `Signature` "expects signed content and a blob". It does not: `Signature.data` is `0..1`, and a
// Signature carrying none is structurally valid. And `Signature.type` binds
// `urn:iso-astm:E1762-95:2013` at PREFERRED strength -- a vocabulary of ATTESTATION kinds, not
// algorithms, whose first code is `1.2.840.10065.1.12.1.1` |Author's Signature|. That is precisely
// what a clinician signing a requisition is doing. So "it would dress an attestation up as a
// cryptographic guarantee" does not follow: the datatype is built for attestations and makes the
// cryptographic half optional.
//
// SO THE TARGET IS `value[x] only Signature`, ON THIS SAME EXTENSION. The choice was never
// extension-versus-no-extension -- R4's `ServiceRequest` has no signature element, so an extension
// is needed either way. The choice is whether that extension's value is a PUBLISHED datatype or
// bespoke children, and `Signature` carries every fact this one does:
//
//     type    1..*  the attestation kind -- Author's Signature
//     when    1..1  the moment, which `signed` carries today
//     who     1..1  the signer, which `signer` carries today, `display` included
//     data    0..1  omitted, and legal to omit
//
// A consumer that has met `Signature` anywhere else reads it with no reference to this guide, which
// is the whole argument for a published datatype over three bespoke children.
//
// NOT RETYPED HERE, and the reason is the same as everywhere else in this release: a producer
// writes the current shape, and retyping the element in the guide alone would publish a contract
// nothing meets and make every signed requisition on a chart nonconformant on re-validation. The
// target is stated; the element moves with the writer.
//
// PRESENCE IS THE FLAG. There is no stored boolean saying whether a requisition is signed; the
// presence of this extension is what says so, and its absence is an unsigned requisition. A
// producer writes it only on a signing write.
//
// AT MOST ONE. A requisition carries one signature line, and a re-sign replaces the signature
// rather than appending one. To see the sequence of signings, read the resource's versions -- each
// stored version carries its own signature, alongside the reason it was written.
//
// WHY THE SIGNER IS A REFERENCE AND THE NAME RIDES ON IT. `signer` resolves to the practitioner
// (or their role) who signed; `signer.display` is the name as it printed on the sheet at that
// moment. Both are stored because a reprint has to reproduce the sheet from the resource alone: a
// clinician who later changes their recorded name must not retroactively change what an issued
// requisition says it was signed by.
//
// NOTHING HERE POINTS AT AN IMAGE. A signature stamp image is not referenced. An earlier shape
// carried a `stamp` child naming a stored document, and it is described below because requisitions
// already on charts still carry it; nothing writes one now. A signature with no stamp is perfectly
// valid -- it prints as the typed name -- so a consumer must never treat a missing stamp as a
// missing or invalid signature.

Extension: NexusRequisitionSignature
Id: nexus-requisition-signature
Title: "Requisition Signature Extension"
Description: """
The clinician's electronic signature on a laboratory requisition: who signed it, and when.

**An attestation, not a cryptographic signature -- and R4's `Signature` datatype is built for
exactly that.** Its `type` binds ISO/ASTM E1762 attestation kinds (`Author's Signature` among them)
rather than algorithms, and `data` is optional, so a signature with no digest and no key is valid.
A future revision of this extension carries a `Signature` as its value for that reason; what follows
describes the shape written today. This is not the R4 `Signature` datatype and
carries no digest, no signed blob and no key. It records that the authenticated user asserted the
requisition at a moment in time. A consumer must not present it as a verifiable cryptographic
signature.

**Presence is the flag.** There is no separate stored boolean. A requisition carrying this
extension is signed; one without it is not.

**At most one, and a re-sign replaces it.** The form prints one signature line. The sequence of
signings is read from the resource's version history, where each stored version carries the
signature it was written with and, separately, the reason that version was written.

**The signer's name is stored on the reference, deliberately.** `signer.display` is the name as it
printed on the sheet when it was signed. A reprint must reproduce the issued document from the
resource alone, so a later change to the practitioner's recorded name does not change what an
already-issued requisition says.

**No stamp image is referenced.** A signature prints as the typed name. The `stamp` child below is
read-only legacy and must never be produced; its absence carries no meaning about validity.
"""
* ^url = "../StructureDefinition/nexus-requisition-signature"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "ServiceRequest"
* . ^short = "The clinician's electronic signature on the requisition -- who, and when"
* value[x] 0..0

* extension contains
    signer 1..1 MS and
    signedAt 1..1 MS and
    stamp 0..1

* extension[signer].value[x] only Reference(Practitioner or PractitionerRole)
* extension[signer] ^short = "Who signed -- the ordering clinician, as a PractitionerRole where one resolved"
* extension[signer] ^definition = "The clinician who signed the requisition. A `PractitionerRole` where the signing context resolved one, otherwise the `Practitioner`. `display` carries the name exactly as it printed on the signed sheet and is stored so a reprint does not change when the practitioner record does."

* extension[signedAt].value[x] only dateTime
* extension[signedAt] ^short = "When the requisition was signed -- a fully-qualified instant"
* extension[signedAt] ^definition = "The moment the requisition was signed, as a timezone-qualified dateTime. This is the time of the signing write, which is not the same as `ServiceRequest.authoredOn`: authoring is preserved across an amendment while the signature is stamped afresh, so the two differ on any requisition that has been edited."

* extension[stamp].value[x] only string
* extension[stamp] ^short = "LEGACY, read-only: identifier of a stored signature-stamp document"
* extension[stamp] ^definition = "The identifier of a stored document holding the signer's stamp image, as captured at sign time. **Deprecated: no producer writes this, and none should.** It is described because requisitions signed under an earlier shape still carry it and must keep rebuilding exactly as they did. Its absence says nothing about the validity of a signature -- an unstamped signature prints as the typed name and is fully valid."