Skip to main content
Version: v0.1.10

Check a document type's required sections

REQUIRED_SECTION_MISSING tells you a section this package expects is absent. Before you route on that, you need to know how much of that document type's obligation this package has actually read off the normative source, and whether it evaluated the obligation at all.

requiredSectionKeys gives the asserted SHALL keys for a type. missingRequiredSections diffs them against the sections you framed. requiredSectionStatus is the honest surface behind both: it carries the keys plus the provenance of each one, plus two independent state axes.

  • verification is a claim about the type: traced-complete, traced-partial, untraced, or not-applicable. How much of that type's obligation was read off the normative artifact.
  • evaluation is a claim about the lookup: evaluated or not-evaluated. Whether the version stamp you supplied put the document inside the tables at all.

That split is the point. An empty keys set is never ambiguous, because the two states together say which emptiness it is: nothing required, nothing asserted, or nothing asked.

import { requiredSectionKeys, missingRequiredSections, requiredSectionStatus } from "@cosyte/ccda";

// A CCD's obligation is fully traced to the normative artifact, and every key
// carries the conformance statement it was read from.
const ccd = requiredSectionStatus("ccd");
ccd.verification; // => "traced-complete"
ccd.evaluation; // => "evaluated"
ccd.keys; // => ["allergies", "medications", "problems", "results", "socialHistory", "vitalSigns"]
ccd.traced[0]?.conformanceId; // => "CONF:1198-30662"
ccd.source?.revision; // => "2025-09-08"

// Same keys, without the provenance, from the lighter accessor.
requiredSectionKeys("ccd"); // => ["allergies", "medications", "problems", "results", "socialHistory", "vitalSigns"]

// What a document that framed only two of them is missing.
missingRequiredSections("ccd", new Set(["allergies", "problems"])); // => ["medications", "results", "socialHistory", "vitalSigns"]

// EMPTY BECAUSE NOTHING IS REQUIRED: an Unstructured Document carries no
// structuredBody at all, so the obligation does not apply to it.
const unstructured = requiredSectionStatus("unstructuredDocument");
unstructured.verification; // => "not-applicable"
unstructured.keys; // => []

// EMPTY BECAUSE NOTHING WAS ASKED: the document names a C-CDA release this
// package has not read. Reducing the obligation instead would be a confident
// wrong statement about conformance.
const future = requiredSectionStatus("ccd", { stamp: "unmodeled-release" });
future.evaluation; // => "not-evaluated"
future.keys; // => []

Two readings that are easy to get backwards, and both are load-bearing:

  • An unmodelled version stamp reports the obligation unevaluated, never reduced. It is not the same as the R1.1-origin reduction, which applies to a document carrying no stamp at all and does drop the R2.1-scoped keys (requiredSectionKeys("ccd", { r21Stamped: false }) returns four, not six). Treating a future release like an old one is how a document silently loses Social History and Vital Signs.
  • unasserted is not a gap list. It names SHALL sections the source states that this package deliberately does not assert, each with one of three reasons: the section is outside the recognized catalog (outside-section-catalog), the source requires it only conditionally (not-unconditionally-required), or the parser recognizes it and asserting it would make the parse of documents that omit it stricter (assertion-would-tighten-parse, today only the Discharge Summary's Hospital Course). Asserting a SHOULD, or one half of a choice, mis-flags a conformant document, which is the same defect as missing a SHALL with the sign flipped.

requiredSectionStatuses() returns the status for every recognized document type at once, which is the call to make if you are building a conformance dashboard rather than checking one document.

Reference​

Types you will import here: RequiredSectionStatus (the whole record), RequiredSectionVerification and RequiredSectionEvaluation (the two state axes above), RequiredSectionOptions (the r21Stamped and stamp inputs), RequiredSectionSource (the normative artifact and its own revision date), TracedRequiredSection (one asserted key with its CONF: statement) and UnassertedRequiredSection with UnassertedSectionReason (a named SHALL section this package does not assert, and which of the three reasons above applies).