fhirsmith 0.14.0 → 0.14.2

package/tx/README.md

@@ -148,6 +148,64 @@ The file is read from disk per request, so editing it is reflected immediately -
 this means the published file can be ahead of what the running server actually loaded, if it
 has been edited since startup.
 
+## OpenAPI description
+
+Each R5 endpoint is described by an OpenAPI 3.1 spec (the R4 and R3 endpoints work the same
+way, with that version's resources, and aren't described separately):
+
+| URL | |
+|---|---|
+| `/{path}/openapi` | Browsable reference (HTML, in the tx page template), with a "try it" form for each GET operation |
+| `/{path}/openapi.json` | The spec as JSON |
+| `/{path}/openapi.yaml` | The spec as YAML |
+
+`servers` is the endpoint. Every response from an R5 endpoint carries a
+`Link: </{path}/openapi.json>; rel="service-desc", </{path}/openapi>; rel="service-doc"` header
+(RFC 8631), the tx pages carry the matching `<link>` element and an **API** item in the
+navigation bar, and the server home page links to it. The HTML pages (`/`, `/op.html`, `/ecl`,
+`/problems.html`, `/info`, `/library`) aren't described.
+
+The spec is in three parts, merged when it's served ([openapi.js](openapi.js)):
+
+* [openapi.yaml](openapi.yaml) - the overview, `/metadata`, `/$versions`, and the shared
+  components, written by hand
+* [openapi-operations.js](openapi-operations.js) - the terminology operations, as data: their
+  in and out parameters, with types, cardinalities and descriptions. openapi.js makes the paths
+  from them (type and instance level; GET with the primitive parameters in the query, POST with
+  a Parameters resource or a form) and a table of the parameters for each. The parameters
+  TxParameters reads for most operations (tx-resource, cache-id, the version rules,
+  displayLanguage, ...) are listed once, in the overview. The read and search paths are made
+  there too, from the search worker's parameters
+* [openapi-schemas.json](openapi-schemas.json) - the FHIR R5 schemas, generated from the
+  StructureDefinitions by `library/fhir-openapi-schema.js`, as configured in
+  [openapi-schemas.config.js](openapi-schemas.config.js)
+
+The schemas are documentation: they describe what the server handles and returns, but the
+server doesn't reject content outside them. They describe:
+
+* CodeSystem, ValueSet, ConceptMap, OperationOutcome, Parameters, Bundle, CapabilityStatement
+  and TerminologyCapabilities, closed, with the `_x` siblings of primitive elements and
+  `modifierExtension` wherever FHIR allows them
+* contained resources only in a ValueSet, and only ValueSets
+* extension and parameter values: the primitive types (not `base64Binary`), `Coding` and
+  `CodeableConcept`
+* resources in a Bundle or a Parameters: CodeSystem, ValueSet, ConceptMap, OperationOutcome -
+  and Parameters, in a Parameters, for `$batch-validate-code` and `profile`. Never a Bundle
+* OperationOutcome issues with `details.text`, and (except for information) a tx-issue-type
+  coding
+
+After changing the operations, `openapi.js` picks them up. After changing the schema config,
+regenerate (this needs `hl7.fhir.r5.core#5.0.0` in the terminology cache):
+
+    node utilities/generate-openapi-schemas.js tx
+
+`tests/tx/openapi.test.js` fails if a route isn't described (or excluded, with a reason), if a
+worker or TxParameters reads a parameter that isn't described - or a described one isn't read
+anywhere - or if the generated schemas are out of date. It also validates what the server
+actually returns (metadata, read and search, `$expand`, `$validate-code`, `$lookup`,
+`$subsumes`, `$batch-validate-code`, `$versions`, `$cache-control`, an error) against the
+schemas, using ajv. So a new parameter needs adding to openapi-operations.js.
+
 ## Library Configuration
 
 The library - the source to load - is configured using a YAML file.

package/tx/cm/cm-database.js

