fhirsmith 0.18.1 → 0.18.2

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.18.2] - 2026-10-29
+
+### Added
+
+- IPS: national profiles - the profile on Bundle that a national IG defines for an IPS document: its jurisdiction (an ISO 3166 country code, or a UN M49 region), the IG's package id and version, and the profile's url. They are shared across all projects at `/ips/national-profiles`, where everyone can see them and only the administrator adds, edits and deletes them (also as JSON). A new processing step, after validation, validates each document against each national profile - loading the IG's package into the validator, once - and keeps the outcome and whether the document passed (no errors). The document's new National Profiles view lists them, and shows each one's validation as the Validation view does
+- IPS: `modules.ips.validator.jar` - a validator jar of the module's own (a local build of org.hl7.fhir.core, say), used as it is, never downloaded or updated. Don't put such a jar at `bin/validator_cli.jar`: the wrapper takes that jar's version from the `.version` file it wrote when it downloaded the release, so a different jar there is started as if it were that release, and is replaced by the next one
+- Registry: `GET /tx-reg/choose-server` - given the code systems a request involves and the client's default server, which one server to send it to, and a log of why. The same choice the Java tooling makes, for clients that aren't Java
+- SNOMED CT ECL: member filters (`^ refset {{ M ... }}`) - `effectiveTime` (with a time value or set), `active`, `moduleId` (any sub expression) and the reference set's own fields (`targetComponentId = << X`, `mapTarget = "..."`, `mapGroup >= #2`, ...), comma-separated and repeatable. A member filter anywhere other than directly after a memberOf constraint is a syntax error (`INVALID_ECL`)
+- SNOMED CT ECL: concept filters (`{{ C ... }}`) - `active`, `definitionStatus` (primitive/defined), `definitionStatusId`, `moduleId` (a concept, a bracketed concept list or any sub expression) and `effectiveTime`
+- SNOMED CT ECL: description filters (`{{ D ... }}`) - `term` (match and `wild:` search terms, single or a set), `language`, `typeId` and `type` (syn/fsn/def), `dialectId` and `dialect` (en-us, en-gb and the other aliases in the ECL specification) with acceptability sets, `moduleId`, `effectiveTime`, `active` and `id`. The filters in one block apply to the same description; only active descriptions are considered unless `active` is given
+- SNOMED CT ECL: history supplements (`{{ + HISTORY }}`, `HISTORY-MIN` / `-MOD` / `-MAX`, `HISTORY (*)`, `HISTORY (refset expression)`) - the inactive concepts that the selected historical association reference sets associate with the result are added to it
+- SNOMED CT ECL: `AND` and `OR` between refinements - between attributes (`: A = x AND B = y`, `: A = x OR B = y`, with brackets for nesting), within an attribute group (`{ A = x OR B = y }`) and between groups (`{ ... } OR { ... }`). Mixing AND and OR without brackets is rejected, as it is for compound expressions. Previously only `,` (conjunction) was accepted
+- SNOMED CT ECL: concrete values in refinements (`= #500`, `>= #1.5`, `!= #-1`, `= "text"`, `= true`). The importer now reads `sct2_RelationshipConcreteValues_*` into a new cache section (cache version 19, after 18's alternate identifiers); editions imported before this report a concrete-value refinement as unsupported. The test edition cache is now `sct_test_20250909e.cache`
+- SNOMED CT ECL: `!=` in refinements (`: A != X` - at least one A whose value is not in X; `[0..0] A != X` - every A is in X), reversed attributes (`: R A = X` - the concepts that are the value of A on a concept in X), and `,` as a conjunction between expressions as well as between refinements
+- SNOMED CT ECL: comments (`/* ... */`), top and bottom of set (`!!> (...)`, `!!< (...)`), and attribute names that are expressions rather than a single concept (`: << 762705008 = ...`, `: (A OR B) = ...`, `: ^ refset = ...`, `: * = ...`, and the same after `.` in dotted expressions)
+- SNOMED CT ECL: alternate identifiers (`LOINC#14394-1`, `"LOINC#14394-1"`): the scheme alias names an identifier scheme (LOINC = 30051010000102 |LOINC code ID|, as imported from the LOINC Extension) and the code resolves to the concept(s) carrying it, which then take hierarchy operators like any set. An unknown scheme, or a code that no concept carries, is `INVALID_ECL`, as an unknown concept is
+- SNOMED CT ECL: reference set field selection on member-of (`^ [targetComponentId] refset`) is parsed, and reported as `UNSUPPORTED_ECL` (the selected fields, and many of the referenced components, are descriptions) rather than as a syntax error
+
+### Changed
+
+- IPS: a clinical profile's page is the same for everyone. The required sections and entries are a table of Expectation, Section and Entry (`Code is system|code`, or `Code is in` a value set, with `[m..n]` when the cardinality isn't 1..1). The rules about resources are a table of Expectation, Resource Set (`Conditions where Code is ...`) and Rule, in words for `.exists()`, `.x.exists()` and `.x.y.exists()`, `.all(sameSubject())`, `.conformsTo(url)` and `.category.hasCoding(system, code)`. The administrator adds, edits and deletes the rules on that page one at a time, in a dialog, each saved by itself; the full editor is still there as Edit all
+- IPS: `fhir-validator-wrapper` 1.6.1 (was 1.5.0) - it sends `/loadIG` the package in the request body (1.5.0 sent it in the query, which the validator ignored, so no national profile's package loaded), and starts validator 7.0.4 and later with `-txTests`, which the tx tests need
+- Terminology server: code systems, value sets and concept maps that both hl7.terminology and an endpoint's FHIR core package provide. THO's is still always the default for the url, but the core versions are no longer dropped: a reference that names a core version (`url|5.0.0`) gets it, where THO doesn't have that version. Previously they weren't available at all, so a reference to one failed - including THO's own value sets that pin a core version (`ValueSet/concept-property-type` 6.0.1 includes `concept-property-type` 5.0.0) - and `valueSetVersion=5.0.0` found nothing
+- Registry: the "Register your own server" and "Documentation" links on the main page come from the master registration file (`registration` and `ecosystem-documentation`), so each ecosystem has its own, and a link the file doesn't give is left out. They were hard-coded to the HL7 ecosystem's
+- Tx tests: the `loinc` mode (the LOINC suite) is run
+
+### Fixed
+
+- VSAC: the cache folder `terminology-cache/vsac` is created if it doesn't exist. Only its parent was being created (the folder name was passed as if it were a file name), so on a fresh install the VSAC database could not be created (`SQLITE_CANTOPEN`) and every VSAC value set failed
+- CodeSystem resources: the `notSelectable` property is recognised as the tx-ecosystem requirements say - by the `concept-properties#notSelectable` uri, whatever local code the code system gives it, and by the code `notSelectable` only where the code system doesn't declare that code with a different uri. A code system that used `notSelectable` for a property of its own had its concepts marked `abstract` in expansions and treated as not selectable (`notSelectable-unprop-all`, `notSelectable-unprop-true`). A filter on that code is still a filter on the code system's own property
+- LOINC: `$lookup` returns `CLASS` as a string, the class name (e.g. `CHEM`), with the Part code for the class as `partCode`; it returned the Part code as a code
+- SNOMED CT ECL: a hierarchy operator on a bracketed expression was silently dropped - `< (A OR B)` returned A and B themselves rather than their descendants. It now applies to every member of the set, as do operators on `*` and on `^ refset`, which were previously rejected as unsupported
+- SNOMED CT ECL: `^` on a reference set whose members are descriptions (a language reference set) returned an empty expansion. It is now reported as `UNSUPPORTED_ECL` when the reference set is named, and skipped when it merely falls inside a computed operand such as `^ *`
+- SNOMED CT ECL: an attribute name with no comparison (`: 363698007` with nothing after it) was accepted by the parser and failed later as unsupported; it is a syntax error
+- SNOMED CT ECL: an evaluation error is now `UNSUPPORTED_ECL` unless it is about a concept that does not exist (`INVALID_ECL`). It was classified by matching the error text, which filed `= true` as a syntax error. A concept id that is not 6-18 digits is rejected by the parser
+- IPS: the pages link the module's browser scripts with their version (`?v=`), so a browser picks up a changed script as soon as the server is restarted with it, instead of using its cached copy for up to an hour
+
+### Tx Conformance Statement
+
+FHIRsmith v0.18.2 passed all 4565 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11+icf+closure+loinc, tests v1.10.1-snapshot, runner v7.0.3)
+
 ## [0.18.1] - 2026-10-25
 
 
