fhirsmith 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -5,6 +5,70 @@ All notable changes to Health Intersections FHIRsmith will be documented in this
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.2] - 2026-10-06
+
+### Security
+
+- Dependency updates for published advisories, including axios (several high severity), brace-expansion (denial of service), and http-cache-semantics and @tootallnate/once (removed with the old sqlite3 build chain)
+
+### Added
+
+- OpenAPI descriptions for the package server (/packages), the terminology registry (/tx-reg), the TestReport module (/testing) and the R5 terminology endpoints: each serves `openapi.json`, `openapi.yaml` and an HTML reference at `openapi` (JSON for non-browser clients), linked from the module's pages and advertised in an RFC 8631 `Link` header on every response. The FHIR resource schemas are generated from the FHIR definitions, constrained to what each module accepts
+- npm audit self-check: once a day the server checks its installed packages (and FHIRsmith itself) against the npm advisory database - report only, nothing is changed. Findings show as a banner on the home page, in full on the dashboard, and in the log. `npmAudit.enabled` = false turns it off (e.g. for servers with no internet access)
+- Registry: new Software page (/tx-reg/software) listing each registered server's software and version, and for FHIRsmith servers, the release date, its age, and how many releases behind it is. The crawler now records `CapabilityStatement.software.version`
+
+### Changed
+
+- Terminology server: contained resources are supported only for ValueSets that contain ValueSets (which `compose.include.valueSet` can import by `#id`). Any other contained resource is rejected (CONTAINED_RESOURCE_NOT_SUPPORTED) wherever the resource comes from; when loading a package, the offending resource is skipped rather than stopping the load
+- $validate-code: the `inactive` and `status` output parameters describe the code being returned. In a CodeableConcept where a different coding is inactive, that coding still gets its warning, but the parameters are not set for the returned code
+- Registry discovery API follows the tx ecosystem IG: rows carry `fhirVersion` and the IG's security flags (`open`, `token`, ...) alongside the existing security string; candidate lists are only given when `url` is supplied; R-codes (R4, R4B, R5, ...) map to their release versions; and the resolve fallback that returned servers authoritative for a code system but not hosting it has been removed
+- The TerminologyCapabilities statement no longer lists expansion parameters the server doesn't act on (`limitedExpansion`, `_incomplete`, `incomplete-ok` and others); `limitedExpansion`/`incomplete-ok` are no longer read, and no longer part of the expansion cache key (they never had any effect)
+- TestReport module: a TestReport with contained resources is refused
+- Packages and registry page footers say when the crawler last updated the data ("last updated 35 minutes ago"), or "not yet updated" before the first crawl - they used to show a raw `[%crawler-date%]` placeholder
+- Packages crawler log: the start time is shown relative ("35 minutes ago") and the duration in seconds; the end time is dropped
+- Dependencies: sqlite3 6 (connect-sqlite3 now uses the same sqlite3, which drops the old node-gyp/make-fetch-happen chain), and updates for axios, brace-expansion, moment, ip-address, csv-parse and uuid. The PR build now fails only on high/critical advisories in what ships (`npm audit --omit=dev`)
+
+### Fixed
+
+- $expand: RxNorm expansions that asked for a concept's children failed with `SQLITE_MISUSE`; an over-limit expansion of the whole of RxNorm is now refused before it is built
+- $expand: a value set with neither a compose nor an expansion gets a clear error (VALUESET_NO_COMPOSE)
+- $validate-code: in a CodeableConcept, the inactive warning names the coding that is actually inactive (it used to name the first coding), and a later active coding no longer hides the warning from an earlier inactive one
+- Packages: `/status`, `/stats` and `/search` hung instead of answering (the `/:id` route swallowed them)
+- Packages: dependency searches accept `id#version` and `id|version` (as sent by the Java PackageClient) as well as `id@version`; npm search (`/-/v1/search`) honours `text`, `size` and `from`, and accepts the other npm and PackageClient parameters
+- XIG: the version shown on the pages
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 3585 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11+closure, tests v1.9.6, runner v6.10.4)
+
+## [0.14.1] - 2026-09-29
+
+### Added
+
+- TestReport module: user administration - the administrator (`adminPassword`) manages users at /testing/admin/users, with rights to edit named links and/or delete reports
+- TestReport module: named links - test script and participant URLs shown by name, maintained at /testing/admin/links
+- TestReport module: the report list shows the test engine, client and server, the number of tests and the run length; a report page shows setup, each test with its operations and assertions, and teardown
+- Test reports from the FHIRsmith build name the test modes they ran with
+
+### Changed
+
+- Security: the publisher and testing web pages require a CSRF token on every form post (lusca), a SameSite=Lax session cookie, and a same-origin `Origin` on posts; the session id is regenerated on login
+- Security: the publisher rate limits task actions (create, approve, delete, retry) and task output reads, as well as logins
+- `server.trustProxy` now defaults to trusting only loopback, link-local and private-network proxies (was `true`, which let anyone reaching the port directly set their own client address and get round the rate limits). See nginx.md - a proxy elsewhere needs to be configured, and the proxy must pass on `Host` or `X-Forwarded-Host`, or form posts are refused
+- $expand: the `displayLanguage` expansion parameter is written without spaces (`en,*;q=0`, not `en, *; q=0`)
+- $translate: `result` is only true if at least one match is a translation - a `not-related-to` (R4: `disjoint`/`unmatched`) or `noMap` match is still returned, but `result` is false
+- SNOMED CT edition names are held in one table (tx/sct/editions.js), used by the provider and the unknown code messages
+
+### Fixed
+
+- $validate-code: when the code is not in the value set, it is looked up in the code system version the value set selects (`compose.include.version`), not the server's default version - so the version and display reported come from the right edition
+- $validate-code: the unknown code message named the SNOMED CT test edition as "unknown"; it is now "Test Edition"
+- Registry: the SNOMED CT test edition (`http://snomed.info/xsct/31000003106`) is labelled, rather than shown as `??`
+
+### Tx Conformance Statement
+
+FHIRsmith passed all 3585 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11+closure, tests v1.9.6, runner v6.10.4)
+
 ## [0.14.0] - 2026-09-27
 
 ### Added

