fhirsmith 0.14.1 → 0.15.0

package/tx/workers/validate.js

@@ -285,7 +285,10 @@ class ValueSetChecker {
   }
 
   seeValueSet() {
-    this.worker.opContext.seeContext(this.valueSet.vurl);
+    const key = this.valueSet.contextKey !== undefined ? this.valueSet.contextKey : this.valueSet.vurl;
+    if (key) {
+      this.worker.opContext.seeContext(key);
+    }
     if (this.valueSet.jsonObj.compose && this.valueSet.jsonObj.compose.extension) {
       for (let ext of this.valueSet.jsonObj.compose.extension) {
         if (ext.url === 'http://hl7.org/fhir/StructureDefinition/valueset-expansion-parameter' || ext.url === 'http://hl7.org/fhir/tools/StructureDefinition/valueset-expansion-parameter') {
@@ -305,8 +308,22 @@ class ValueSetChecker {
   async prepare() {
     if (this.valueSet === null) {
       throw new Issue('error', 'not-found', null, null, 'Error Error: vs = nil', null, 422);
-    } else {
-      this.seeValueSet();
+    }
+    // circular reference detection: this value set is in the chain being processed until
+    // it's prepared (which prepares everything it imports)
+    this.seeValueSet();
+    try {
+      await this.prepareSeen();
+    } finally {
+      const key = this.valueSet.contextKey !== undefined ? this.valueSet.contextKey : this.valueSet.vurl;
+      if (key) {
+        this.worker.opContext.unseeContext(key);
+      }
+    }
+  }
+
+  async prepareSeen() {
+    {
       this.worker.opContext.addNote(this.valueSet, 'Analysing ' + this.valueSet.vurl + ' for validation purposes', this.indentCount);
       if (this.indentCount === 0) {
         this.worker.opContext.addNote(this.valueSet, 'Parameters: ' + this.params.summary(), this.indentCount);
@@ -569,9 +586,14 @@ class ValueSetChecker {
             if (msg) {
               op.addIssue(new Issue('information', 'informational', addToPath(path, 'code'), null, msg, 'process-note'));
             }
-            inactive.value = await cs.isInactive(ctxt.context);
-            inactive.path = path;
-            vstatus.value = await cs.getStatus(ctxt.context);
+            // in a CodeableConcept a later coding must not clear the inactive status an earlier
+            // coding found, or the warning silently disappears when the inactive coding comes first
+            if (!inactive.value) {
+              inactive.value = await cs.isInactive(ctxt.context);
+              inactive.path = path;
+              inactive.code = code;
+              vstatus.value = await cs.getStatus(ctxt.context);
+            }
           }
           if (displays !== null) {
             await this.worker.listDisplaysFromCodeSystem(displays, cs, ctxt.context);
@@ -925,6 +947,7 @@ class ValueSetChecker {
     let pdisp;
     let psys;
     let pcode;
+    let ppath; // the path of the coding that is returned
     let pver;
 
 
@@ -1063,6 +1086,7 @@ class ValueSetChecker {
         if (pcode === undefined) {
           psys = c.system;
           pcode = c.code;
+          ppath = path;
           if (ver.value) {
             pver = ver.value;
           }
@@ -1185,6 +1209,7 @@ class ValueSetChecker {
             if (!this.params.membershipOnly && !inactive.value && await prov.isInactive(ctxt.context)) {
               inactive.value = true;
               inactive.path = path;
+              inactive.code = c.code;
               const st = await prov.getStatus(ctxt.context);
               if (st) {
                 vstatus.value = st;
@@ -1340,9 +1365,14 @@ class ValueSetChecker {
     }
 
     if (inactive.value) {
-      result.addParamBool('inactive', inactive.value);
-      if (vstatus.value && vstatus.value !== 'inactive') {
-        result.addParamCode('status', vstatus.value);
+      // the inactive and status parameters describe the code being returned. In a CodeableConcept
+      // the inactive coding may be a different one (or none was returned at all): it still gets
+      // its warning below, but the parameters are not claimed for the returned code
+      if (mode !== 'codeableConcept' || (pcode && inactive.path === ppath)) {
+        result.addParamBool('inactive', inactive.value);
+        if (vstatus.value && vstatus.value !== 'inactive') {
+          result.addParamCode('status', vstatus.value);
+        }
       }
       let mpath = inactive.path;
       if (!mpath) {
@@ -1354,7 +1384,9 @@ class ValueSetChecker {
         mid1 = 'INACTIVE_CONCEPT_FOUND_ADD';
         mm1 = 'inactive';
       }
-      let m = this.worker.i18n.translate(mid1, this.params.HTTPLanguages, [vstatus.value, tcode, mm1]);
+      // report the code that is actually inactive - in a CodeableConcept that isn't necessarily
+      // the first coding (tcode), which is what this message used to name
+      let m = this.worker.i18n.translate(mid1, this.params.HTTPLanguages, [vstatus.value, inactive.code || tcode, mm1]);
       msg(m);
       op.addIssue(new Issue('warning', 'business-rule', mpath, 'INACTIVE_CONCEPT_FOUND', m, 'code-comment'));
     } else if (vstatus.value && vstatus.value.toLowerCase() === 'deprecated') {
@@ -1548,6 +1580,7 @@ class ValueSetChecker {
           if (!this.params.membershipOnly && role !== 'not in') {
             inactive.value = true;
             inactive.path = path;
+            inactive.code = code;
             if (inactive.value) {
               vstatus.value = await cs.getStatus(loc.context);
             }
@@ -1558,6 +1591,7 @@ class ValueSetChecker {
           if (role !== 'not in') {
             inactive.value = true;
             inactive.path = path;
+            inactive.code = code;
             vstatus.value = await cs.getStatus(loc.context);
             let msg = this.worker.i18n.translate('STATUS_CODE_WARNING_CODE', this.params.HTTPLanguages, ['not active', code]);
             messages.push(msg);
@@ -1566,9 +1600,12 @@ class ValueSetChecker {
         } else {
           result = true;
           if (role !== 'not in') {
-            inactive.value = await cs.isInactive(loc.context);
-            inactive.path = path;
-            vstatus.value = await cs.getStatus(loc.context);
+            if (!inactive.value) {
+              inactive.value = await cs.isInactive(loc.context);
+              inactive.path = path;
+              inactive.code = code;
+              vstatus.value = await cs.getStatus(loc.context);
+            }
             if (vcc !== null) {
               if (!vcc.coding) {
                 vcc.coding = [];
@@ -1605,6 +1642,7 @@ class ValueSetChecker {
             if (!this.params.membershipOnly) {
               inactive.value = true;
               inactive.path = path;
+              inactive.code = code;
               vstatus.value = await cs.getStatus(loc);
             }
           } else {
@@ -1618,9 +1656,12 @@ class ValueSetChecker {
             } else if (Extensions.has(cc,'http://hl7.org/fhir/StructureDefinition/valueset-deprecated')) {
               op.addIssue(new Issue('warning', 'business-rule', addToPath(path, 'code'), 'CONCEPT_DEPRECATED_IN_VALUESET', this.worker.i18n.translate('CONCEPT_DEPRECATED_IN_VALUESET', this.params.HTTPLanguages, [cs.system(), code, 'deprecated', vs.vurl]), 'code-comment'));
             }
-            inactive.value = await cs.isInactive(loc);
-            inactive.path = path;
-            vstatus.value = await cs.getStatus(loc);
+            if (!inactive.value) {
+              inactive.value = await cs.isInactive(loc);
+              inactive.path = path;
+              inactive.code = code;
+              vstatus.value = await cs.getStatus(loc);
+            }
             result = true;
             return result;
           }
@@ -1669,6 +1710,7 @@ class ValueSetChecker {
           if (!this.params.membershipOnly) {
             inactive.value = true;
             inactive.path = path;
+            inactive.code = code;
             vstatus.value = await cs.getStatus(loc);
           }
         } else {
@@ -1681,6 +1723,7 @@ class ValueSetChecker {
             if (await cs.isInactive(loc)) {
               inactive.value = true;
               inactive.path = path;
+              inactive.code = code;
               // only replace a status we already have with a real one - a filter context
               // doesn't always carry the status (SNOMED, LOINC), and the assembly reads
               // vstatus for the message wording as well as for the status parameter
@@ -1718,9 +1761,12 @@ class ValueSetChecker {
       }
     } else {
       result = true;
-      inactive.value = await cs.isInactive(loc.context);
-      inactive.path = path;
-      vstatus.value = await cs.getStatus(loc.context);
+      if (!inactive.value) {
+        inactive.value = await cs.isInactive(loc.context);
+        inactive.path = path;
+        inactive.code = code;
+        vstatus.value = await cs.getStatus(loc.context);
+      }
       await this.worker.listDisplaysFromCodeSystem(displays, cs, loc.context);
       return result;
     }

package/tx/workers/worker.js

@@ -379,14 +379,22 @@ class TerminologyWorker {
       return null;
     }
     if (url.startsWith("#")) {
+      // A local reference: per FHIR, #id is resolved against the contained resources of
+      // the resource being processed - which, when that is itself a contained value set,
+      // means its container's (contained resources are all siblings in one list)
       if (source) {
-        if (source.jsonObj) {
-          source = source.jsonObj;
-        }
-        for (const contained of source.contained || []) {
-          if (contained.id === url.substring(1)) {
+        const container = source.container || source;
+        const json = container.jsonObj || container;
+        for (const contained of json.contained || []) {
+          if (contained && contained.id === url.substring(1)) {
+            if (contained.resourceType !== 'ValueSet') {
+              // the resource wrappers already reject this; this is the second line of defence
+              throw new Issue('error', 'not-supported', null, 'CONTAINED_RESOURCE_NOT_SUPPORTED',
+                `The reference '${url}' is to a contained ${contained.resourceType}, not a ValueSet`, 'not-supported', 400);
+            }
             const ret = this.wrapRawResource(contained);
             ret.isContained = true;
+            ret.container = container.jsonObj ? container : this.wrapRawResource(container);
             return ret;
           }
         }
@@ -477,11 +485,24 @@ class TerminologyWorker {
    *   Note: this is the caller's parameters, not this.params - the worker's own
    *   params is null when expanding an imported ValueSet
    */
+  /** The circular reference key seeValueSet tracks for a value set */
+  valueSetContextKey(vs) {
+    return vs.contextKey !== undefined ? vs.contextKey : (vs.url ? (vs.url + (vs.version ? '|' + vs.version : '')) : null);
+  }
+
+  /** Finished processing a value set: see OperationContext.unseeContext */
+  unseeValueSet(vs) {
+    const key = this.valueSetContextKey(vs);
+    if (key) {
+      this.opContext.unseeContext(key);
+    }
+  }
+
   seeValueSet(vs, params) {
     // Build canonical URL from url and version
-    const vurl = vs.url ? (vs.url + (vs.version ? '|' + vs.version : '')) : null;
-    if (vurl) {
-      this.opContext.seeContext(vurl);
+    const key = this.valueSetContextKey(vs);
+    if (key) {
+      this.opContext.seeContext(key);
     }
     // Check for expansion parameter extensions on compose
     if (vs.jsonObj.compose && vs.jsonObj.compose.extension) {

package/utilities/extract-schema-json.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+// The published FHIR specification has a page per resource for its JSON schema
+// (e.g. testreport.schema.json.html), but not the schema itself as a file, so links to
+// testreport.schema.json fail. This walks a tree of published specifications and, for each
+// X.schema.json.html, takes the content of its <pre> element and writes it as X.schema.json
+// beside it.
+//
+//   node utilities/extract-schema-json.js <dir> [<dir> ...] [--dry-run] [--force] [--verbose]
+//
+//   --dry-run  report what would be written, but write nothing
+//   --force    overwrite an existing X.schema.json whose content differs (by default it's
+//              left alone and reported)
+//   --verbose  list every file written or skipped
+//   --no-recurse  only look in the named directories themselves, not below them
+//
+// It can be stopped and run again: files already written are reported as up to date.
+//
+// A page is skipped (and reported) if it doesn't have exactly one <pre>, or if the content
+// isn't valid JSON. Symbolic links are not followed. Exit status is 1 if anything was
+// skipped for a problem, so it can be run in a script.
+
+const fs = require('fs');
+const path = require('path');
+
+const SUFFIX = '.schema.json.html';
+
+const NAMED_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: '\'', nbsp: ' ' };
+
+function decodeEntities(text) {
+  return text.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (m, e) => {
+    if (e[0] === '#') {
+      const code = e[1] === 'x' || e[1] === 'X' ? parseInt(e.substring(2), 16) : parseInt(e.substring(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : m;
+    }
+    const v = NAMED_ENTITIES[e.toLowerCase()];
+    return v === undefined ? m : v;
+  });
+}
+
+/**
+ * The text with the markup removed. Repeated until nothing changes, so that removing one tag
+ * can't leave another behind (<a<b>>).
+ */
+function stripTags(html) {
+  let text = html;
+  let previous;
+  do {
+    previous = text;
+    text = text.replace(/<[^<>]*>/g, '');
+  } while (text !== previous);
+  return text;
+}
+
+/**
+ * The schema in a page: the text of its one <pre> element, with any markup removed and
+ * entities decoded.
+ *
+ * @param {string} html
+ * @returns {{json?: string, problem?: string}}
+ */
+function extractSchema(html) {
+  const pres = [...html.matchAll(/<pre\b[^>]*>([\s\S]*?)<\/pre>/gi)];
+  if (pres.length !== 1) {
+    return { problem: pres.length === 0 ? 'no <pre> element' : `${pres.length} <pre> elements` };
+  }
+  // entities are decoded after the markup is gone: a decoded < is the schema's own text
+  const text = decodeEntities(stripTags(pres[0][1])).trim() + '\n';
+  try {
+    JSON.parse(text);
+  } catch (e) {
+    return { problem: 'the <pre> content is not valid JSON: ' + e.message };
+  }
+  return { json: text };
+}
+
+async function* walk(dir, recurse = true) {
+  let handle;
+  try {
+    handle = await fs.promises.opendir(dir);
+  } catch (e) {
+    console.error(`Cannot read ${dir}: ${e.message}`);
+    return;
+  }
+  for await (const entry of handle) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (recurse) {
+        yield* walk(p);
+      }
+    } else if (entry.isFile() && entry.name.endsWith(SUFFIX)) {
+      yield p;
+    }
+  }
+}
+
+async function run(roots, options = {}) {
+  const counts = { pages: 0, written: 0, unchanged: 0, different: 0, problems: 0 };
+  const log = (msg) => options.verbose && console.log(msg);
+  for (const root of roots) {
+    for await (const page of walk(root, !options.noRecurse)) {
+      counts.pages++;
+      const target = page.slice(0, -'.html'.length);
+      const { json, problem } = extractSchema(await fs.promises.readFile(page, 'utf8'));
+      if (problem) {
+        counts.problems++;
+        console.warn(`${page}: ${problem}`);
+        continue;
+      }
+      let existing = null;
+      try {
+        existing = await fs.promises.readFile(target, 'utf8');
+      } catch (e) {
+        // not there yet
+      }
+      if (existing === json) {
+        counts.unchanged++;
+        continue;
+      }
+      if (existing !== null && !options.force) {
+        counts.different++;
+        console.warn(`${target}: exists with different content - left alone (--force to overwrite)`);
+        continue;
+      }
+      if (!options.dryRun) {
+        await fs.promises.writeFile(target, json);
+      }
+      counts.written++;
+      log(`${options.dryRun ? 'would write' : 'wrote'} ${target}`);
+    }
+  }
+  return counts;
+}
+
+async function main(args) {
+  const options = {
+    dryRun: args.includes('--dry-run'),
+    force: args.includes('--force'),
+    verbose: args.includes('--verbose'),
+    noRecurse: args.includes('--no-recurse')
+  };
+  const roots = args.filter(a => !a.startsWith('--'));
+  if (roots.length === 0) {
+    console.error('usage: extract-schema-json.js <dir> [<dir> ...] [--dry-run] [--force] [--verbose] [--no-recurse]');
+    process.exit(2);
+  }
+  const start = Date.now();
+  const c = await run(roots, options);
+  console.log(`${c.pages} schema pages: ${c.written} ${options.dryRun ? 'to write' : 'written'}, ` +
+    `${c.unchanged} already up to date, ${c.different} existing and different (left alone), ` +
+    `${c.problems} with problems (${((Date.now() - start) / 1000).toFixed(1)}s)`);
+  process.exit(c.problems > 0 ? 1 : 0);
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}
+
+module.exports = { extractSchema, decodeEntities, run };

package/utilities/generate-openapi-schemas.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+// Generates a module's FHIR component schemas for its OpenAPI description, from the
+// StructureDefinitions in a FHIR package (see library/fhir-openapi-schema.js).
+//
+//   node utilities/generate-openapi-schemas.js <module> [-package <dir>]
+//
+// reads <module>/openapi-schemas.config.js and writes <module>/openapi-schemas.json. The
+// package is found in the server's terminology cache unless -package names the unpacked
+// package directory.
+
+const fs = require('fs');
+const path = require('path');
+const { generateSchemas } = require('../library/fhir-openapi-schema');
+
+function packageDir(id) {
+  const folders = require('../library/folder-setup');
+  return folders.filePath('terminology-cache', id, 'package');
+}
+
+function main(args) {
+  const module = args[0];
+  if (!module) {
+    console.error('usage: generate-openapi-schemas.js <module> [-package <dir>]');
+    process.exit(2);
+  }
+  const moduleDir = path.join(__dirname, '..', module);
+  const config = require(path.join(moduleDir, 'openapi-schemas.config.js'));
+  const i = args.indexOf('-package');
+  const dir = i >= 0 ? args[i + 1] : packageDir(config.package);
+  if (!fs.existsSync(dir)) {
+    console.error(`The package ${config.package} isn't at ${dir}. Load it into the terminology cache, or use -package <dir>`);
+    process.exit(1);
+  }
+  const out = path.join(moduleDir, 'openapi-schemas.json');
+  fs.writeFileSync(out, JSON.stringify(generateSchemas(config, dir), null, 2) + '\n');
+  console.log(`Wrote ${out}`);
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}
+
+module.exports = { packageDir };

package/xig/xig.js

@@ -397,8 +397,7 @@ async function gatherPageStatistics() {
       downloadDate: downloadDate,
       totalResources: tableCounts.resources || 0,
       totalPackages: tableCounts.packages || 0,
-      processingTime: processingTime,
-      version: getMetadata('fhir-version') || '4.0.1'
+      processingTime: processingTime
     };
 
   } catch (error) {
@@ -411,8 +410,7 @@ async function gatherPageStatistics() {
       downloadDate: 'Error',
       totalResources: 0,
       totalPackages: 0,
-      processingTime: processingTime,
-      version: '4.0.1'
+      processingTime: processingTime
     };
   }
 }