fhirsmith 0.14.2 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.15.0] - 2026-10-08
+
+### Added
+
+- Library YAML: a source can give the id prefix for the resources it loads (`npm:hl7.terminology=tho`), so their ids stay the same when sources are added, removed or reordered. Sources without one are numbered, as before. See Resource Ids in tx/README.md
+- `CapabilityStatement.software.releaseDate` (and the TerminologyCapabilities equivalent) is the date the running version was released, taken from its heading in CHANGELOG.md, which is now included in the Docker image. A snapshot reports the time the server started
+- Registry: the crawler records each server's `software.releaseDate`. The Software page uses it to date software other than FHIRsmith, and FHIRsmith releases (including development builds) that the release list doesn't know about yet
+
+### Changed
+
+- **Breaking - resource ids:** every CodeSystem, ValueSet and ConceptMap is served with an id in the id space of its source - `prefix-id`, e.g. `CodeSystem/tho-v3-ActCode` - and the FHIR core package each endpoint loads uses `core` (`CodeSystem/core-administrative-gender`). An unprefixed id is not found by read or by any `[type]/[id]/$operation`. Library CodeSystems used to keep the ids they had in their packages (ValueSets and ConceptMaps were already numbered), and so could clash with the endpoint's core CodeSystems
+- THO overrides the FHIR core packages the same way the Java validator does: where hl7.terminology has a url, the core package's CodeSystems, ValueSets and ConceptMaps with that url are not loaded at all. Older core versions used to stay available by `url|version`, so the server reported versions the validator doesn't know (e.g. v3-MaritalStatus `2018-08-12`). The exception is the R4 v2 tables 0006, 0360 and 0391, which R4 core has in two versions each with the version in the url: those versions stay available, and THO's is the default
+- `software.releaseDate` is no longer the time of the request
+
+### Fixed
+
+- Search: two CodeSystems with the same id from different packages (e.g. v3-MaritalStatus from hl7.fhir.r4.core and hl7.terminology) linked to the same resource, and a read of that id always returned the core one
+- On the R4 endpoint, a ValueSet asked for without a version (e.g. `http://terminology.hl7.org/ValueSet/v3-MaritalStatus`) was the core package's copy rather than hl7.terminology's
+
+### Tx Conformance Statement
+
+FHIRsmith v0.15.0 passed all 3585 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11+closure, tests v1.9.6, runner v7.0.0)
+
 ## [0.14.2] - 2026-10-06
 
 ### Security

package/library/changelog.js