@@ -349,7 +349,16 @@ class ConceptMapDatabase {
             this.cmCount = rows.length;
 
             for (const row of rows) {
-              const conceptMap = new ConceptMap(JSON.parse(row.content));
+              let conceptMap;
+              try {
+                conceptMap = new ConceptMap(JSON.parse(row.content));
+              } catch (e) {
+                // one unacceptable concept map must not take the rest with it
+                require('../../library/logger').getInstance().child({ module: 'tx' })
+                  .warn(`ConceptMap database: skipping ConceptMap ${row.url || row.id}: ${e.message}`);
+                this.cmCount--;
+                continue;
+              }
 
               // Store by URL and id alone
               conceptMapMap.set(row.url, conceptMap);

package/tx/cm/cm-package.js

@@ -63,7 +63,14 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     for (const entry of conceptMapEntries) {
       const conceptMap = await this.packageLoader.loadFile(entry);
       if (conceptMap.url) {
-        conceptMaps.push(new ConceptMap(conceptMap, this.packageLoader.fhirVersion())); // get in converted to R5 format
+        try {
+          conceptMaps.push(new ConceptMap(conceptMap, this.packageLoader.fhirVersion())); // get in converted to R5 format
+        } catch (e) {
+          // one unacceptable concept map (e.g. one with contained resources, which the
+          // server doesn't support) must not stop the rest of the package loading
+          require('../../library/logger').getInstance().child({ module: 'tx' })
+            .warn(`Package ${this.packageLoader.pid ? this.packageLoader.pid() : ''}: skipping ConceptMap ${conceptMap.url}: ${e.message}`);
+        }
       }
     }
 

package/tx/cs/cs-rxnorm.js

@@ -36,12 +36,27 @@ class RxNormPrep {
 
 // Iterator context
 class RxNormIteratorContext {
-  constructor(query, params = {}) {
+  /**
+   * @param {string|null} query - the SQL that produces the rows, or null for an iterator with no rows
+   * @param {object} params - the query parameters
+   * @param {number} [total] - the number of rows the query will return, if known. The expander
+   *   reads it to refuse an over-limit whole-code-system expansion before it is materialised
+   */
+  constructor(query, params = {}, total = undefined) {
     this.query = query;
     this.params = params;
     this.cursor = 0;
-    this.results = null;
-    this.executed = false;
+    if (query) {
+      this.results = null;
+      this.executed = false;
+      this.total = total;
+    } else {
+      // nothing to run: an empty statement isn't a no-op in node-sqlite3, it fails with
+      // "SQLITE_MISUSE: not an error"
+      this.results = [];
+      this.executed = true;
+      this.total = 0;
+    }
   }
 
   more() {
@@ -288,10 +303,12 @@ class RxNormServices extends CodeSystemProvider {
     if (!context) {
       // Iterate all codes
       const query = `SELECT ${this.getCodeField()}, STR FROM rxnconso WHERE SAB = ? AND TTY <> 'SY' ORDER BY ${this.getCodeField()}`;
-      return new RxNormIteratorContext(query, { sab: this.getSAB() });
+      return new RxNormIteratorContext(query, { sab: this.getSAB() }, this.totalCodeCount);
     } else {
-      // No hierarchical iteration for specific contexts in this implementation
-      return new RxNormIteratorContext('', {});
+      // No hierarchical iteration for specific contexts in this implementation. The expander
+      // asks every concept for its children (includeCodeAndDescendants), so this has to be an
+      // iterator with no rows - not one with an empty query, which sqlite rejects
+      return new RxNormIteratorContext(null, {});
     }
   }
 

package/tx/cs/cs-snomed.js

@@ -16,6 +16,7 @@ const {ConceptMap} = require("../library/conceptmap");
 const {ECLLexer, ECLParser, ECLNodeType, ECLTokenType} = require("../sct/ecl");
 const {Issue} = require("../library/operation-outcome");
 const {debugLog} = require("../operation-context");
+const {editionName, editionCode} = require("../sct/editions");
 const {SnomedTextIndex, rankMatches, filterTokens} = require("../sct/text-index");
 const Logger = require("../../library/logger");
 
@@ -3038,81 +3039,11 @@ class SnomedServicesFactory extends CodeSystemFactoryProvider {
 }
 
 function getEditionName(edition) {
-  const editionMap = {
-    '900000000000207008': 'International Edition',
-    // The terminology-ecosystem test distribution, published under xsct - see the
-    // tx-ecosystem IG, which requires a server claiming the snomed mode to load it.
-    '31000003106': 'Test Edition',
-    '449081005': 'International Spanish Edition',
-    '11000221109': 'Argentinian Edition',
-    '32506021000036107': 'Australian Edition (with drug extension)',
-    '11000234105': 'Austrian Edition',
-    '11000172109': 'Belgian Edition',
-    '20621000087109': 'Canadian English Edition',
-    '20611000087101': 'Canadian Canadian French Edition',
-    '554471000005108': 'Danish Edition',
-    '11000279109': 'Czech Edition',
-    '11000181102': 'Estonian Edition',
-    '11000229106': 'Finnish Edition',
-    '11000274103': 'German Edition',
-    '1121000189102': 'Indian Edition',
-    '827022005': 'IPS Terminology',
-    '11000220105': 'Irish Edition',
-    '11000146104': 'Netherlands Edition',
-    '21000210109': 'New Zealand Edition',
-    '51000202101': 'Norwegian Edition',
-    '11000267109': 'Republic of Korea Edition (South Korea)',
-    '900000001000122104': 'Spanish National Edition',
-    '45991000052106': 'Swedish Edition',
-    '2011000195101': 'Swiss Edition',
-    '83821000000107': 'UK Edition',
-    '999000021000000109': 'UK Clinical Edition',
-    '5631000179106': 'Uruguay Edition',
-    '731000124108': 'US Edition',
-    '21000325107': 'Chilean Edition',
-    '5991000124107': 'US Edition (with ICD-10-CM maps)'
-  };
-
-  return editionMap[edition] || 'Unknown Edition';
+  return editionName(edition) || 'Unknown Edition';
 }
 
 function getEditionCode(edition) {
-  const editionMap = {
-    '900000000000207008': 'Intl',
-    // The terminology-ecosystem test distribution, published under xsct - see the
-    // tx-ecosystem IG, which requires a server claiming the snomed mode to load it.
-    '31000003106': 'Test',
-    '449081005': 'es',
-    '11000221109': 'AR-es',
-    '32506021000036107': 'AU+',
-    '11000234105': 'AT',
-    '11000172109': 'BE',
-    '20621000087109': 'CA-en',
-    '20611000087101': 'CA-fr',
-    '554471000005108': 'DK',
-    '11000279109': 'CZ',
-    '11000181102': 'ES',
-    '11000229106': 'FI',
-    '11000274103': 'DE',
-    '1121000189102': 'IN',
-    '827022005': 'IPS',
-    '11000220105': 'IE',
-    '11000146104': 'NL',
-    '21000210109': 'NZ',
-    '51000202101': 'NO',
-    '11000267109': 'KR',
-    '900000001000122104': 'ES-es',
-    '45991000052106': 'SW',
-    '2011000195101': 'CH',
-    '83821000000107': 'UK',
-    '999000021000000109': 'UK-Clinical',
-    '5631000179106': 'UR',
-    '731000124108': 'US',
-    '21000325107': 'CL',
-    '5991000124107': 'US+)'
-  };
-
-  return editionMap[edition] || 'Unknown Edition';
+  return editionCode(edition) || 'Unknown Edition';
 }
 
 

package/tx/html/tx-template.html

@@ -10,6 +10,7 @@
   <meta charset="utf-8" http-equiv="X-UA-Compatible" content="IE=edge" />
 
   <link rel="stylesheet" href="/fhir.css"/>
+  [%api-head%]
 
     <!-- Bootstrap core CSS -->
   <link rel="stylesheet" href="/assets/css/bootstrap.css"/>
@@ -91,6 +92,7 @@
             <a href="[%endpoint-path%]/op.html" style="color: gold">Operations</a>  &nbsp;|&nbsp;
             <a href="[%endpoint-path%]/ecl" style="color: gold">ECL</a>  &nbsp;|&nbsp;
             <a href="[%endpoint-path%]/problems.html" style="color: gold">Problems</a>  &nbsp;|&nbsp;
+            [%api-link%]
             [%library-link%]
   &nbsp;
 		</div>

package/tx/library/canonical-resource.js

@@ -1,4 +1,45 @@
 const {VersionUtilities, VersionPrecision} = require("../../library/version-utilities");
+const {Issue} = require("./operation-outcome");
+
+/**
+ * Contained resources. The terminology server supports exactly one use of them: a ValueSet
+ * that contains ValueSets, which its compose refers to as #id. Any other contained resource
+ * - a contained CodeSystem or ConceptMap, anything contained in a CodeSystem or ConceptMap,
+ * or a contained ValueSet that itself contains something - is rejected, whatever path the
+ * resource arrives by (request, tx-resource, cache, package). Supporting them would mean
+ * resolving references to them everywhere, and the terminology ecosystem only requires
+ * servers to support contained value sets in value sets.
+ *
+ * @param {Object} jsonObj - the resource (R5 form)
+ * @throws {Issue} if the resource contains anything not supported
+ */
+function checkContained(jsonObj) {
+  const contained = jsonObj ? jsonObj.contained : undefined;
+  if (contained === undefined || contained === null) {
+    return;
+  }
+  const type = jsonObj.resourceType;
+  const which = `${type}${jsonObj.id ? '/' + jsonObj.id : ''}${jsonObj.url ? ' (' + jsonObj.url + ')' : ''}`;
+  if (!Array.isArray(contained)) {
+    throw new Issue('error', 'structure', `${type}.contained`, 'CONTAINED_RESOURCE_NOT_SUPPORTED',
+      `${which}: contained must be an array`, 'invalid-data', 400);
+  }
+  contained.forEach((c, i) => {
+    const ct = c && typeof c === 'object' ? c.resourceType : undefined;
+    let problem = null;
+    if (type !== 'ValueSet') {
+      problem = `${which} contains a ${ct || 'resource'}: this server only supports ValueSets contained in a ValueSet`;
+    } else if (ct !== 'ValueSet') {
+      problem = `${which} contains a ${ct || 'resource with no resourceType'}: this server only supports ValueSets contained in a ValueSet`;
+    } else if (Array.isArray(c.contained) && c.contained.length > 0) {
+      problem = `${which}: the contained ValueSet${c.id ? ' #' + c.id : ''} itself contains resources, which is not allowed`;
+    }
+    if (problem) {
+      throw new Issue('error', 'not-supported', `${type}.contained[${i}]`, 'CONTAINED_RESOURCE_NOT_SUPPORTED',
+        problem, 'not-supported', 400);
+    }
+  });
+}
 
 /**
  * Base class for metadata resources to provide common interface
@@ -31,6 +72,14 @@ class CanonicalResource {
     this.fhirVersion = fhirVersion;
   }
 
+  /**
+   * Rejects contained resources this server doesn't support - see checkContained.
+   * Subclasses call this once the resource is in R5 form.
+   */
+  checkContained() {
+    checkContained(this.jsonObj);
+  }
+
   get resourceType() {
     return this.jsonObj.resourceType;
   }
@@ -163,4 +212,4 @@ class CanonicalResource {
   }
 }
 
-module.exports = { CanonicalResource };
+module.exports = { CanonicalResource, checkContained };

package/tx/library/codesystem.js

@@ -55,6 +55,7 @@ class CodeSystem extends CanonicalResource {
       if (e.issueCode) { wrapped.issueCode = e.issueCode; }
       throw wrapped;
     }
+    this.checkContained();
     if (!noMaps) {
       this.buildMaps();
     }

package/tx/library/conceptmap.js

@@ -19,6 +19,7 @@ class ConceptMap extends CanonicalResource {
     // Convert to R5 format internally (modifies input for performance)
     this.jsonObj = conceptMapToR5(jsonObj, fhirVersion);
     this.validate();
+    this.checkContained();
     this.id = this.jsonObj.id;
     // Precalculated at construction so callers (e.g. the resource cache) have a
     // cheap O(1) sense of how large this resource is.

package/tx/library/valueset.js

@@ -25,12 +25,28 @@ class ValueSet extends CanonicalResource {
     // Convert to R5 format internally (modifies input for performance)
     this.jsonObj = valueSetToR5(jsonObj, fhirVersion);
     this.validate();
+    this.checkContained();
     this.buildMaps();
     // Precalculated at construction so callers (e.g. the resource cache) have a
     // cheap O(1) sense of how large this resource is.
     this._conceptCount = ValueSet._countConcepts(this.jsonObj, this._containsCount);
   }
 
+  /**
+   * What circular reference detection knows this value set by: its versioned url, or, for
+   * a contained value set (see TerminologyWorker.findValueSet), its container's key plus
+   * #id - a contained value set's own url, if it has one, says nothing about which
+   * container it came from. null for a value set with no url that isn't contained.
+   * @returns {string|null}
+   */
+  get contextKey() {
+    if (this.isContained && this.container) {
+      const base = this.container.contextKey || this.container.vurl || '(unidentified)';
+      return `${base}#${this.jsonObj.id || ''}`;
+    }
+    return this.vurl || null;
+  }
+
   /**
    * Number of concepts this ValueSet carries: the enumerated concepts in its
    * compose (include + exclude `concept` lists) plus any concepts in an inline

package/tx/library.js

@@ -664,7 +664,15 @@ class Library {
     const resources = await contentLoader.getResourcesByType("CodeSystem");
     let csc = 0;
     for (const resource of resources) {
-      const cs = new CodeSystem(await contentLoader.loadFile(resource, contentLoader.fhirVersion()));
+      let cs;
+      try {
+        cs = new CodeSystem(await contentLoader.loadFile(resource, contentLoader.fhirVersion()));
+      } catch (e) {
+        // one unacceptable resource (e.g. contained resources the server doesn't support)
+        // must not stop the rest of the package loading
+        this.log.warn(`Package ${contentLoader.pid()}: skipping CodeSystem ${resource.id || resource.filename || ''}: ${e.message}`);
+        continue;
+      }
       if (this.#isIgnored(cs.url, cs.version)) {
         this.log.info(`Ignoring CodeSystem ${cs.url}${cs.version ? '#' + cs.version : ''} (excluded by config)`);
         continue;
@@ -775,7 +783,14 @@ class Library {
     const csEntries = await contentLoader.getResourcesByType("CodeSystem");
     let csc = 0;
     for (const entry of csEntries) {
-      const cs = new CodeSystem(await contentLoader.loadFile(entry, contentLoader.fhirVersion()));
+      let cs;
+      try {
+        cs = new CodeSystem(await contentLoader.loadFile(entry, contentLoader.fhirVersion()));
+      } catch (e) {
+        // one unacceptable resource must not stop the rest of the package loading
+        this.log.warn(`Package ${contentLoader.pid()}: skipping CodeSystem ${entry.id || entry.filename || ''}: ${e.message}`);
+        continue;
+      }
       if (this.#isIgnored(cs.url, cs.version)) {
         this.log.info(`Ignoring CodeSystem ${cs.url}${cs.version ? '#' + cs.version : ''} (excluded by config)`);
         continue;