Requisition Form Answers Extension

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

The keyed answers written onto a laboratory requisition: the dependent inputs printed beside individual boxes, the check-one category choices, and the insured / uninsured billing choices.

FSH

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

// RequisitionAnswersExtension.fsh
// The keyed answers written onto a laboratory requisition: the dependent inputs printed beside
// individual boxes, the check-one category choices, and the insured / uninsured billing choices.
//
// WHY ONE KEYED LIST AND NOT THREE EXTENSIONS. The three kinds are all the same thing -- an answer
// written on the form -- and the key says which question was answered. Three near-identical
// extensions would make a consumer learn three shapes to read one concept, and every new kind of
// question the ministry adds to the form would be a fourth. The key prefix carries the kind, so the
// shape is stable while the form's vocabulary is not.
//
// WHY IT IS NOT A QUESTIONNAIRERESPONSE -- AND THE FIRST REASON GIVEN FOR THAT WAS WRONG.
//
// The reason recorded here was that a QuestionnaireResponse is a resource in its own right, with
// its own identity, status and lifecycle, while these answers are not separable from the
// requisition: marks on one printed sheet, reproduced from the order alone, with nothing that can
// be deleted independently.
//
// A CONTAINED QuestionnaireResponse HAS EXACTLY THOSE PROPERTIES. A contained resource has no
// independent identity, cannot be addressed, deleted or versioned on its own, and travels with its
// parent always -- which is the whole of the inseparability this file asked for. R4 puts it on
// `ServiceRequest.contained` with `supportingInfo` pointing at the internal reference. So the
// objection as written does not survive, and it should not be the reason.
//
// THE REASON THAT DOES SURVIVE IS DIFFERENT, AND SHARPER: THERE IS NO QUESTIONNAIRE TO POINT AT.
// A QuestionnaireResponse's items mean what the Questionnaire it references says they mean. This
// guide deliberately does not enumerate the provincial form's keys -- the ministry republishes the
// form on its own cadence and an enumeration inside a specification starts drifting the day it is
// written -- so there is no Questionnaire, and this guide's own QuestionnaireResponse profile says
// what that costs: "a response with no `questionnaire` still cannot be interpreted beyond its own
// display text, because nothing states what the items mean." A contained response would carry the
// same opaque keys, in more machinery, with a `questionnaire` element left empty.
//
// AND ONE THING THE CONTAINED SHAPE WOULD GENUINELY BUY, which is worth conceding rather than
// arguing away: TYPED ANSWERS. `answer.value[x]` admits `integer`, `boolean`, `decimal`, `date` and
// `Coding`. A `category:` answer here is a decimal index carried as a STRING, which is the weakest
// part of this design and would simply be an integer there.
//
// WHAT WOULD CHANGE THE ANSWER: publishing a Questionnaire for the provincial form. That is a real
// decision with a real cost -- it is a commitment to track a document this guide does not control --
// and it is the same decision the forms lanes turn on. Until it is taken, the keys are opaque
// wherever they are carried, and carrying them here keeps the requisition self-contained without
// pretending a form definition exists.
//
// KEYS ARE THE FORM'S OWN AND ARE OPAQUE HERE. A key is a prefix naming the kind of question,
// followed by the form's own identifier for the specific input, category or billing choice. Those
// identifiers belong to a particular revision of a particular provincial form. This guide does not
// enumerate them, for the same reason it does not reprint the form: the ministry republishes it on
// its own cadence, and an enumeration inside a specification is a snapshot that starts drifting on
// the day it is written. Treat an unrecognised key as an answer to a question you do not render.
//
// VALUES ARE STRINGS, INCLUDING THE NUMERIC ONE. A `category:` answer's value is a decimal index
// into the printed option list, held as a string. That index is positional and is only meaningful
// against the form revision that produced it.
//
// AN EMPTY LIST IS NOT WRITTEN. A producer emits the extension only when at least one answer
// carries both a key and a value, and drops any pair missing either, so the stored list never
// contains a blank answer.