@@ -0,0 +1,57 @@
+// library/changelog.js
+// Release dates from CHANGELOG.md. A release is dated in its heading when it is made -
+// "## [0.14.2] - 2026-10-06" (or "## [v0.13.4] - ...") - so the changelog that ships with
+// the code is where a server finds out when its own version was released. A snapshot's
+// heading has no date yet, so it has no release date.
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_PATH = path.join(__dirname, '..', 'CHANGELOG.md');
+const HEADING = /^##\s*\[v?(\d+\.\d+\.\d+)\]\s*-\s*(\d{4}-\d{2}-\d{2})\s*$/gm;
+
+/**
+ * @param {string} [changelogPath]
+ * @returns {Map<string, string>} version (no leading v) -> release date (YYYY-MM-DD).
+ *   Throws if the file can't be read.
+ */
+function readReleaseDates(changelogPath = DEFAULT_PATH) {
+  const text = fs.readFileSync(changelogPath, 'utf8');
+  const dates = new Map();
+  let m;
+  HEADING.lastIndex = 0;
+  while ((m = HEADING.exec(text)) !== null) {
+    if (!dates.has(m[1])) {
+      dates.set(m[1], m[2]);
+    }
+  }
+  return dates;
+}
+
+/**
+ * The release date of a version, or null if it isn't a dated release (a snapshot, or no
+ * changelog to read)
+ */
+function releaseDateOf(version, changelogPath = DEFAULT_PATH) {
+  try {
+    return readReleaseDates(changelogPath).get(String(version || '').replace(/^v/, '')) || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * The release date a server reports for its version: the date of the release, or, for a
+ * version that hasn't been released (a snapshot), the time the server started - which is
+ * when that build went into service.
+ *
+ * @param {string} version
+ * @param {Date} started - when the server started
+ * @param {string} [changelogPath]
+ * @returns {string} YYYY-MM-DD for a release, an ISO dateTime for a snapshot
+ */
+function reportedReleaseDate(version, started, changelogPath = DEFAULT_PATH) {
+  return releaseDateOf(version, changelogPath) || started.toISOString();
+}
+
+module.exports = { readReleaseDates, releaseDateOf, reportedReleaseDate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhirsmith",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "txVersion": "1.9.5-SNAPSHOT",
   "description": "A Node.js server that provides a collection of tools to serve the FHIR ecosystem",
   "main": "server.js",

package/registry/crawler.js

@@ -339,6 +339,20 @@ class RegistryCrawler {
     return version;
   }
 
+  /**
+   * CapabilityStatement.software.releaseDate, if it means anything. A date within a few
+   * minutes of now is the server's clock, not a release date: FHIRsmith up to 0.14.2 filled
+   * it in with the time of the request, and other software may do the same.
+   */
+  reportedReleaseDate(software, now = Date.now()) {
+    const value = software && software.releaseDate;
+    const t = value ? new Date(value).getTime() : NaN;
+    if (isNaN(t) || Math.abs(now - t) < 10 * 60 * 1000) {
+      return '';
+    }
+    return String(value);
+  }
+
   /**
    * A server that can't be reached this time is still running whatever it was running
    * last time we saw it - keep that, so the software page doesn't lose track of it
@@ -353,6 +367,7 @@ class RegistryCrawler {
           if (prev.address === version.address && prev.software) {
             version.software = prev.software;
             version.softwareVersion = prev.softwareVersion || '';
+            version.softwareReleaseDate = prev.softwareReleaseDate || '';
             return;
           }
         }
@@ -371,6 +386,7 @@ class RegistryCrawler {
     version.version = capability.fhirVersion || '3.0.2';
     version.software = capability.software ? capability.software.name : "unknown";
     version.softwareVersion = capability.software && capability.software.version ? String(capability.software.version) : '';
+    version.softwareReleaseDate = this.reportedReleaseDate(capability.software);
 
     // Get terminology capabilities (R3 uses Parameters resource)
     try {
@@ -416,6 +432,7 @@ class RegistryCrawler {
     version.version = capability.fhirVersion || defVersion;
     version.software = capability.software ? capability.software.name : "unknown";
     version.softwareVersion = capability.software && capability.software.version ? String(capability.software.version) : '';
+    version.softwareReleaseDate = this.reportedReleaseDate(capability.software);
 
     let set = new Set();
 

package/registry/fhirsmith-releases.js

@@ -6,7 +6,7 @@
 // succeeds (or if it can't be reached), the dated headings in this server's own
 // CHANGELOG.md are used instead - those only go up to this server's own version.
 
-const fs = require('fs');
+const { readReleaseDates } = require('../library/changelog');
 const path = require('path');
 const axios = require('axios');
 
@@ -72,12 +72,9 @@ class FhirsmithReleases {
    */
   loadFromChangelog(changelogPath = path.join(__dirname, '..', 'CHANGELOG.md')) {
     try {
-      const text = fs.readFileSync(changelogPath, 'utf8');
       const list = [];
-      const re = /^##\s*\[v?(\d+\.\d+\.\d+)\]\s*-\s*(\d{4}-\d{2}-\d{2})\s*$/gm;
-      let m;
-      while ((m = re.exec(text)) !== null) {
-        list.push({ version: m[1], date: new Date(m[2] + 'T00:00:00Z') });
+      for (const [version, date] of readReleaseDates(changelogPath)) {
+        list.push({ version, date: new Date(date + 'T00:00:00Z') });
       }
       this.setReleases(list, 'CHANGELOG.md');
     } catch (error) {

package/registry/model.js

@@ -12,6 +12,7 @@ class ServerVersionInformation {
     this.lastTat = '';
     this.software = ''; // what software is running
     this.softwareVersion = ''; // CapabilityStatement.software.version, if the server reports one
+    this.softwareReleaseDate = ''; // CapabilityStatement.software.releaseDate, if it is a real date
     this.codeSystems = []; // Array of strings (sorted, unique)
     this.valueSets = []; // Array of strings (sorted, unique)
   }
@@ -60,6 +61,7 @@ class ServerVersionInformation {
       terminologies: this.codeSystems,
       software: this.software,
       'software-version': this.softwareVersion,
+      'software-release-date': this.softwareReleaseDate,
       valuesets: this.valueSets
     };
   }
@@ -74,6 +76,7 @@ class ServerVersionInformation {
     instance.lastTat = json.lastTat || '';
     instance.software = json.software;
     instance.softwareVersion = json['software-version'] || '';
+    instance.softwareReleaseDate = json['software-release-date'] || '';
     instance.codeSystems = json.terminologies || [];
     instance.valueSets = json.valuesets || [];
     return instance;

package/registry/registry.js

@@ -512,6 +512,7 @@ class RegistryModule {
             fhirVersion: version.version || '',
             software: version.software && version.software !== 'unknown' ? version.software : '',
             softwareVersion: version.softwareVersion || '',
+            softwareReleaseDate: version.softwareReleaseDate || '',
             error: version.error,
             lastSuccess: version.lastSuccess
           });
@@ -556,7 +557,7 @@ class RegistryModule {
 
   _renderReleaseCells(row, now) {
     if (!isFhirsmith(row.software) || !this.releases) {
-      return '<td></td><td></td>';
+      return this._renderReportedReleaseCells(row, now);
     }
     const d = this.releases.describe(row.softwareVersion, now);
     const behind = d.behind ? ` (${d.behind} release${d.behind === 1 ? '' : 's'} behind)` : '';
@@ -571,11 +572,28 @@ class RegistryModule {
           `<td><span class="${cls}">${describeAge(d.ageDays)}${behind}</span></td>`;
       }
       case 'dev':
-        return '<td></td><td>development build' +
+        return `<td>${this._reportedReleaseDay(row)}</td><td>development build` +
           (d.release ? ` after v${escape(d.release.version)}` : '') + behind + '</td>';
       default:
-        return '<td></td><td><i>unknown</i></td>';
+        return this._renderReportedReleaseCells(row, now);
+    }
+  }
+
+  // what the server says about its release (CapabilityStatement.software.releaseDate) -
+  // the only source for software other than FHIRsmith
+  _reportedReleaseDay(row) {
+    // the day as the server gives it - converting to UTC can move it a day
+    const m = /^(\d{4}-\d{2}-\d{2})/.exec(row.softwareReleaseDate || '');
+    return m ? m[1] : '';
+  }
+
+  _renderReportedReleaseCells(row, now) {
+    const day = this._reportedReleaseDay(row);
+    if (!day) {
+      return '<td></td><td></td>';
     }
+    const days = Math.max(0, Math.floor((now - new Date(row.softwareReleaseDate).getTime()) / (24 * 60 * 60 * 1000)));
+    return `<td>${day}</td><td>${describeAge(days)}</td>`;
   }
 
   /**

package/tx/README.md

@@ -237,12 +237,28 @@ shouldn't be - too big. Note that that files in the list below are considered to
 Each source entry follows the format:
 
 ```
-type[!]:details
+type[!]:details[=prefix]
 ```
 
 - **type**: The source type (see Source Types below)
 - **!** (optional): Append to type to mark this source as the default for its code system. When multiple versions of the same code system are loaded, the default is used when no version is specified.
 - **details**: Type-specific configuration (filename, package name, or internal provider name)
+- **prefix** (optional): The id prefix for the resources the source provides - see [Resource Ids](#resource-ids). Everything after the last `=` in the entry is the prefix, so a `url` source whose url contains a `=` must give one.
+
+### Resource Ids
+
+Every CodeSystem, ValueSet and ConceptMap is served with an id in the id space of the source it came from: the source's prefix, `-`, and the id the resource has in the source. With
+
+```yaml
+- npm:hl7.terminology=tho
+```
+
+THO's v3-ActCode code system is `CodeSystem/tho-v3-ActCode`. No resource is served on the id it has in its source - different sources can use the same ids (hl7.terminology and the FHIR core packages both have a CodeSystem `v3-MaritalStatus`), so an unprefixed id can't say which one is meant, and it finds nothing.
+
+- A prefix may contain letters, digits and `.` (no `-`), up to 32 characters, and each prefix may only be given once
+- If a source isn't given a prefix, it gets a number. Numbers depend on the order of the sources (and on which sources provide which kinds of resource), so they change when the YAML changes. Give every source that provides resources a prefix if its ids should stay the same - i.e. on any server where people link to resources by id
+- `core` is the FHIR core package each endpoint loads for its FHIR version (`CodeSystem/core-administrative-gender`), and `x` is the code systems the server implements natively (`CodeSystem/x-...`); neither can be given as a prefix
+- Sources that only provide code systems natively (`internal`, `snomed`, `loinc` etc.) don't serve resources by id, so a prefix does nothing for them
 
 ### Source Types
 
@@ -464,9 +480,9 @@ sources:
   - snomed:sct_us_20250901.cache
   
   # FHIR packages
-  - npm:hl7.terminology
-  - npm:hl7.fhir.us.core
-  - npm:us.nlm.vsac
+  - npm:hl7.terminology=tho
+  - npm:hl7.fhir.us.core=us
+  - npm:us.nlm.vsac=vsac
 ```
 
 Also see tx.fhir.org.yml for the production configuration for tx.fhir.org

package/tx/cm/cm-api.js

@@ -1,22 +1,37 @@
+const { assignIdSpace } = require('../library/resource-ids');
+
 /**
  * Abstract base class for Concept Map providers
  * Defines the interface that all Concept Map providers must implement
  */
 class AbstractConceptMapProvider {
   /**
-   * {int} Unique number assigned to this provider
+   * {string} The prefix of this provider's id space (set by assignIds) - given for its source in the library
+   * YAML, autonumbered, or 'core' for an endpoint's core package. Every concept map this
+   * provider provides has an id that starts with spaceId + '-' (see tx/library/resource-ids.js)
    */
   spaceId;
 
   /**
-   * ensure that the ids on the Concept Maps are unique, if they are
-   * in the global namespace
+   * Put this provider in an id space: set spaceId, and prefix the ids of the concept maps it
+   * provides with spaceId + '-'. A provider is put in one id space, once - asking for a
+   * different one later is an error (see assignIdSpace)
    *
-   * @param {Set<String>} ids
+   * @param {string} spaceId
    */
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
-    throw new Error('assignIds must be implemented by AbstractConceptMapProvider subclass');
+  assignIds(spaceId) {
+    if (assignIdSpace(this, spaceId)) {
+      this.prefixIds();
+    }
+  }
+
+  /**
+   * Prefix the ids of the concept maps this provider provides with spaceId + '-', once spaceId
+   * is set (by assignIds). Concept maps the provider loads later must be given ids
+   * in the same space.
+   */
+  prefixIds() {
+    throw new Error('prefixIds must be implemented by AbstractConceptMapProvider subclass');
   }
 
   /**
@@ -32,11 +47,11 @@ class AbstractConceptMapProvider {
   }
 
   /**
-   * Fetches a specific Concept Map by id. ConceptMap providers must enforce that Concept Map ids are unique
-   * either globally (as enforced by assignIds) or in their space
+   * Fetches a specific Concept Map by id. The id is in this provider's space (spaceId + '-' +
+   * the concept map's own id); an id that isn't - including an unprefixed one - finds nothing
    *
    * @param {string} id - The id of the Concept Map
-   * @returns {Promise<ConceptMap>} The requested Concept Map
+   * @returns {Promise<ConceptMap>} The requested Concept Map, or null
    * @throws {Error} Must be implemented by subclasses
    */
   // eslint-disable-next-line no-unused-vars

package/tx/cm/cm-database.js

@@ -733,10 +733,6 @@ class ConceptMapDatabase {
     return { query, params };
   }
 
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
-    // nothing - we don't do any assigning.
-  }
 }
 
 module.exports = {

package/tx/cm/cm-package.js

@@ -5,6 +5,7 @@ const { ConceptMapDatabase } = require('./cm-database');
 const { VersionUtilities } = require('../../library/version-utilities');
 const {validateParameter} = require("../../library/utilities");
 const {ConceptMap} = require("../library/conceptmap");
+const { applyIdPrefix, stripIdPrefix } = require('../library/resource-ids');
 
 /**
  * Package-based ConceptMap provider using shared database layer
@@ -34,6 +35,7 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     if (this.initialized) {
       return;
     }
+    await this.packageLoader.initialize();
 
     const dbExists = await this.database.exists();
 
@@ -43,6 +45,8 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     }
 
     this.conceptMapMap = await this.database.loadAllConceptMaps();
+    // nothing, unless the spaceId was assigned before the provider was initialized
+    this.#applyIdPrefix();
     this.initialized = true;
   }
 
@@ -128,7 +132,9 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
     this._validateSearchParams(searchParams);
 
     if (this.USE_DATABASE_SEARCH) {
-      return await this.database.search(this.spaceId, searchParams, elements);
+      const results = await this.database.search(this.spaceId, searchParams, elements);
+      return this.#excludedIds.size === 0 ? results
+        : results.filter(r => !this.#excludedIds.has(stripIdPrefix(r.id, this.spaceId)));
     } else {
       const matches = [];
       const seen = new Set(); // Track by URL to avoid duplicates from versioned keys
@@ -194,9 +200,8 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
 
         if (isMatch) {
           seen.add(vsUrl);
-          // Return with prefixed id
-          const result = { ...json, id: `${this.spaceId}-${json.id}` };
-          matches.push(result);
+          // the id is already prefixed (see assignIds)
+          matches.push(json);
         }
       }
 
@@ -298,19 +303,53 @@ class PackageConceptMapProvider extends AbstractConceptMapProvider {
   }
 
   async fetchConceptMapById(id) {
-    if (!this.spaceId) {
-      return this.conceptMapMap.get(id);
-    } else if (id.startsWith(this.spaceId+"-")) {
-      let key = id.substring(this.spaceId.length + 1);
-      return this.conceptMapMap.get(key);
-    } else {
-      return null;
+    // the map is keyed by the concept map's own id (and its url); the concept map itself
+    // carries the prefixed id, which is how a url key that happens to match is excluded
+    const cm = this.conceptMapMap.get(stripIdPrefix(id, this.spaceId));
+    return cm && cm.id === id ? cm : null;
+  }
+
+  sourcePackage() {
+    return this.packageLoader.id();
+  }
+
+  // the concept maps left out by excludeUrls, by their own (unprefixed) id
+  #excludedIds = new Set();
+
+  /**
+   * Leave out the concept maps with any of these urls: they can't be fetched, they aren't
+   * found by search, and they aren't used for translation. The FHIR core package's concept
+   * maps are left out where hl7.terminology provides the same url (see
+   * Provider.applyTHOPrecedence). Must be called once the provider is initialized - the
+   * database is shared, so it isn't changed.
+   *
+   * @param {Set<string>} urls
+   */
+  excludeUrls(urls) {
+    const excluded = new Set();
+    for (const cm of this.conceptMapMap.values()) {
+      if (cm && urls.has(cm.url)) {
+        excluded.add(cm);
+      }
+    }
+    for (const [key, cm] of [...this.conceptMapMap]) {
+      if (excluded.has(cm)) {
+        this.conceptMapMap.delete(key);
+      }
     }
+    for (const cm of excluded) {
+      this.#excludedIds.add(stripIdPrefix(cm.id, this.spaceId) ?? cm.id);
+    }
+  }
+
+  prefixIds() {
+    this.#applyIdPrefix();
   }
 
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
-    // nothing - we don't do any assigning.
+  #applyIdPrefix() {
+    for (const cm of new Set(this.conceptMapMap.values())) {
+      applyIdPrefix(cm, this.spaceId);
+    }
   }
 
   async findConceptMapForTranslation(opContext, conceptMaps, sourceSystem, sourceScope, targetScope, targetSystem) {

package/tx/cs/cs-provider-api.js

@@ -1,22 +1,37 @@
+const { assignIdSpace } = require('../library/resource-ids');
+
 /**
  * Abstract base class for value set providers
  * Defines the interface that all value set providers must implement
  */
 class AbstractCodeSystemProvider {
   /**
-   * {int} Unique number assigned to this provider
+   * {string} The prefix of this provider's id space (set by assignIds) - given for its source in the library
+   * YAML, or autonumbered. Every code system this provider provides has an id that starts
+   * with spaceId + '-' (see tx/library/resource-ids.js)
    */
   spaceId;
 
   /**
-   * ensure that the ids on the code systems are unique, if they are
-   * in the global namespace
+   * Put this provider in an id space: set spaceId, and prefix the ids of the code systems it
+   * provides with spaceId + '-'. A provider is put in one id space, once - asking for a
+   * different one later is an error (see assignIdSpace)
    *
-   * @param {Set<String>} ids
+   * @param {string} spaceId
    */
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
-    throw new Error('assignIds must be implemented by subclass');
+  assignIds(spaceId) {
+    if (assignIdSpace(this, spaceId)) {
+      this.prefixIds();
+    }
+  }
+
+  /**
+   * Prefix the ids of the code systems this provider provides with spaceId + '-', once spaceId
+   * is set (by assignIds). Code systems the provider provides later (see
+   * getCodeSystemChanges) must be given ids in the same space.
+   */
+  prefixIds() {
+    throw new Error('prefixIds must be implemented by subclass');
   }
 
   /**

package/tx/cs/cs-provider-list.js

@@ -1,4 +1,5 @@
 const { AbstractCodeSystemProvider } = require('./cs-provider-api');
+const { applyIdPrefix } = require('../library/resource-ids');
 
 /**
  * Package-based ValueSet provider using shared database layer
@@ -11,18 +12,18 @@ class ListCodeSystemProvider extends AbstractCodeSystemProvider {
   codeSystems = [];
 
   /**
-   * ensure that the ids on the code systems are unique, if they are
-   * in the global namespace
-   *
-   * @param {Set<String>} ids
+   * prefix the ids of the code systems with this provider's spaceId. A code system without
+   * an id gets its position in the list
    */
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
+  prefixIds() {
+    let i = 0;
     for (const cs of this.codeSystems) {
-      if (!cs.id || ids.has("CodeSystem/"+cs.id)) {
-        cs.id = ""+ids.size;
+      i++;
+      const json = cs.jsonObj || cs;
+      if (!json.id) {
+        json.id = String(i);
       }
-      ids.add("CodeSystem/"+cs.id);
+      applyIdPrefix(cs, this.spaceId);
     }
   }
 

package/tx/library/resource-ids.js

@@ -0,0 +1,107 @@
+//
+// Resource ids in the server's id spaces
+//
+// Every CodeSystem, ValueSet and ConceptMap the server serves by id lives in the id space of
+// the provider that loaded it, and its id is the provider's prefix, a '-', then the id the
+// resource had in its source: "tho-v3-ActCode", "core-v3-MaritalStatus". The prefix is the
+// provider's spaceId: given in the library YAML (npm:hl7.terminology=tho), autonumbered by
+// the library when the YAML doesn't give one, and "core" for the FHIR core package each
+// endpoint loads for itself.
+//
+// No resource is served under its original id. Two sources can carry resources with the same
+// id (hl7.terminology and hl7.fhir.r4.core both have a CodeSystem v3-MaritalStatus), so an
+// unprefixed id can't say which one it means - and anything that looks a resource up by its
+// raw id must fail, rather than find whichever one happens to come first.
+//
+
+// resources whose id has been prefixed - so prefixing is idempotent, and a raw id that
+// happens to start with the prefix still gets one
+const prefixed = new WeakSet();
+
+/**
+ * Prefix a resource's id with spaceId. The resource is either a wrapper with a jsonObj
+ * (CodeSystem, ValueSet, ConceptMap) or a plain json object. Does nothing to a resource
+ * that has already been prefixed, or that has no id.
+ *
+ * @param {Object} resource
+ * @param {string} spaceId
+ */
+function applyIdPrefix(resource, spaceId) {
+  if (!resource || !spaceId || prefixed.has(resource)) {
+    return;
+  }
+  const json = resource.jsonObj || resource;
+  if (!json.id) {
+    return;
+  }
+  const id = `${spaceId}-${json.id}`;
+  json.id = id;
+  if (resource.jsonObj && Object.prototype.hasOwnProperty.call(resource, 'id')) {
+    resource.id = id;
+  }
+  prefixed.add(resource);
+}
+
+/**
+ * The id a resource had in its source, for an id served in spaceId - or null, if the id
+ * isn't in that space (including when it's a raw id, or there's no spaceId).
+ *
+ * @param {string} id
+ * @param {string} spaceId
+ * @returns {string|null}
+ */
+function stripIdPrefix(id, spaceId) {
+  if (!spaceId || typeof id !== 'string') {
+    return null;
+  }
+  const prefix = `${spaceId}-`;
+  return id.startsWith(prefix) && id.length > prefix.length ? id.substring(prefix.length) : null;
+}
+
+/**
+ * Whether a prefix given in the library YAML is acceptable. It's the start of an id, so it
+ * may only use id characters, and no '-', so that the prefix of any id is unambiguous.
+ * 'core' is the endpoints' own core package, and 'x' is the code system factories
+ * (CodeSystem/x-...), so neither is available.
+ *
+ * @param {string} prefix
+ * @returns {string|null} why the prefix isn't acceptable, or null if it is
+ */
+function checkIdPrefix(prefix) {
+  if (!/^[A-Za-z0-9.]{1,32}$/.test(prefix)) {
+    return `an id prefix may only contain letters, digits and '.' (up to 32 characters)`;
+  }
+  if (prefix === CORE_PREFIX || prefix === 'x') {
+    return `the id prefix '${prefix}' is reserved`;
+  }
+  return null;
+}
+
+/**
+ * Put a provider in an id space - the shared part of the providers' assignIds(spaceId).
+ * A provider is put in one id space, once: its resources are prefixed when it is, so
+ * moving it to another would leave them in the old one. Asking again for the same space
+ * does nothing.
+ *
+ * @param {Object} provider - a code system, value set or concept map provider
+ * @param {string} spaceId
+ * @returns {boolean} true if the provider has just been put in the space, and must now
+ *   prefix its resources' ids
+ */
+function assignIdSpace(provider, spaceId) {
+  if (!spaceId) {
+    throw new Error(`${provider.constructor.name}: no id space given`);
+  }
+  if (provider.spaceId) {
+    if (provider.spaceId === spaceId) {
+      return false;
+    }
+    throw new Error(`${provider.constructor.name} is already in the id space '${provider.spaceId}', so it can't be put in '${spaceId}'`);
+  }
+  provider.spaceId = spaceId;
+  return true;
+}
+
+const CORE_PREFIX = 'core';
+
+module.exports = { applyIdPrefix, stripIdPrefix, checkIdPrefix, assignIdSpace, CORE_PREFIX };