package/README.md

@@ -10,10 +10,11 @@ This server provides a set of server-side services that are useful for the FHIR
 
 ## Services useful the community as a whole
 
-* [TX Registry](registry/readme.md) - **Terminology System Registry** as [described by the terminology ecosystem specification](https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig) (as running at http://tx.fhir.org/tx-reg)
-* [Package server](packages/readme.md) - **NPM-style FHIR package registry** with search, versioning, and downloads, consistent with the FHIR NPM Specification (as running at http://packages2.fhir.org/packages)
+* [TX Registry](registry/readme.md) - **Terminology System Registry** as [described by the terminology ecosystem specification](https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig) (as running at http://tx.fhir.org/tx-reg). Its API is described by an OpenAPI 3.1 spec at `/tx-reg/openapi.json` (and `.yaml`), with a browsable reference at `/tx-reg/openapi`
+* [Package server](packages/readme.md) - **NPM-style FHIR package registry** with search, versioning, and downloads, consistent with the FHIR NPM Specification (as running at http://packages2.fhir.org/packages). Its API is described by an OpenAPI 3.1 spec at `/packages/openapi.json` (and `.yaml`), with a browsable reference at `/packages/openapi`
 * [XIG server](xig/readme.md) -  **Comprehensive FHIR IG analytics** with resource breakdowns by version, authority, and realm (as running at http://packages2.fhir.org/packages)
 * [Publisher](publisher/readme.md) - FHIR publishing services (as running at [healthintersections.com.au](http://www.healthintersections.com.au/publisher))
+* [Testing](testing/readme.md) - **TestReport repository**: receives FHIR TestReports from TxTester and other test tools, with a FHIR API and web pages (as running at https://testing.fhir.org/testing). Its API is described by an OpenAPI 3.1 spec at `/testing/openapi.json` (and `.yaml`), with a browsable reference at `/testing/openapi`
 * [VCL](vcl/readme.md) - **Parse VCL expressions** into FHIR ValueSet resources (as running at http://fhir.org/vcl)
 * (Coming) Token services
 

package/config-template.json

@@ -18,6 +18,15 @@
     // how often the counters are written out
     "intervalMinutes": 10
   },
+  // Once a day the server checks its installed npm packages against the npm advisory
+  // database (what `npm audit` does - report only, nothing is changed). Problems show on
+  // the home page and the dashboard, and in the log. Needs outbound access to
+  // registry.npmjs.org. The whole block is optional.
+  "npmAudit": {
+    // set false to turn the check off (e.g. a server with no internet access)
+    "enabled": true,
+    "intervalHours": 24
+  },
   "modules": {
     "shl": {
       "enabled": false,
@@ -88,6 +97,10 @@
       "cookieSecure": true,
       // failed-login attempts allowed per IP per 15 minutes (default 20)
       "loginAttemptsPerWindow": 20,
+      // per IP address per minute: task actions (create, approve, delete, retry), and reads
+      // of task output, history and QA pages and files
+      "taskActionsPerMinute": 30,
+      "taskReadsPerMinute": 300,
       "workspaceRoot": "/absolute/path/to/workspaces",
       "igPublisherTimeoutMinutes": 60,
       // where to put files the IG Publisher leaves in the web folder that are too big for GitHub
@@ -261,6 +274,13 @@
       "tokenHeader": "Authorization",
       // DELETE of a report needs this token, in the same header. No adminToken, no deletes
       // "adminToken": "<!-- secret -->",
+      // the web administration pages: log in as 'admin' with this password to manage users
+      // (who can edit the named links and/or delete reports). No adminPassword, no administrator
+      // "adminPassword": "<!-- secret -->",
+      // signs the login cookie; without it logins don't survive a restart
+      // "sessionSecret": "<!-- random string -->",
+      // the login cookie is HTTPS-only unless this is false (e.g. for local testing over http)
+      // "cookieSecure": true,
       // bytes
       "maxSize": 512000,
       // reports per IP address per window; max 0 turns the limit off

package/library/fhir-openapi-schema.js

@@ -0,0 +1,441 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+/**
+ * Generates OpenAPI 3.1 (JSON Schema 2020-12) component schemas for FHIR resources from
+ * their StructureDefinitions.
+ *
+ * The published FHIR JSON schema doesn't work well in an OpenAPI description: every
+ * resource reaches every other one (through contained resources and Bundle entries) and
+ * every datatype (through extensions), so referencing one resource drags in the whole
+ * specification. This generator produces only what the named resources actually use, and
+ * cuts the recursion at two fixed boundaries:
+ *
+ *  - an element whose type is a resource (Bundle.entry.resource, and so on) is "any
+ *    resource": an object with a resourceType, otherwise not described. A module can
+ *    narrow it with an overlay (a search Bundle of TestReports, say)
+ *  - an extension is described as an object with a url and a value[x], but the value isn't
+ *    described further
+ *
+ * Elements can be prohibited outright (the testing module doesn't accept contained
+ * resources), and an overlay can tighten the generated schemas to what an endpoint really
+ * requires.
+ *
+ * A module can move the boundaries, when it knows what it handles:
+ *  - `resources` names the resources an element of type Resource can hold, by path
+ *    (Bundle.entry.resource: CodeSystem or ValueSet, say); they're generated too. An
+ *    element whose type is a particular resource (Bundle.issues: OperationOutcome) is always
+ *    that resource
+ *  - `choiceTypes` restricts the types of a choice element, by path
+ *    (Parameters.parameter.value[x]: the primitives, say)
+ *  - `generateExtension` describes Extension fully, from its StructureDefinition, instead
+ *    of as a boundary; usually with choiceTypes for Extension.value[x]
+ *
+ * What's generated:
+ *  - one schema per resource and complex datatype, named for the type, and one per backbone
+ *    element, named for its path (TestReport_Setup_Action); contentReference becomes a $ref
+ *  - every object is closed (additionalProperties: false), as FHIR JSON is
+ *  - a primitive element `x` gets its value (with the type's regex as a pattern, and the
+ *    codes of a required binding as an enum where they can be worked out from the package)
+ *    and its `_x` sibling for the element's id and extensions. In a repeating primitive,
+ *    either array may have nulls where the other has an entry
+ *  - choice elements (value[x]) are expanded to their concrete names (valueString ...)
+ *  - required: elements with min >= 1, and resourceType
+ *
+ * @module library/fhir-openapi-schema
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REGEX_EXT = 'http://hl7.org/fhir/StructureDefinition/regex';
+const SYSTEM_STRING = 'http://hl7.org/fhirpath/System.String';
+
+/** The boundary schemas; included where something reaches them. */
+const BOUNDARY_SCHEMAS = {
+  Extension: {
+    type: 'object',
+    description: 'An extension. The value (value[x]) can be any FHIR datatype, and is not described further here.',
+    properties: {
+      id: { type: 'string' },
+      url: { type: 'string', description: 'The extension\'s definition' },
+      extension: { type: 'array', items: { $ref: '#/components/schemas/Extension' } }
+    },
+    patternProperties: {
+      '^_?value[A-Z][A-Za-z0-9]*$': { description: 'The value (value[x]), and its _value[x] sibling for a primitive' }
+    },
+    required: ['url'],
+    additionalProperties: false
+  },
+  AnyResource: {
+    type: 'object',
+    description: 'A FHIR resource of any type. Not described further here.',
+    properties: {
+      resourceType: { type: 'string' }
+    },
+    required: ['resourceType'],
+    additionalProperties: true
+  }
+};
+
+function ref(name) {
+  return { $ref: `#/components/schemas/${name}` };
+}
+
+function cap(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function schemaNameForPath(p) {
+  return p.split('.').map(cap).join('_');
+}
+
+function extValue(type, url) {
+  const e = (type.extension || []).find(x => x.url === url);
+  return e ? (e.valueUrl || e.valueString || e.valueUri) : undefined;
+}
+
+/**
+ * The StructureDefinitions, CodeSystems and ValueSets in an unpacked FHIR package.
+ */
+class FhirPackage {
+  constructor(dir) {
+    this.dir = dir;
+    this.sds = new Map();
+    this.byUrl = new Map();
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.json') || !/^(StructureDefinition|CodeSystem|ValueSet)-/.test(f)) {
+        continue;
+      }
+      const r = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      if (r.url) {
+        this.byUrl.set(r.url, r);
+      }
+      if (r.resourceType === 'StructureDefinition' && r.derivation === 'specialization') {
+        this.sds.set(r.type, r);
+      }
+    }
+    const pj = path.join(dir, 'package.json');
+    this.id = fs.existsSync(pj) ? (() => {
+      const p = JSON.parse(fs.readFileSync(pj, 'utf8'));
+      return `${p.name}#${p.version}`;
+    })() : dir;
+  }
+
+  sd(type) {
+    return this.sds.get(type);
+  }
+
+  /** The codes of a value set, if they can be worked out simply; otherwise null. */
+  codes(vsUrl) {
+    const vs = this.byUrl.get(vsUrl.split('|')[0]);
+    if (!vs || !vs.compose || vs.compose.exclude || !Array.isArray(vs.compose.include)) {
+      return null;
+    }
+    const codes = [];
+    for (const inc of vs.compose.include) {
+      if (inc.filter || inc.valueSet || !inc.system) {
+        return null;
+      }
+      if (inc.concept) {
+        codes.push(...inc.concept.map(c => c.code));
+      } else {
+        const cs = this.byUrl.get(inc.system);
+        if (!cs || cs.content !== 'complete' || !cs.concept) {
+          return null;
+        }
+        const walk = (list) => list.forEach(c => {
+          codes.push(c.code);
+          if (c.concept) {
+            walk(c.concept);
+          }
+        });
+        walk(cs.concept);
+      }
+    }
+    return codes.length > 0 ? codes : null;
+  }
+}
+
+class FhirSchemaGenerator {
+  /**
+   * @param {FhirPackage} pkg
+   * @param {Object} [options]
+   * @param {string[]} [options.prohibit] - elements that are left out: a name (e.g.
+   *   'contained') leaves the element out of every resource and type, a path (e.g.
+   *   'CodeSystem.contained') out of that one place. The schemas are closed, so they're
+   *   then not allowed
+   * @param {Object<string, string[]>} [options.resources] - path -> the resource types an
+   *   element of type Resource may hold (otherwise it's AnyResource)
+   * @param {Object<string, string[]>} [options.choiceTypes] - path of a choice element
+   *   (e.g. 'Parameters.parameter.value[x]') -> the types allowed (otherwise all of them)
+   * @param {boolean} [options.generateExtension] - describe Extension from its
+   *   StructureDefinition rather than as a boundary
+   */
+  constructor(pkg, options = {}) {
+    this.pkg = pkg;
+    this.prohibit = new Set(options.prohibit || []);
+    this.resources = options.resources || {};
+    this.choiceTypes = options.choiceTypes || {};
+    this.boundary = { ...BOUNDARY_SCHEMAS };
+    if (options.generateExtension) {
+      delete this.boundary.Extension;
+    }
+    this.schemas = {};
+    this.queue = [];
+    this.queued = new Set();
+  }
+
+  /**
+   * @param {string[]} roots - the resources (and types) to describe
+   * @returns {Object} name -> schema
+   */
+  generate(roots) {
+    Object.assign(this.schemas, structuredClone(this.boundary));
+    roots.forEach(r => this.enqueue(r));
+    while (this.queue.length > 0) {
+      this.generateType(this.queue.shift());
+    }
+    // a boundary nothing ended up at isn't needed
+    const used = JSON.stringify(this.schemas);
+    for (const name of Object.keys(this.boundary)) {
+      if (!used.includes(`"#/components/schemas/${name}"`)) {
+        delete this.schemas[name];
+      }
+    }
+    // a stable order, so the generated file diffs cleanly
+    const sorted = {};
+    for (const k of Object.keys(this.schemas).sort()) {
+      sorted[k] = this.schemas[k];
+    }
+    return sorted;
+  }
+
+  enqueue(type) {
+    if (!this.queued.has(type) && !this.boundary[type]) {
+      this.queued.add(type);
+      this.queue.push(type);
+    }
+  }
+
+  generateType(type) {
+    const sd = this.pkg.sd(type);
+    if (!sd) {
+      throw new Error(`No StructureDefinition for ${type} in ${this.pkg.id}`);
+    }
+    if (sd.kind === 'primitive-type') {
+      throw new Error(`${type} is a primitive type, and has no schema of its own`);
+    }
+    this.elements = sd.snapshot.element;
+    this.buildObject(type, type, sd.kind === 'resource', sd.description);
+  }
+
+  children(p) {
+    const prefix = p + '.';
+    return this.elements.filter(e => e.path.startsWith(prefix) && !e.path.substring(prefix.length).includes('.'));
+  }
+
+  buildObject(schemaName, p, isResource, description) {
+    const schema = { type: 'object' };
+    if (description) {
+      schema.description = description;
+    }
+    const properties = {};
+    const required = [];
+    if (isResource) {
+      properties.resourceType = { const: p };
+      required.push('resourceType');
+    }
+    for (const el of this.children(p)) {
+      const name = el.path.substring(p.length + 1);
+      if (el.max === '0' || this.prohibit.has(name) || this.prohibit.has(el.path)) {
+        continue;
+      }
+      if (name.endsWith('[x]')) {
+        const base = name.slice(0, -3);
+        const allowed = this.choiceTypes[el.path];
+        if (allowed) {
+          const unknown = allowed.filter(t => !el.type.some(et => et.code === t));
+          if (unknown.length > 0) {
+            throw new Error(`${el.path} can't be ${unknown.join(', ')}`);
+          }
+        }
+        for (const t of el.type.filter(t => !allowed || allowed.includes(t.code))) {
+          this.addProperty(properties, base + cap(t.code), el, t);
+        }
+      } else {
+        this.addProperty(properties, name, el, el.type ? el.type[0] : null);
+        if (el.min >= 1) {
+          required.push(name);
+        }
+      }
+    }
+    schema.properties = properties;
+    if (required.length > 0) {
+      schema.required = required;
+    }
+    schema.additionalProperties = false;
+    this.schemas[schemaName] = schema;
+  }
+
+  addProperty(properties, name, el, type) {
+    const many = el.max !== '1';
+    const description = el.short;
+    let value;
+    let primitive = false;
+
+    if (el.contentReference) {
+      value = ref(schemaNameForPath(el.contentReference.replace(/^.*#/, '')));
+    } else if (!type) {
+      throw new Error(`${el.path} has no type`);
+    } else if (type.code === SYSTEM_STRING) {
+      // element ids, and the like
+      value = { type: 'string' };
+    } else if (type.code === 'BackboneElement' || (type.code === 'Element' && this.children(el.path).length > 0)) {
+      const sn = schemaNameForPath(el.path);
+      this.buildObject(sn, el.path, false, el.definition);
+      value = ref(sn);
+    } else if (type.code === 'Extension') {
+      this.enqueue('Extension');
+      value = ref('Extension');
+    } else {
+      const tsd = this.pkg.sd(type.code);
+      if (!tsd) {
+        throw new Error(`${el.path}: no StructureDefinition for type ${type.code}`);
+      }
+      if (type.code === 'Resource' || type.code === 'DomainResource') {
+        const allowed = this.resources[el.path];
+        if (allowed) {
+          allowed.forEach(t => this.enqueue(t));
+          value = allowed.length === 1 ? ref(allowed[0]) : { anyOf: allowed.map(ref) };
+        } else {
+          value = ref('AnyResource');
+        }
+      } else if (tsd.kind === 'resource') {
+        this.enqueue(type.code);
+        value = ref(type.code);
+      } else if (tsd.kind === 'primitive-type') {
+        primitive = true;
+        value = this.primitive(tsd, el);
+      } else {
+        this.enqueue(type.code);
+        value = ref(type.code);
+      }
+    }
+
+    if (primitive) {
+      // the value, and the _x sibling for its id and extensions
+      if (many) {
+        properties[name] = { type: 'array', description, items: { anyOf: [value, { type: 'null' }] } };
+        properties['_' + name] = { type: 'array', items: { anyOf: [ref('Element'), { type: 'null' }] } };
+      } else {
+        properties[name] = { ...value, description };
+        properties['_' + name] = ref('Element');
+      }
+      this.enqueue('Element');
+    } else if (many) {
+      properties[name] = { type: 'array', description, items: value };
+    } else {
+      properties[name] = { ...value, description };
+    }
+  }
+
+  primitive(tsd, el) {
+    const valueEl = tsd.snapshot.element.find(e => e.path === `${tsd.type}.value`);
+    const vt = valueEl && valueEl.type ? valueEl.type[0] : {};
+    // x-fhir-type records the FHIR type, which the JSON type doesn't say (dateTime, code, uri
+    // are all strings); the reference page shows it instead of the regex
+    const schema = { 'x-fhir-type': tsd.type };
+    switch (tsd.type) {
+      case 'boolean': schema.type = 'boolean'; break;
+      case 'integer': schema.type = 'integer'; break;
+      case 'positiveInt': schema.type = 'integer'; schema.minimum = 1; break;
+      case 'unsignedInt': schema.type = 'integer'; schema.minimum = 0; break;
+      case 'decimal': schema.type = 'number'; break;
+      default: schema.type = 'string';
+    }
+    if (schema.type === 'string') {
+      const regex = extValue(vt, REGEX_EXT);
+      if (regex) {
+        schema.pattern = regex.startsWith('^') ? regex : `^(${regex})$`;
+      }
+    }
+    if (tsd.type === 'code' && el.binding && el.binding.strength === 'required' && el.binding.valueSet) {
+      const codes = this.pkg.codes(el.binding.valueSet);
+      if (codes) {
+        schema.enum = codes;
+        delete schema.pattern;
+      }
+    }
+    return schema;
+  }
+}
+
+/**
+ * Applies an overlay to generated schemas: objects merge, `required` lists are unioned,
+ * and anything else in the overlay replaces what was generated. A schema in the overlay
+ * that wasn't generated is added as is.
+ */
+// keys that would reach an object's prototype rather than the object
+function isUnsafeKey(k) {
+  return k === '__proto__' || k === 'constructor' || k === 'prototype';
+}
+
+function applyOverlay(schemas, overlay) {
+  const merge = (target, src) => {
+    for (const [k, v] of Object.entries(src)) {
+      if (isUnsafeKey(k)) {
+        throw new Error(`An overlay can't set '${k}'`);
+      }
+      // only the target's own properties are merged into, never anything it inherits
+      const own = Object.prototype.hasOwnProperty.call(target, k);
+      if (k === 'required' && Array.isArray(target.required)) {
+        target.required = [...new Set([...target.required, ...v])];
+      } else if (own && v && typeof v === 'object' && !Array.isArray(v) && target[k] && typeof target[k] === 'object' && !Array.isArray(target[k]) && !v.$replace) {
+        merge(target[k], v);
+      } else {
+        const value = v && v.$replace ? { ...v } : v;
+        if (value && value.$replace) {
+          delete value.$replace;
+        }
+        target[k] = value;
+      }
+    }
+  };
+  for (const [name, s] of Object.entries(overlay || {})) {
+    if (isUnsafeKey(name)) {
+      throw new Error(`An overlay can't set '${name}'`);
+    }
+    if (Object.prototype.hasOwnProperty.call(schemas, name)) {
+      merge(schemas[name], s);
+    } else {
+      schemas[name] = s;
+    }
+  }
+  return schemas;
+}
+
+/**
+ * Generates the schemas a module's config asks for.
+ *
+ * @param {Object} config - { package, roots, prohibit, resources, choiceTypes,
+ *   generateExtension, overlay } (see FhirSchemaGenerator)
+ * @param {string} packageDir - the unpacked package
+ * @returns {{generatedFrom: string, schemas: Object}}
+ */
+function generateSchemas(config, packageDir) {
+  const pkg = new FhirPackage(packageDir);
+  const gen = new FhirSchemaGenerator(pkg, {
+    prohibit: config.prohibit,
+    resources: config.resources,
+    choiceTypes: config.choiceTypes,
+    generateExtension: config.generateExtension
+  });
+  const schemas = applyOverlay(gen.generate(config.roots), structuredClone(config.overlay || {}));
+  return { generatedFrom: pkg.id, schemas };
+}
+
+module.exports = { FhirPackage, FhirSchemaGenerator, applyOverlay, generateSchemas, BOUNDARY_SCHEMAS };

package/library/html-server.js

@@ -8,6 +8,7 @@
 const fs = require('fs');
 const path = require('path');
 const escape = require('escape-html');
+const packageJson = require('../package.json');
 
 let sponsorMessage = '';
 
@@ -60,7 +61,6 @@ class HtmlServer {
     
     // Default options
     const renderOptions = {
-      version: '4.0.1',
       downloadDate: 'Unknown',
       totalResources: 0,
       totalPackages: 0,
@@ -72,8 +72,11 @@ class HtmlServer {
     let html = template
       .replace(/\[%title%\]/g, escape(title))
       .replace(/\[%content%\]/g, content) // Content is assumed to be already-safe HTML
-      .replace(/\[%ver%\]/g, escape(renderOptions.version))
+      // [%ver%] is the FHIRsmith version in every template (it follows the FHIRsmith link)
+      .replace(/\[%ver%\]/g, escape(packageJson.version))
       .replace(/\[%download-date%\]/g, escape(renderOptions.downloadDate))
+      // "last updated 35 minutes ago" / "not yet updated", for the crawler-driven modules
+      .replace(/\[%crawler-status%\]/g, escape(renderOptions.crawlerStatus || 'not yet updated'))
       .replace(/\[%total-resources%\]/g, escape(renderOptions.totalResources.toLocaleString()))
       .replace(/\[%total-packages%\]/g, escape(renderOptions.totalPackages.toLocaleString()))
       .replace(/\[%endpoint-path%\]/g, escape(renderOptions.endpointpath))
@@ -82,7 +85,10 @@ class HtmlServer {
       .replace(/\[%sponsorMessage%\]/g, sponsorMessage)
       .replace(/\[%about%\]/g, renderOptions.about || '')
       // raw HTML, like [%about%]: the caller decides whether the nav item exists at all
-      .replace(/\[%library-link%\]/g, renderOptions.libraryLink || '');
+      .replace(/\[%library-link%\]/g, renderOptions.libraryLink || '')
+      // raw HTML too: the OpenAPI description, where a template's module has one in some places only
+      .replace(/\[%api-link%\]/g, renderOptions.apiLink || '')
+      .replace(/\[%api-head%\]/g, renderOptions.apiHead || '');
     
     // Handle any custom template variables
     if (options.templateVars) {

package/library/languages.js

@@ -562,6 +562,21 @@ class Languages {
     }
     return parts.join(', ');
   }
+
+  /**
+   * The languages as they were asked for, in the form a displayLanguage parameter takes
+   * (the Accept-Language syntax: "en,it;q=0.8,*"). Unlike asString, which is for reading
+   * in messages, there are no spaces; unlike toString, implicit languages are left out.
+   */
+  asParameter() {
+    return this.languages.filter(lang => !lang.implicit).map(lang => {
+      if (lang.quality === undefined || lang.quality === 1.0) {
+        return lang.code;
+      } else {
+        return `${lang.code};q=${lang.quality}`;
+      }
+    }).join(',');
+  }
 }
 
 /**