Extension: NexusRequisitionAnswers
Id: nexus-requisition-answers
Title: "Requisition Form Answers Extension"
Description: """
The keyed answers written onto a laboratory requisition: the dependent inputs printed beside
individual boxes, the check-one category choices, and the insured / uninsured billing choices.

**One keyed list, not three shapes.** Every entry is "an answer written on the form", and its `key`
says which question it answers. A consumer learns one shape and reads all three kinds.

**Why not a `QuestionnaireResponse`.** Not because of separability -- a CONTAINED
QuestionnaireResponse has no independent identity, cannot be deleted or versioned on its own, and
travels with its parent, which is exactly the inseparability a requisition needs. The reason is that
there is no `Questionnaire` for it to reference: this guide does not enumerate the provincial form's
keys, so a response would carry the same opaque keys with its `questionnaire` element empty, and a
response with no questionnaire cannot be interpreted beyond its own display text. What the contained
shape would genuinely buy is TYPED answers -- a `category:` index would be an integer rather than a
decimal held as a string -- and that gain is real. Publishing a Questionnaire for the form is what
would change this answer.

### Reading a key

A key is a prefix naming the kind of question, followed by the form's own identifier for the
specific input, category or billing choice:

| prefix | what the answer answers | what the value holds |
|---|---|---|
| `mod:` | a dependent input printed beside a single box | the text typed onto the ruled line, or the option circled |
| `category:` | a section's check-one category | a decimal index into the printed option list, as a string |
| `billing:` | a section's insured / uninsured choice | the chosen option's value |

**The identifiers after the prefix are the form's own and are not enumerated here.** They belong to
a particular revision of a particular provincial requisition, which is republished on its own
cadence; a copy inside this specification would be a snapshot that starts drifting the day it is
written. A consumer should treat an unrecognised key as an answer to a question it does not render,
and must not fail on one.

**Values are strings, including the numeric one.** A `category:` value is a positional index, held
as a decimal string, and it is meaningful only against the form revision that produced it. It is
not a code and must not be read as one.

**An empty list is not written.** A producer emits the extension only when at least one answer
carries both a key and a value, so a stored entry is never blank.

**At most one, on the order only.** The answers are not echoed onto the `DiagnosticReport` the
requisition eventually produces.
"""
* ^url = "../StructureDefinition/nexus-requisition-answers"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "ServiceRequest"
* . ^short = "The keyed answers written onto the requisition form"
* value[x] 0..0

* extension contains
    answer 1..* MS

* extension[answer] ^short = "One answer written on the form: which question, and what was put"
* extension[answer] ^comment = "Repeats once per answered question. Order is not significant -- a consumer selects by `key` rather than by position."
* extension[answer].extension contains
    key 1..1 MS and
    value 1..1 MS

* extension[answer].extension[key].value[x] only string
* extension[answer].extension[key] ^short = "Which question -- a `mod:` / `category:` / `billing:` prefix, then the form's own identifier"
* extension[answer].extension[key] ^definition = "The question this answer answers. A prefix naming the kind of question (`mod:` for a dependent input printed beside a box, `category:` for a section's check-one choice, `billing:` for a section's insured / uninsured choice) followed by the form's own identifier for that input, category or choice. Those identifiers are specific to a revision of the provincial requisition form and are not enumerated by this guide. A consumer must tolerate a key it does not recognise."

* extension[answer].extension[value].value[x] only string
* extension[answer].extension[value] ^short = "What was answered -- always a string, even where it holds a number"
* extension[answer].extension[value] ^definition = "The answer as stored. For a `mod:` key it is the text typed onto the form's ruled line or the option circled. For a `billing:` key it is the chosen option's value. For a `category:` key it is a decimal index into the section's printed option list, held as a string: that index is positional and is meaningful only against the form revision that produced it, so it is not a code and must not be read as one."