@@ -79,12 +120,6 @@ Note: We are heading towards a 1.0.0 release.
 - `$lookup`: a warning when the `displayLanguage` asked for has no display for the code, and the display is in the default language (`LOOKUP_DISPLAY_LANGUAGE_FALLBACK`)
 - ICD-11: the `classificationCode` extension (provisional url `http://id.who.int/icd/schema/extension/classificationCode`) on a Coding carries the short code for an entity id, saving a lookup. When present it is checked in `$validate-code` (CodeSystem and ValueSet): a wrong value, or the extension on a code with no short code, on a short code, or on a system other than MMS, is an error
 - ICD-11 `$lookup`: postcoordination is reported as one `postcoordination` property per axis (subproperties `axis` and `value` Codings, a `/` member's value with its own nested postcoordination), replacing the WHO `postcoordinationScale` shape. With the new parameter `post-coordination-metadata=true` every declared axis is listed with `required`, `allowMultipleValues` and its value set; otherwise only the valued axes. `source` (the Foundation entity) is a Coding, and asking for `source.details` adds what a `$lookup` on it would return, designations included. A single-valued axis with several values gets a message in `$validate-code`
-- SNOMED CT ECL: member filters (`^ refset {{ M ... }}`) - `effectiveTime` (with a time value or set), `active`, `moduleId` (any sub expression) and the reference set's own fields (`targetComponentId = << X`, `mapTarget = "..."`, `mapGroup >= #2`, ...), comma-separated and repeatable. A member filter anywhere other than directly after a memberOf constraint is a syntax error (`INVALID_ECL`). Description filters (`{{ D }}`), concept filters (`{{ C }}`) and history supplements (`{{ + }}`) are now parsed and rejected as `UNSUPPORTED_ECL` rather than failing as a lexer error
-- SNOMED CT ECL: concept filters (`{{ C ... }}`) - `active`, `definitionStatus` (primitive/defined), `definitionStatusId`, `moduleId` (a concept, a bracketed concept list or any sub expression) and `effectiveTime`
-- SNOMED CT ECL: `AND` and `OR` between refinements - between attributes (`: A = x AND B = y`, `: A = x OR B = y`, with brackets for nesting), within an attribute group (`{ A = x OR B = y }`) and between groups (`{ ... } OR { ... }`). Mixing AND and OR without brackets is rejected, as for compound expressions. Previously only `,` (conjunction) was accepted
-- SNOMED CT ECL: description filters (`{{ D ... }}`) - `term` (match and `wild:` search terms, single or a set), `language`, `typeId` and `type` (syn/fsn/def), `dialectId` and `dialect` (en-us, en-gb and the other aliases in the ECL specification) with acceptability sets, `moduleId`, `effectiveTime`, `active` and `id`. The filters in one block apply to the same description; only active descriptions are considered unless `active` is given
-- SNOMED CT ECL: comments (`/* ... */`), top and bottom of set (`!!> (...)`, `!!< (...)`), and attribute names that are expressions rather than a single concept (`: << 762705008 = ...`, `: (A OR B) = ...`, `: ^ refset = ...`, `: * = ...`, and the same after `.` in dotted expressions)
-- SNOMED CT ECL: concrete values in refinements (`= #5`, `!= "x"`, `= match:"x"`, `= true`, ...) and alternate identifiers (`"ICD10#A01.1"`, `SCTID#123`) and reference set field selection on member-of (`^ [targetComponentId] refset`) are now parsed, so they are reported as `UNSUPPORTED_ECL` with a message saying what is missing (concrete value relationships / alternate identifier reference sets are not loaded) rather than as a syntax error
 - SNOMED CT: `tx/sct/documentation.md` - what the server supports for SNOMED CT: editions, ECL, expressions and the MRCM, implicit concept maps and translation
 - `utilities/make-sct-test-extension.js`: builds the extension concepts (module TEST1000003) in the SNOMED CT test edition used by the tx tests - one of each shape (fully defined ungrouped, fully defined role-grouped, equivalent to an International concept, primitive), plus inactive ones with and without historical associations
 - README: each module's status - in production; in production but still under development; under development / prototyping; or on the back-burner
@@ -106,9 +141,6 @@ Note: We are heading towards a 1.0.0 release.
 - ValueSet `$validate-code`: an include with more than one filter only checked the first. The other filters' checks return a message when the code fails them, and a message was taken as a pass
 - LOINC: the `exists` filter ignored its value. On a relationship property (`METHOD_TYP`, `COMPONENT`, `document-kind`, ...) the value was looked up as a code or display, so `exists true` and `exists false` both returned every code with the relationship (because a code displayed as "True" and one as "False" exist), and on a property (`CLASSTYPE`, `ORDER_OBS`, ...) `exists false` meant `exists true`. `true` now returns the codes that have the property, `false` every other code in the code system - Parts, AnswerLists and Answers included, so add `CLASSTYPE exists true` to restrict to LOINC terms (e.g. LOINC terms with no method: `METHOD_TYP exists false` + `CLASSTYPE exists true`). Any other value is not supported
 - Packages: a package download or page request was counted twice in the statistics (once by the validation step, once by the handler), and tarball downloads were not told from requests for a version's JSON document; downloads are now counted as `download`, version documents as `version`, each once
-- SNOMED CT ECL: a hierarchy operator on a bracketed expression was silently dropped - `< (A OR B)` returned A and B themselves rather than their descendants. It now applies to every member of the set, as do operators on `*` and on `^ refset`, which were previously rejected as unsupported
-- SNOMED CT ECL: `^` on a reference set whose members are descriptions (a language reference set) returned an empty expansion; it is now reported as `UNSUPPORTED_ECL`
-- SNOMED CT ECL: an evaluation error is now `UNSUPPORTED_ECL` unless it is about a concept that does not exist (`INVALID_ECL`); it was classified by matching the error text, which filed `= true` as a syntax error. A concept id that is not 6-18 digits is rejected by the parser
 - SNOMED CT expressions: the MRCM content type taken as "postcoordinated" was 723594008, which is *all precoordinated content* (postcoordinated is 723595009). So the body-structure part-of attributes (|Regional part of| etc., precoordinated only) were allowed in expressions, |Has ingredient| (postcoordinated only) was not checked, and for the attributes with a precoordinated-specific range that range was used in place of the general one
 
 - SHL: every access to a live link (`/shl/access/{uuid}`) hung without a response - the access-logging callback was a plain `function`, so `this.db` was undefined in it and the request was never answered (since 0.3.0). A `GET` on a link is now the U flag (direct file) access the SMART Health Links spec defines: a link with one file returns it as a JWE (`application/jose`), and `recipient` is read from the query and logged (it was always `anonymous`); a link with more than one file, or a VHL, still gets the manifest / VHL bundle. The manifest now has `status` (`finalized`), file `location`s are always https (they followed `req.secure`, so http behind a proxy without trust proxy), and `embedded` is the JWE itself (it was the base64 of it, as stored)

package/ips/ips.js

@@ -39,10 +39,12 @@
  * @module ips/ips
  */
 
+const http = require('http');
 const express = require('express');
 const path = require('path');
 const fs = require('fs');
 const crypto = require('crypto');
+const scripts = require('./scripts');
 const rateLimit = require('express-rate-limit');
 const escape = require('escape-html');
 const session = require('express-session');
@@ -79,7 +81,69 @@ const TX_STARTUP_GRACE_MS = 5 * 60 * 1000;
 const FHIR_JSON = 'application/fhir+json; charset=utf-8';
 const CODE_RE = /^[a-z0-9][a-z0-9-]{1,31}$/;
 // paths at the root that can't be project codes
-const RESERVED = new Set(['login', 'logout', 'admin', 'metadata', 'openapi', 'static', 'assets', 'lookup']);
+const { jurisdiction: jurisdictionOf } = require('./jurisdictions');
+const LOAD_IG_TIMEOUT_MS = 300000;
+const RESERVED = new Set(['login', 'logout', 'admin', 'metadata', 'openapi', 'static', 'assets', 'lookup', 'national-profiles']);
+
+/**
+ * Ask the validator service to load a package (id#version) - POST /loadIG with {"ig": ...} as
+ * the validator's LoadIGHTTPHandler takes it. fhir-validator-wrapper's own loadIG() (to 1.6.0
+ * at least) sends the package id and version as query parameters with no body, which the
+ * service refuses ("Error parsing JSON source: ... Eof at Line 1"), so it is only used for a
+ * validator with no address of its own (as the tests' are).
+ * @returns {Promise<Object>} the OperationOutcome the service answers with
+ */
+function loadIG(validator, packageId, version) {
+  if (!validator.baseUrl) {
+    return validator.loadIG(packageId, version);
+  }
+  const body = JSON.stringify({ ig: `${packageId}#${version}` });
+  const url = new URL(`${validator.baseUrl}/loadIG`);
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      hostname: url.hostname, port: url.port, path: url.pathname, method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Accept': 'application/fhir+json', 'Content-Length': Buffer.byteLength(body) }
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        try {
+          resolve(JSON.parse(text));
+        } catch (e) {
+          reject(new Error(`The validator answered HTTP ${res.statusCode} with a response that is not JSON (${text.length} bytes)`));
+        }
+      });
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    // loading a package can mean downloading it, and its dependencies
+    req.setTimeout(LOAD_IG_TIMEOUT_MS, () => req.destroy(new Error('The validator took too long to load the package')));
+    req.end(body);
+  });
+}
+
+/**
+ * What's wrong with a national profile's details, or null: a jurisdiction (a country's ISO 3166
+ * two-letter code, or a region's UN M49 three-digit code - see jurisdictions.js), a FHIR package id (lower case, at
+ * least two parts separated by dots), a version (as package versions are written), and the
+ * canonical URL (http or https) of the IG's profile on Bundle.
+ */
+function nationalProfileProblem(jurisdiction, packageId, version, url) {
+  if (!jurisdictionOf(jurisdiction)) {
+    return 'The jurisdiction must be a country, by its ISO 3166 two-letter code (e.g. AU), or a region, by its UN M49 three-digit code (e.g. 150 for Europe)';
+  }
+  if (packageId.length > 128 || !/^[a-z0-9][a-z0-9_-]*(\.[a-z0-9][a-z0-9_-]*)+$/.test(packageId)) {
+    return 'The package id must be a FHIR package id: lower case letters, digits, - and _, in two or more parts separated by dots (e.g. hl7.fhir.au.ips)';
+  }
+  if (!/^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/.test(version)) {
+    return 'The version must be a package version (e.g. 1.0.0, or 1.1.0-ballot)';
+  }
+  if (url.length > 1024 || !/^https?:\/\/[^\s/?#]+(?:[/?#]\S*)?$/.test(url)) {
+    return 'The profile must be the canonical URL (http or https) of the IG\'s profile on Bundle';
+  }
+  return null;
+}
 
 /**
  * What's wrong with a submitted document, if anything.
@@ -165,25 +229,6 @@ function preferValue(req, name) {
   return null;
 }
 
-// the browser scripts: the module's own files, read once and served from memory (so no
-// request reaches the file system), with an ETag so a browser can keep its copy
-const SCRIPTS = new Map();
-function script(name) {
-  if (!SCRIPTS.has(name)) {
-    const body = fs.readFileSync(path.join(__dirname, name), 'utf8');
-    SCRIPTS.set(name, { body, etag: `"${crypto.createHash('sha256').update(body).digest('base64url').substring(0, 27)}"` });
-  }
-  const s = SCRIPTS.get(name);
-  return (req, res) => {
-    res.setHeader('Cache-Control', 'public, max-age=3600');
-    res.setHeader('ETag', s.etag);
-    if (req.get('If-None-Match') === s.etag) {
-      return res.status(304).end();
-    }
-    res.type('application/javascript').send(s.body);
-  };
-}
-
 function wantsHtml(req) {
   const f = req.query._format;
   if (typeof f === 'string' && f !== '') {
@@ -308,6 +353,7 @@ class IpsModule {
     this.setupSession();
     this.setupRootRoutes();
     this.setupProfileRoutes();
+    this.setupNationalProfileRoutes();
     this.setupProjectRoutes();
     this.setupValidator();
     this.setupValueSets();
@@ -451,7 +497,7 @@ class IpsModule {
       next();
     };
 
-    r.get('/profile-editor.js', script('profile-editor.js'));
+    r.get('/profile-editor.js', scripts.handler('profile-editor.js'));
     r.get('/lookup', this.session, adminJson, ...this.lookups, h('lookup', (req, res) => this.systemLookup(req, res)));
     r.get('/lookup-vs', this.session, adminJson, ...this.lookups, h('lookup', (req, res) => this.valueSetLookup(req, res)));
     r.get('/StructureDefinition', ...this.web, h('profiles', (req, res) => this.profileList(req, res)));
@@ -460,12 +506,37 @@ class IpsModule {
     r.get('/StructureDefinition/:id', profile, ...this.web, h('profile', (req, res) => this.profileRead(req, res)));
     r.get('/StructureDefinition/:id/edit', profile, this.session, this.csrf, admin, h('profile', (req, res) => this.profileEditor(req, res, req.profile)));
     r.post('/StructureDefinition/:id', profile, this.sameOrigin, this.session, json, this.csrf, adminJson, h('profile', (req, res) => this.profileSave(req, res, req.profile)));
+    // one constraint at a time, from the profile's page: add, edit (keeping its key), delete
+    r.post('/StructureDefinition/:id/constraint', profile, this.sameOrigin, this.session, json, this.csrf, adminJson, h('profile', (req, res) => this.constraintSave(req, res, null)));
+    r.post('/StructureDefinition/:id/constraint/:key', profile, this.sameOrigin, this.session, json, this.csrf, adminJson, h('profile', (req, res) => this.constraintSave(req, res, req.params.key)));
+    r.post('/StructureDefinition/:id/constraint/:key/delete', profile, this.sameOrigin, this.session, this.form, this.csrf, admin, h('profile', (req, res) => this.constraintDelete(req, res)));
     r.post('/StructureDefinition/:id/delete', profile, this.sameOrigin, this.session, this.form, this.csrf, admin, h('profile', (req, res) => {
       this.store.deleteProfile(req.profileId);
       res.redirect(req.baseUrl + '/StructureDefinition');
     }));
   }
 
+  /**
+   * The national profiles, across all projects: everyone can see them, only the administrator
+   * adds, edits and deletes them. Before the project routes, so /national-profiles isn't taken
+   * for a project code.
+   */
+  setupNationalProfileRoutes() {
+    const r = this.router;
+    const h = (name, fn) => (req, res) => this.handle(req, res, name, () => fn(req, res));
+    const admin = this.adminOnly;
+    r.get('/national-profiles', ...this.web, h('national-profiles', (req, res) => this.sendNationalProfiles(req, res)));
+    r.post('/national-profiles', this.sameOrigin, this.session, this.form, this.csrf, admin, h('national-profiles', (req, res) => this.saveNationalProfile(req, res, null)));
+    r.post('/national-profiles/:id', this.sameOrigin, this.session, this.form, this.csrf, admin, h('national-profiles', (req, res) => this.saveNationalProfile(req, res, req.params.id)));
+    r.post('/national-profiles/:id/delete', this.sameOrigin, this.session, this.form, this.csrf, admin, h('national-profiles', (req, res) => {
+      const np = /^\d{1,15}$/.test(req.params.id) ? this.store.nationalProfile(parseInt(req.params.id, 10)) : null;
+      if (np && this.store.deleteNationalProfile(np.id)) {
+        this.log.info(`IPS module: national profile ${np.packageId}#${np.version} deleted`);
+      }
+      res.redirect(req.baseUrl + '/national-profiles');
+    }));
+  }
+
   setupProjectRoutes() {
     const r = this.router;
     const h = (name, fn) => (req, res) => this.handle(req, res, name, () => fn(req, res));
@@ -509,7 +580,7 @@ class IpsModule {
       next();
     };
 
-    r.get('/editor.js', script('editor.js'));
+    r.get('/editor.js', scripts.handler('editor.js'));
     r.get('/:code', project, ...this.web, h('list', (req, res) => this.htmlList(req, res)));
     r.get('/:code/metadata', project, h('metadata', (req, res) => this.metadata(req, res)));
     // The submission form has no CSRF token and starts no session: submitting is open to
@@ -595,15 +666,22 @@ class IpsModule {
    * wait in the queue.
    */
   setupValidator() {
+    // the national profiles' packages, as they are loaded into the validator: id#version -> Promise
+    this.nationalPackages = new Map();
     const cfg = this.config.validator;
     if (!cfg || cfg.enabled === false) {
       this.log.warn('IPS module: no validator configured (modules.ips.validator) - documents will not be validated');
       return;
     }
     const FhirValidator = require('fhir-validator-wrapper');
-    const jar = folders.filePath('bin', 'validator_cli.jar');
+    // a jar of its own (a validator built locally, say): used as it is, never downloaded or
+    // updated; otherwise the released one in the data folder's bin directory, kept up to date
+    const localJar = typeof cfg.jar === 'string' && cfg.jar.trim() ? (path.isAbsolute(cfg.jar) ? cfg.jar : folders.filePath(cfg.jar)) : null;
+    const jar = localJar || folders.filePath('bin', 'validator_cli.jar');
     this.validator = new FhirValidator(jar, this.log);
     const settings = {
+      autoDownload: !localJar,
+      skipUpdateCheck: !!localJar,
       version: cfg.version || '4.0.1',
       txServer: cfg.txServer || 'http://tx.fhir.org/r4',
       txLog: cfg.txLog || folders.filePath('logs', 'ips-validator-tx.log'),
@@ -611,7 +689,7 @@ class IpsModule {
       igs: Array.isArray(cfg.packages) ? cfg.packages : ['hl7.fhir.uv.ips#1.1.0'],
       timeout: cfg.timeout || 120000
     };
-    this.log.info(`IPS module: starting the FHIR validator on port ${settings.port} (tx ${settings.txServer}; ${settings.igs.join(', ')})`);
+    this.log.info(`IPS module: starting the FHIR validator${localJar ? ` (${localJar})` : ''} on port ${settings.port} (tx ${settings.txServer}; ${settings.igs.join(', ')})`);
     this.validatorStarting = this.validator.start(settings).then(() => {
       this.log.info('IPS module: the FHIR validator is running');
     }).catch(e => {
@@ -622,6 +700,31 @@ class IpsModule {
     });
   }
 
+  /**
+   * Load a national profile's package into the validator - once: a package that loaded, or
+   * failed to (with why), is remembered until the national profiles are changed, so each
+   * document doesn't ask again. The validator's packages (modules.ips.validator.packages) are
+   * loaded when it starts; these are added to them.
+   * @returns {Promise<void>} rejects with the reason the package could not be loaded
+   */
+  loadNationalPackage(packageId, version) {
+    const key = `${packageId}#${version}`;
+    let p = this.nationalPackages.get(key);
+    if (!p) {
+      p = loadIG(this.validator, packageId, version).then(outcome => {
+        const bad = (Array.isArray(outcome?.issue) ? outcome.issue : []).filter(i => i && (i.severity === 'error' || i.severity === 'fatal'));
+        if (bad.length > 0 || outcome?.resourceType !== 'OperationOutcome') {
+          const why = bad.map(i => i.details?.text || i.diagnostics || i.code).filter(Boolean).join('; ') || 'the validator did not return an OperationOutcome';
+          throw new Error(`The validator could not load ${key}: ${why}`);
+        }
+        this.log.info(`IPS module: national profile package ${key} loaded into the validator`);
+      });
+      p.catch(e => this.log.warn(`IPS module: ${e.message}`));
+      this.nationalPackages.set(key, p);
+    }
+    return p;
+  }
+
   /** Read the value sets the terminology check holds documents to: the module's own, in ips/valuesets/. */
   setupValueSets() {
     try {
@@ -1295,6 +1398,52 @@ class IpsModule {
       render.renderSubmit(req.project, this.ctx(req, res), { needsToken: tokenConfigured(req.project.token), aiEnabled: this.store.projectAi(req.project).enabled === true, ...options }), Date.now(), req);
   }
 
+  // ---- national profiles ----
+
+  /** The national profiles: a page (with the administrator's forms), or JSON. */
+  sendNationalProfiles(req, res, message, status = 200) {
+    const list = this.store.nationalProfiles();
+    res.status(status);
+    if (!wantsHtml(req) && !message) {
+      return res.json(list.map(np => ({ jurisdiction: np.jurisdiction, packageId: np.packageId, version: np.version, url: np.url })));
+    }
+    this.sendHtml(res, 'National Profiles', render.renderNationalProfiles(list, this.ctx(req, res), message), Date.now(), req);
+  }
+
+  /** Add (id null) or change a national profile, from the form: packageId, version, url. */
+  saveNationalProfile(req, res, id) {
+    const field = (name) => (typeof req.body[name] === 'string' ? req.body[name].trim() : '');
+    const packageId = field('packageId');
+    const version = field('version');
+    const url = field('url');
+    // a country code is upper case; a region's is digits
+    const jurisdiction = field('jurisdiction').toUpperCase();
+    const problem = nationalProfileProblem(jurisdiction, packageId, version, url);
+    if (problem) {
+      return this.sendNationalProfiles(req, res, problem, 400);
+    }
+    const existing = this.store.nationalProfileByPackage(packageId, version);
+    if (id === null) {
+      if (existing) {
+        return this.sendNationalProfiles(req, res, `There is already a national profile for ${packageId}#${version}`, 409);
+      }
+      this.store.createNationalProfile(packageId, version, url, jurisdiction);
+      this.log.info(`IPS module: national profile ${packageId}#${version} (${jurisdiction}) added (${url})`);
+    } else {
+      const n = /^\d{1,15}$/.test(id) ? parseInt(id, 10) : -1;
+      if (existing && existing.id !== n) {
+        return this.sendNationalProfiles(req, res, `There is already a national profile for ${packageId}#${version}`, 409);
+      }
+      if (!this.store.updateNationalProfile(n, packageId, version, url, jurisdiction)) {
+        return this.sendNationalProfiles(req, res, 'That national profile no longer exists', 404);
+      }
+      this.log.info(`IPS module: national profile ${packageId}#${version} (${jurisdiction}) saved (${url})`);
+    }
+    // a package that failed to load is tried again
+    this.nationalPackages = new Map();
+    res.redirect(req.baseUrl + '/national-profiles');
+  }
+
   // ---- clinical profiles ----
 
   /** The clinical profiles: a page, or a FHIR searchset of the StructureDefinitions. */
@@ -1321,7 +1470,31 @@ class IpsModule {
       res.type('application/fhir+json');
       return res.send(JSON.stringify(sd));
     }
-    this.sendHtml(res, `Clinical Profile: ${sd.title}`, render.renderProfile(sd, { ...this.ctx(req, res), valueSetTitle: (url) => this.valueSetTitle(url) }), Date.now(), req);
+    const ctx = { ...this.ctx(req, res), valueSetTitle: (url) => this.valueSetTitle(url), profileTitle: (url) => this.profileTitle(url) };
+    // the administrator edits the rows in place, a row at a time
+    const editor = ctx.user?.isAdmin ? {
+      constraints: this.editorConstraints(sd),
+      sections: profiles.IPS_SECTIONS, systems: profiles.SYSTEMS, resourceTypes: profiles.RESOURCE_TYPES, sectionSystem: editorSchema.LOINC, canLookup: !!this.tx
+    } : null;
+    this.sendHtml(res, `Clinical Profile: ${sd.title}`, render.renderProfile(sd, ctx, editor), Date.now(), req);
+  }
+
+  /**
+   * What to call a profile a rule says resources conform to: one of the clinical profiles (by
+   * its title), or one of the national profiles (by its jurisdiction and package), or null.
+   */
+  profileTitle(url) {
+    if (typeof url !== 'string') {
+      return null;
+    }
+    const plain = url.split('|')[0];
+    const m = /\/StructureDefinition\/profile-([a-f0-9]{12})$/.exec(plain);
+    const sd = m ? this.store.profile(m[1]) : null;
+    if (sd && sd.url === plain) {
+      return sd.title;
+    }
+    const np = this.store.nationalProfiles().find(p => p.url === plain);
+    return np ? `${np.jurisdiction ? `${np.jurisdiction} ` : ''}national profile (${np.packageId}#${np.version})` : null;
   }
 
   /** The title of one of this module's own value sets, or null. */
@@ -1331,8 +1504,12 @@ class IpsModule {
   }
 
   /** The editor, for a new profile or an existing one. */
+  editorConstraints(sd) {
+    return profiles.constraintsOf(sd).map(c => ({ ...c, shape: profiles.parseShape(c.expression), rshape: profiles.parseResourceShape(c.expression) }));
+  }
+
   profileEditor(req, res, sd) {
-    const constraints = profiles.constraintsOf(sd).map(c => ({ ...c, shape: profiles.parseShape(c.expression), rshape: profiles.parseResourceShape(c.expression) }));
+    const constraints = this.editorConstraints(sd);
     this.sendHtml(res, sd ? `Edit Clinical Profile: ${sd.title}` : 'New Clinical Profile',
       render.renderProfileEditor(sd, this.ctx(req, res), {
         profile: { id: sd ? sd.id : null, title: sd ? sd.title : '', constraints },
@@ -1369,6 +1546,53 @@ class IpsModule {
     res.status(previous ? 200 : 201).json({ id: sd.id, url: `${req.baseUrl}/StructureDefinition/${sd.id}` });
   }
 
+  /**
+   * Add a constraint to a profile ({human, expression}), or replace one (by its key, which it
+   * keeps). 201/200 with {key}, 404 when there is no constraint with that key, 422 with {problems}.
+   */
+  constraintSave(req, res, key) {
+    const previous = req.profile;
+    const body = req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body : {};
+    const row = { key, human: body.human, expression: body.expression };
+    const constraints = profiles.constraintsOf(previous);
+    const at = key === null ? constraints.length : constraints.findIndex(c => c.key === key);
+    if (at < 0) {
+      return res.status(404).json({ problems: [`The profile has no constraint '${key}'`] });
+    }
+    // the row by itself first, so what is wrong is said of it, not of a number in the list
+    const alone = profiles.checkInput({ title: previous.title, constraints: [{ human: row.human, expression: row.expression }] }, null);
+    if (alone.problems.length) {
+      return res.status(422).json({ problems: alone.problems.map(p => p.replace(/^Constraint 1/, 'The rule')) });
+    }
+    constraints.splice(at, key === null ? 0 : 1, row);
+    const checked = profiles.checkInput({ title: previous.title, constraints }, previous);
+    if (checked.problems.length) {
+      return res.status(422).json({ problems: checked.problems });
+    }
+    this.saveConstraints(previous, checked.constraints);
+    this.log.info(`IPS module: clinical profile ${previous.id}: constraint ${checked.constraints[at].key} ${key === null ? 'added' : 'saved'}`);
+    res.status(key === null ? 201 : 200).json({ key: checked.constraints[at].key });
+  }
+
+  /** Delete one of a profile's constraints, back to the profile's page. */
+  constraintDelete(req, res) {
+    const previous = req.profile;
+    const constraints = profiles.constraintsOf(previous);
+    const at = constraints.findIndex(c => c.key === req.params.key);
+    if (at < 0) {
+      return htmlServer.sendErrorResponse(res, TEMPLATE, new Error(`The profile has no constraint '${req.params.key}'`), 404);
+    }
+    constraints.splice(at, 1);
+    this.saveConstraints(previous, constraints);
+    this.log.info(`IPS module: clinical profile ${previous.id}: constraint ${req.params.key} deleted`);
+    res.redirect(`${req.baseUrl}/StructureDefinition/${previous.id}`);
+  }
+
+  saveConstraints(previous, constraints) {
+    const id = previous.id.substring('profile-'.length);
+    this.store.saveProfile(id, profiles.build({ id, url: previous.url, title: previous.title, constraints }));
+  }
+
   // ---- the editor ----
 
   sendCompose(req, res) {
@@ -1597,6 +1821,7 @@ class IpsModule {
         ...this.ctx(req, res),
         steps: this.steps.map(st => st.name),
         level: typeof req.query.level === 'string' ? req.query.level : undefined,
+        np: typeof req.query.np === 'string' ? req.query.np : undefined,
         problemsOnly: req.query.problems === '1'
       };
       return this.sendHtml(res, `${req.project.name}: Document ${row.id}`, render.renderDocument(req.project, row, view, ctx), start, req);

package/ips/jurisdictions.js

@@ -0,0 +1,65 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+/**
+ * Jurisdictions, as http://hl7.org/fhir/ValueSet/jurisdiction has them: a country, by its
+ * ISO 3166-1 two-letter code (urn:iso:std:iso:3166), or a region, by its UN M49 three-digit
+ * code (http://unstats.un.org/unsd/methods/m49/m49.htm). The codes and names are the ones
+ * the terminology module's providers hold (tx/cs/cs-country.js, tx/cs/cs-areacode.js).
+ *
+ * @module ips/jurisdictions
+ */
+
+const { CountryCodeFactoryProvider } = require('../tx/cs/cs-country');
+const { AreaCodeFactoryProvider } = require('../tx/cs/cs-areacode');
+
+const ISO_3166 = 'urn:iso:std:iso:3166';
+const M49 = 'http://unstats.un.org/unsd/methods/m49/m49.htm';
+// in the country list, but not countries
+const UNKNOWN = new Set(['XX', 'ZZ']);
+
+let tables = null;
+
+/**
+ * The providers' code lists, read once. Only their data is wanted, not code system
+ * providers, so their load() runs on an object with no i18n (it only fills codes/codeMap).
+ */
+function load() {
+  if (!tables) {
+    const countries = Object.create(CountryCodeFactoryProvider.prototype);
+    const areas = Object.create(AreaCodeFactoryProvider.prototype);
+    // load() is async in form, but does its work synchronously
+    countries.load();
+    areas.load();
+    tables = { countries: countries.codeMap, areas: areas.codeMap };
+  }
+  return tables;
+}
+
+/**
+ * A jurisdiction by its code: two upper case letters (a country), or three digits (a
+ * region - an M49 region, not a country's numeric code).
+ * @param {string} code
+ * @returns {{system: string, code: string, display: string}|null} null if it is neither
+ */
+function jurisdiction(code) {
+  if (typeof code !== 'string') {
+    return null;
+  }
+  const t = load();
+  if (/^[A-Z]{2}$/.test(code)) {
+    const c = t.countries.get(code);
+    // not the user-assigned codes (XK, QM-QZ...), nor the 'unknown' ones (XX, ZZ): they aren't countries ISO 3166 names
+    return c && !c.userDefined && !UNKNOWN.has(code) ? { system: ISO_3166, code, display: c.display } : null;
+  }
+  if (/^\d{3}$/.test(code)) {
+    const a = t.areas.get(code);
+    return a && a.class_ === 'region' ? { system: M49, code, display: a.display } : null;
+  }
+  return null;
+}
+
+module.exports = { jurisdiction, ISO_3166, M49 };

package/ips/pipeline.js

@@ -12,10 +12,11 @@
  *   1. translate     translate CodeableConcepts that fail the terminology check to codes that pass it
  *   2. narrative     generate the narrative with the IPS presenter (presenter.js), into the analysed copy
  *   3. validation    validate the (translated) document with the FHIR validator (fhir-validator-wrapper)
- *   4. terminology   check each CodeableConcept against the value sets for international exchange
- *   5. piqi          measure the quality of the document with PIQI                        (not yet)
- *   6. profiles      check the document against each clinical profile (profiles.js)
- *   7. ai            assess the document for consistency and its terminology with an AI service (ai-client.js)
+ *   4. national      validate it against each national profile (the national IGs' profiles on Bundle)
+ *   5. terminology   check each CodeableConcept against the value sets for international exchange
+ *   6. piqi          measure the quality of the document with PIQI                        (not yet)
+ *   7. profiles      check the document against each clinical profile (profiles.js)
+ *   8. ai            assess the document for consistency and its terminology with an AI service (ai-client.js)
  *
  * Each step is { name, run(row, project, module) -> result }. A step keeps what it finds in
  * one of two places: as a result stored against the document (store.saveResult - the
@@ -122,6 +123,66 @@ const validation = {
   }
 };
 
+/**
+ * National profiles: the document is validated against each national profile - the
+ * national IG's package is loaded into the validator first (once), then the document is
+ * validated against the IG's profile on Bundle, as the validation step validates it. For
+ * each profile, the result keeps the OperationOutcome and whether the document passed: no
+ * errors (or fatal issues). A profile whose package can't be loaded, or that the validator
+ * can't validate against, is kept with the reason (pass is then null), and doesn't stop the
+ * pipeline.
+ */
+const national = {
+  name: 'national',
+  async run(row, project, module) {
+    const list = module.store.nationalProfiles();
+    const started = Date.now();
+    if (list.length === 0) {
+      module.store.saveResult(row.id, 'national', { ms: 0, profiles: [] });
+      return 'national profiles: none';
+    }
+    const v = module.validator;
+    if (!v) {
+      throw new Error('The validator is not configured (modules.ips.validator)');
+    }
+    if (!v.isRunning()) {
+      throw new Error('The validator is not running');
+    }
+    const cfg = module.config.validator || {};
+    const checkIpsCodes = cfg.checkIpsCodes !== false;
+    const doc = JSON.stringify(row.analysed || row.bundle);
+    const profiles = [];
+    for (const np of list) {
+      const entry = { id: np.id, jurisdiction: np.jurisdiction, packageId: np.packageId, version: np.version, url: np.url };
+      const t0 = Date.now();
+      try {
+        await module.loadNationalPackage(np.packageId, np.version);
+        const outcome = await v.validate(doc, { profiles: [np.url], checkIpsCodes, timeout: VALIDATE_TIMEOUT_MS });
+        if (!outcome || outcome.resourceType !== 'OperationOutcome') {
+          throw new Error('The validator did not return an OperationOutcome');
+        }
+        entry.counts = issueCounts(outcome);
+        entry.pass = !entry.counts.error && !entry.counts.fatal;
+        entry.outcome = outcome;
+      } catch (e) {
+        entry.pass = null;
+        entry.error = e.message;
+      }
+      entry.ms = Date.now() - t0;
+      profiles.push(entry);
+    }
+    module.store.saveResult(row.id, 'national', {
+      ms: Date.now() - started,
+      validatorVersion: typeof v.jarVersion === 'function' ? v.jarVersion() : null,
+      profiles
+    });
+    const passed = profiles.filter(p => p.pass === true).length;
+    const failed = profiles.filter(p => p.pass === false).length;
+    const unchecked = profiles.length - passed - failed;
+    return `national profiles: ${passed} passed, ${failed} failed` + (unchecked ? `, ${unchecked} not checked` : '');
+  }
+};
+
 // ---- the terminology check ------------------------------------------------------------
 
 /**
@@ -1003,10 +1064,10 @@ const aiStep = {
 };
 
 /** The steps, in order. Only the ones that exist yet. */
-const STEPS = [translate, narrative, validation, terminology, profilesStep, aiStep];
+const STEPS = [translate, narrative, validation, national, terminology, profilesStep, aiStep];
 
 module.exports = {
-  STEPS, translate, narrative, validation, terminology, profiles: profilesStep, ai: aiStep, checkConstraint, valueSetsIn, lookupDisplay, checkConcept, documentForAi, assessmentOf, aiSystemPrompt, AI_SYSTEM_PROMPT, checkOf, addCheck, stripChecks, translateConcept, translationOf,
+  STEPS, translate, narrative, validation, national, terminology, profiles: profilesStep, ai: aiStep, checkConstraint, valueSetsIn, lookupDisplay, checkConcept, documentForAi, assessmentOf, aiSystemPrompt, AI_SYSTEM_PROMPT, checkOf, addCheck, stripChecks, translateConcept, translationOf,
   validateCodeInValueSet, validateCodeInSystem, issueCounts, issueSummary,
   IPS_BUNDLE_PROFILE, CHECK_EXTENSION, TRANSLATION_EXTENSION, MAX_CHECKS_PER_DOCUMENT, MAX_CACHED_ANSWERS
 };