fhirsmith 0.14.2 → 0.15.0

package/tx/library.js

@@ -39,6 +39,7 @@ const { OCLValueSetProvider } = require('./ocl/vs-ocl');
 const { OCLConceptMapProvider } = require('./ocl/cm-ocl');
 const {UriServicesFactory} = require("./cs/cs-uri");
 const {debugLog} = require("./operation-context");
+const { checkIdPrefix } = require("./library/resource-ids");
 
 /**
  * This class holds all the loaded content ready for processing
@@ -72,6 +73,17 @@ class Library {
   packageSources = [];
   externalSources = [];
 
+  /**
+   * {Map<Object, string>} the id prefix the library YAML gives for the source a provider was
+   * loaded from (npm:hl7.terminology=tho), by provider
+   */
+  #sourcePrefixes = new Map();
+
+  /**
+   * {Set<string>} every id prefix the library YAML gives - autonumbered prefixes skip them
+   */
+  #givenPrefixes = new Set();
+
   baseUrl = null;
   cacheFolder = null;
   startTime = Date.now();
@@ -171,6 +183,8 @@ class Library {
 
     this.log.info('Fetching Data from '+this.baseUrl);
 
+    this.#checkSourcePrefixes(config.sources);
+
     for (const source of config.sources) {
       try {
         await this.processSource(source, this.packageManager, "fetch");
@@ -223,15 +237,20 @@ class Library {
     this.assignIds();
   }
 
-  async processSource(source, packageManager, mode) {
-    // Parse the source string
+  /**
+   * Parse a source entry from the library YAML: type[!]:details[=prefix]
+   *
+   * @param {string} source
+   * @returns {{type: string, details: string, isDefault: boolean, prefix: string|null}}
+   */
+  #parseSource(source) {
     const colonIndex = source.indexOf(':');
     if (colonIndex === -1) {
       throw new Error(`Invalid source format: ${source}`);
     }
 
     let type = source.substring(0, colonIndex);
-    const details = source.substring(colonIndex + 1);
+    let details = source.substring(colonIndex + 1);
 
     // Handle special markers (like ! for default)
     let isDefault = false;
@@ -240,6 +259,59 @@ class Library {
       isDefault = true;
     }
 
+    // the id prefix for the resources the source provides: everything after the last '='
+    let prefix = null;
+    const eqIndex = details.lastIndexOf('=');
+    if (eqIndex > -1) {
+      prefix = details.substring(eqIndex + 1);
+      details = details.substring(0, eqIndex);
+      const problem = checkIdPrefix(prefix);
+      if (problem) {
+        throw new Error(`Invalid source '${source}': ${problem}`);
+      }
+    }
+    return { type, details, isDefault, prefix };
+  }
+
+  /**
+   * Check the id prefixes the library YAML gives before anything is loaded - each id space
+   * must belong to one source
+   *
+   * @param {string[]} sources
+   */
+  #checkSourcePrefixes(sources) {
+    const seen = new Map();
+    for (const source of sources) {
+      const { prefix } = this.#parseSource(source);
+      if (prefix) {
+        if (seen.has(prefix)) {
+          throw new Error(`The id prefix '${prefix}' is given for both '${seen.get(prefix)}' and '${source}'`);
+        }
+        seen.set(prefix, source);
+      }
+    }
+  }
+
+  async processSource(source, packageManager, mode) {
+    const { type, details, isDefault, prefix } = this.#parseSource(source);
+
+    // the providers this source adds, so they can be given its id prefix
+    const csCount = this.codeSystemProviders.length;
+    const vsCount = this.valueSetProviders.length;
+    const cmCount = this.conceptMapProviders.length;
+
+    await this.#loadSource(type, details, isDefault, mode, packageManager);
+
+    if (prefix) {
+      this.#givenPrefixes.add(prefix);
+      for (const provider of [...this.codeSystemProviders.slice(csCount),
+        ...this.valueSetProviders.slice(vsCount), ...this.conceptMapProviders.slice(cmCount)]) {
+        this.#sourcePrefixes.set(provider, prefix);
+      }
+    }
+  }
+
+  async #loadSource(type, details, isDefault, mode, packageManager) {
     // Switch statement for different source types
     switch (type) {
       case 'internal':
@@ -1000,6 +1072,7 @@ class Library {
     // Now add the existing value set providers after the FHIR core packages
     provider.valueSetProviders.push(...this.valueSetProviders);
     provider.conceptMapProviders.push(...this.conceptMapProviders);
+    provider.applyTHOPrecedence();
 
     // bind UCUM common value set
     let ucum = provider.codeSystemFactories.get("http://unitsofmeasure.org");
@@ -1030,30 +1103,29 @@ class Library {
   }
 
   /**
-   * all the loaded resources must have unique IDs for the get operation
-   * they must be assigned by the library on loading. providers can either assign
-   * ids from the global space at start up, or, if they can provide new resources
-   * later in an ongoing fashion, allocate them in their own space
+   * Every loaded resource is served in the id space of the provider that loaded it: its id is
+   * the provider's spaceId, '-', and the id it had in its source (see
+   * tx/library/resource-ids.js). The spaceId is the prefix the library YAML gives for the
+   * provider's source, or, if it gives none, a number - the next one, counting providers of
+   * the same kind, that the YAML doesn't use as a prefix. Numbers depend on the order of the
+   * sources, so a source whose ids should stay the same when the YAML changes needs a prefix.
+   *
+   * (Code system factories don't have ids - they are not available directly.)
    */
   assignIds() {
-    let ids = new Set();
-    // these don't have ids - not available directly for (const cs of this.codeSystemFactories) { .. }
-    let i = 0;
-    for (const cp of this.codeSystemProviders) {
-      cp.spaceId = String(++i);
-      cp.assignIds(ids);
-    }
-    i = 0;
-    for (const vp of this.valueSetProviders) {
-      vp.spaceId = String(++i);
-      vp.assignIds(ids);
-    }
-    i = 0;
-    for (const cmp of this.conceptMapProviders) {
-      cmp.spaceId = String(++i);
-      cmp.assignIds(ids);
+    for (const providers of [this.codeSystemProviders, this.valueSetProviders, this.conceptMapProviders]) {
+      let n = 0;
+      for (const provider of providers) {
+        let spaceId = this.#sourcePrefixes.get(provider);
+        if (!spaceId) {
+          do {
+            n++;
+          } while (this.#givenPrefixes.has(String(n)));
+          spaceId = String(n);
+        }
+        provider.assignIds(spaceId);
+      }
     }
-
   }
 
   async close() {

package/tx/ocl/cm-ocl.cjs

@@ -3,6 +3,7 @@ const { ConceptMap } = require('../library/conceptmap');
 const { PAGE_SIZE } = require('./shared/constants');
 const { createOclHttpClient } = require('./http/client');
 const { fetchAllPages, extractItemsAndNext } = require('./http/pagination');
+const { stripIdPrefix } = require('../library/resource-ids');
 
 const DEFAULT_MAX_SEARCH_PAGES = 10;
 
@@ -24,7 +25,7 @@ class OCLConceptMapProvider extends AbstractConceptMapProvider {
     this._canonicalBySourceUrl = new Map();
   }
 
-  assignIds(ids) {
+  prefixIds() {
     if (!this.spaceId) {
       return;
     }
@@ -33,13 +34,18 @@ class OCLConceptMapProvider extends AbstractConceptMapProvider {
     this._idMap.clear();
 
     for (const cm of unique) {
-      if (!cm.id.startsWith(`${this.spaceId}-`)) {
-        const nextId = `${this.spaceId}-${cm.id}`;
-        cm.id = nextId;
-        cm.jsonObj.id = nextId;
-      }
+      this.#prefixId(cm);
       this._idMap.set(cm.id, cm);
-      ids.add(`ConceptMap/${cm.id}`);
+    }
+  }
+
+  // concept maps are served in this provider's id space - including the ones that arrive
+  // after the spaceId is assigned
+  #prefixId(cm) {
+    if (this.spaceId && cm.id && !cm.id.startsWith(`${this.spaceId}-`)) {
+      const nextId = `${this.spaceId}-${cm.id}`;
+      cm.id = nextId;
+      cm.jsonObj.id = nextId;
     }
   }
 
@@ -56,7 +62,7 @@ class OCLConceptMapProvider extends AbstractConceptMapProvider {
 
     const mappingId = this.#extractMappingId(url);
     if (mappingId) {
-      return await this.fetchConceptMapById(mappingId);
+      return await this.#fetchMappingById(mappingId);
     }
 
     try {
@@ -81,14 +87,15 @@ class OCLConceptMapProvider extends AbstractConceptMapProvider {
     if (this._idMap.has(id)) {
       return this._idMap.get(id);
     }
+    // only ids in this provider's space - the rest is the OCL mapping id
+    const rawId = stripIdPrefix(id, this.spaceId);
+    return rawId ? await this.#fetchMappingById(rawId) : null;
+  }
 
-    let rawId = id;
-    if (this.spaceId && id.startsWith(`${this.spaceId}-`)) {
-      rawId = id.substring(this.spaceId.length + 1);
-    }
-
-    if (this._idMap.has(rawId)) {
-      return this._idMap.get(rawId);
+  async #fetchMappingById(rawId) {
+    const id = this.spaceId ? `${this.spaceId}-${rawId}` : rawId;
+    if (this._idMap.has(id)) {
+      return this._idMap.get(id);
     }
 
     try {
@@ -378,6 +385,7 @@ class OCLConceptMapProvider extends AbstractConceptMapProvider {
   }
 
   #indexConceptMap(cm) {
+    this.#prefixId(cm);
     this.conceptMapMap.set(cm.url, cm);
     if (cm.version) {
       this.conceptMapMap.set(`${cm.url}|${cm.version}`, cm);

package/tx/ocl/cs-ocl.cjs

@@ -92,15 +92,12 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
     }
   }
 
-  assignIds(ids) {
+  prefixIds() {
+    const codeSystems = [...new Set(this._idToCodeSystem.values())];
     this._usedIds.clear();
-    for (const cs of this._idToCodeSystem.values()) {
-      if (!cs.id || ids.has(`CodeSystem/${cs.id}`)) {
-        cs.id = String(ids.size);
-        cs.jsonObj.id = cs.id;
-      }
-      ids.add(`CodeSystem/${cs.id}`);
-      this._usedIds.add(cs.id);
+    this._idToCodeSystem.clear();
+    for (const cs of codeSystems) {
+      this.#trackCodeSystemId(cs);
       this._idToCodeSystem.set(cs.id, cs);
     }
   }
@@ -358,9 +355,11 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
       return;
     }
 
-    if (!cs.id || this._usedIds.has(cs.id)) {
+    // code systems are served in this provider's id space
+    const prefix = this.spaceId ? `${this.spaceId}-` : '';
+    if (!cs.id || !cs.id.startsWith(prefix) || this._usedIds.has(cs.id)) {
       const raw = cs.id || cs.name || cs.url || 'ocl-cs';
-      const base = this.spaceId ? `${this.spaceId}-${raw}` : String(raw);
+      const base = raw.startsWith(prefix) ? String(raw) : `${prefix}${raw}`;
       let candidate = base;
       let index = 1;
       while (this._usedIds.has(candidate)) {

package/tx/ocl/vs-ocl.cjs

@@ -114,6 +114,7 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
             id: cached.canonicalUrl
           }, 'R5');
           this.#applyCachedCompose(valueSetObj, paramsKey);
+          this.#prefixId(valueSetObj);
           // Indexa o ValueSet restaurado para torná-lo disponível via fetchValueSet
           this.valueSetMap.set(valueSetObj.url, valueSetObj);
           if (valueSetObj.version) {
@@ -224,7 +225,7 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
     }
   }
 
-  assignIds(ids) {
+  prefixIds() {
     if (!this.spaceId) {
       return;
     }
@@ -233,13 +234,18 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
     this._idMap.clear();
 
     for (const vs of unique) {
-      if (!vs.id.startsWith(`${this.spaceId}-`)) {
-        const nextId = `${this.spaceId}-${vs.id}`;
-        vs.id = nextId;
-        vs.jsonObj.id = nextId;
-      }
+      this.#prefixId(vs);
       this._idMap.set(vs.id, vs);
-      ids.add(`ValueSet/${vs.id}`);
+    }
+  }
+
+  // value sets are served in this provider's id space - including the ones that arrive
+  // after the spaceId is assigned
+  #prefixId(vs) {
+    if (this.spaceId && vs.id && !vs.id.startsWith(`${this.spaceId}-`)) {
+      const nextId = `${this.spaceId}-${vs.id}`;
+      vs.id = nextId;
+      vs.jsonObj.id = nextId;
     }
   }
 
@@ -345,16 +351,9 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
   }
 
   #getLocalValueSetById(id) {
-    if (this._idMap.has(id)) {
-      return this._idMap.get(id);
-    }
-
-    if (this.spaceId && id.startsWith(`${this.spaceId}-`)) {
-      const unprefixed = id.substring(this.spaceId.length + 1);
-      return this._idMap.get(id) || this._idMap.get(unprefixed) || this.valueSetMap.get(unprefixed) || null;
-    }
-
-    return this._idMap.get(id) || this.valueSetMap.get(id) || null;
+    // _idMap is keyed by the ids the value sets are served with - prefixed, once the
+    // spaceId is assigned
+    return this._idMap.get(id) || null;
   }
 
   // eslint-disable-next-line no-unused-vars
@@ -391,6 +390,7 @@ class OCLValueSetProvider extends AbstractValueSetProvider {
   }
 
   #indexValueSet(vs) {
+    this.#prefixId(vs);
     const existing = this.valueSetMap.get(vs.url) || null;
 
     // When fresh discovery metadata replaces a cold-cached entry, carry over

package/tx/provider.js

@@ -9,6 +9,7 @@ const {PackageContentLoader} = require("../library/package-manager");
 const {PackageValueSetProvider} = require("./vs/vs-package");
 const ValueSet = require("./library/valueset");
 const {PackageConceptMapProvider} = require("./cm/cm-package");
+const { applyIdPrefix, CORE_PREFIX } = require("./library/resource-ids");
 
 /**
  * This class holds what information is in context
@@ -153,6 +154,12 @@ class Provider {
   }
 
 
+  /**
+   * Load the FHIR core package for this endpoint. Its resources are served in the 'core' id
+   * space (CodeSystem/core-v3-MaritalStatus): the core packages for different FHIR versions
+   * share ids, and so does other content (hl7.terminology), so no endpoint can serve them on
+   * their own ids (see tx/library/resource-ids.js)
+   */
   async loadNpm(packageManager, cacheFolder,  details, isDefault, mode) {
     // Parse packageId and version from details (e.g., "hl7.terminology.r4#6.0.2")
     let packageId = details;
@@ -171,6 +178,9 @@ class Provider {
     await contentLoader.initialize();
 
     const resources = await contentLoader.getResourcesByType("CodeSystem");
+    let i = 0;
+    // the index has the urls as they are in the package; the version is taken out of the url
+    // when the code system is loaded (see normalizeVersionedCanonicals in package-manager.js)
     for (const resource of resources) {
       let cs;
       try {
@@ -183,13 +193,24 @@ class Provider {
         continue;
       }
       cs.sourcePackage = contentLoader.pid();
+      if (typeof resource.url === 'string' && resource.url.includes('|')) {
+        cs.urlHadVersion = true; // see addCodeSystem
+      }
+      // these objects belong to this endpoint, so they can be given ids here
+      i++;
+      if (!cs.id) {
+        cs.id = String(i);
+      }
+      applyIdPrefix(cs, CORE_PREFIX);
       this.addCodeSystem(cs);
     }
     const vs = new PackageValueSetProvider(contentLoader);
     await vs.initialize();
+    vs.assignIds(CORE_PREFIX);
     this.valueSetProviders.push(vs);
     const cm = new PackageConceptMapProvider(contentLoader);
     await cm.initialize();
+    cm.assignIds(CORE_PREFIX);
     this.conceptMapProviders.push(cm);
   }
 
@@ -582,27 +603,38 @@ class Provider {
     return pid != null && pid.startsWith("hl7.terminology");
   }
 
+  /**
+   * Add a code system to the ones this endpoint knows, by url and by url|version.
+   *
+   * THO precedence, as in CanonicalResourceManager.see() in the Java core: content that
+   * moved from the FHIR core packages to terminology.hl7.org has been QA'd there since, and
+   * its versions went backwards (coverage-selfpay is 4.0.1 in hl7.fhir.r4.core but 1.0.1 in
+   * hl7.terminology), so version precedence can't decide between them. Instead, a code system
+   * from an hl7.terminology package replaces every code system with the same url from a FHIR
+   * core package - none of the core versions stay available.
+   *
+   * Except: hl7.fhir.r4.core has the v2 tables 0006, 0360 and 0391 in two versions each,
+   * with the version in the url (http://terminology.hl7.org/CodeSystem/v2-0006|2.1 - see
+   * urlHadVersion in loadNpm). hl7.terminology doesn't publish those versions, so they stay
+   * available by url|version; THO's code system is the default for the url.
+   */
   addCodeSystem(cs) {
-    // Special case, mirroring CanonicalResourceManager.see() in the Java core:
-    // when content moved from the FHIR core packages to terminology.hl7.org,
-    // the versions went backwards (e.g. coverage-selfpay is 4.0.1 in
-    // hl7.fhir.r4.core (2019) but 1.0.1 in hl7.terminology (2024)), so plain
-    // version precedence would leave the stale core copy as the default. A
-    // resource from an hl7.terminology package displaces any same-URL
-    // resource that came from a FHIR core package, regardless of version.
     if (Provider.#isTHOPackage(cs.sourcePackage)) {
       for (const [key, t] of [...this.codeSystems]) {
-        // only the bare-url (default) entry is displaced; explicitly versioned
-        // entries (key = url|version) stay addressable, because the core packages
-        // carry historical versions (e.g. the normalized R4 v2 tables 0006/0360/0391
-        // at 2.1/2.3.1/2.4/2.6/2.7) that hl7.terminology does not publish at all
-        if (key === t.url && t.url === cs.url && VersionUtilities.isCorePackage(t.sourcePackage)) {
+        if (t.url === cs.url && VersionUtilities.isCorePackage(t.sourcePackage)
+          && (key === t.url || !t.urlHadVersion)) {
           this.codeSystems.delete(key);
         }
       }
+    } else if (VersionUtilities.isCorePackage(cs.sourcePackage) && !cs.urlHadVersion) {
+      // THO's code system is always the default for its url
+      const t = this.codeSystems.get(cs.url);
+      if (t && Provider.#isTHOPackage(t.sourcePackage)) {
+        return;
+      }
     }
     const existing = this.codeSystems.get(cs.url);
-    // the reverse guard: a core-package resource never displaces a THO one
+    // a core-package resource never displaces a THO one as the default
     const yieldsToTHO = existing && Provider.#isTHOPackage(existing.sourcePackage)
       && VersionUtilities.isCorePackage(cs.sourcePackage);
     if (!existing || (!yieldsToTHO && cs.isMoreRecent(existing))) {
@@ -619,6 +651,41 @@ class Provider {
     }
   }
 
+  /**
+   * THO precedence for value sets and concept maps, as for code systems (see addCodeSystem):
+   * once the library's providers have been added after this endpoint's core package, the core
+   * package's value sets and concept maps whose urls an hl7.terminology package also provides
+   * are left out. (No core value set or concept map has the version in its url.)
+   */
+  applyTHOPrecedence() {
+    const thoValueSets = new Set();
+    for (const vp of this.valueSetProviders) {
+      if (vp instanceof PackageValueSetProvider && Provider.#isTHOPackage(vp.sourcePackage())) {
+        for (const vs of vp.valueSetMap.values()) {
+          thoValueSets.add(vs.url);
+        }
+      }
+    }
+    const thoConceptMaps = new Set();
+    for (const cmp of this.conceptMapProviders) {
+      if (cmp instanceof PackageConceptMapProvider && Provider.#isTHOPackage(cmp.sourcePackage())) {
+        for (const cm of cmp.conceptMapMap.values()) {
+          thoConceptMaps.add(cm.url);
+        }
+      }
+    }
+    for (const vp of this.valueSetProviders) {
+      if (vp instanceof PackageValueSetProvider && VersionUtilities.isCorePackage(vp.sourcePackage())) {
+        vp.excludeUrls(thoValueSets);
+      }
+    }
+    for (const cmp of this.conceptMapProviders) {
+      if (cmp instanceof PackageConceptMapProvider && VersionUtilities.isCorePackage(cmp.sourcePackage())) {
+        cmp.excludeUrls(thoConceptMaps);
+      }
+    }
+  }
+
   deleteCodeSystem(cs) {
     this.codeSystems.delete(cs.vurl);
     this.codeSystems.delete(cs.url);

package/tx/tx.fhir.org.yml

@@ -1,6 +1,14 @@
 base:
   url: https://storage.googleapis.com/tx-fhir-org
 
+# Each source is type[!]:details[=prefix] - see tx/README.md.
+#
+# The prefix (after the last '=') is the id space for the resources the source provides:
+# with npm:hl7.terminology=tho, THO's v3-ActCode is CodeSystem/tho-v3-ActCode. Every
+# resource is served with a prefixed id - never the id it has in its source, which other
+# sources may share - and each endpoint's own FHIR core package uses 'core'. A source with
+# no prefix gets a number, which changes when sources are added, removed or reordered, so
+# any source whose resources people link to by id should have one.
 sources:
   - internal:lang
   - internal:country
@@ -29,14 +37,14 @@ sources:
   - snomed:sct_test_20250909b.cache
   - cpt:CodeSystem-cpt.db|cpt-2023-fragment-0.1.db
   - omop:omop_v20250227.db
-  - npm:hl7.terminology
-  - npm:fhir.tx.support
-  - npm:ihe.formatcode.fhir
-  - npm:fhir.dicom
-  - npm:hl7.fhir.us.core
-  - npm:us.cdc.phinvads
-  - npm:hl7.fhir.uv.sdc
-  - internal:vsac
+  - npm:hl7.terminology=tho
+  - npm:fhir.tx.support=tx
+  - npm:ihe.formatcode.fhir=ihe
+  - npm:fhir.dicom=dicom
+  - npm:hl7.fhir.us.core=us
+  - npm:us.cdc.phinvads=cdc
+  - npm:hl7.fhir.uv.sdc=sdc
+  - internal:vsac=vsac
   - icd11:icd11-2026-01.db
 
 ignored:

package/tx/tx.js

@@ -5,6 +5,10 @@
 // with support for multiple endpoints at different FHIR versions.
 //
 
+const { reportedReleaseDate } = require('../library/changelog');
+
+// when this server process started (the release date of a snapshot build)
+const SERVER_STARTED = new Date(Date.now() - process.uptime() * 1000);
 const express = require('express');
 const path = require('path');
 const fs = require('fs');
@@ -223,7 +227,9 @@ class TXModule {
       description: config.description || 'FHIR Terminology Server',
       contactUrl: config.contactUrl,
       contact: config.contact,
-      releaseDate: config.releaseDate,
+      // when this version was released, from its CHANGELOG.md heading - or, for a snapshot,
+      // when the server started
+      releaseDate: config.releaseDate || reportedReleaseDate(packageJson.version, SERVER_STARTED),
       host: config.host ? config.host : "localhost"
     });
 

package/tx/vs/vs-api.js

@@ -1,10 +1,14 @@
+const { assignIdSpace } = require('../library/resource-ids');
+
 /**
  * Abstract base class for value set providers
  * Defines the interface that all value set providers must implement
  */
 class AbstractValueSetProvider {
   /**
-   * {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 value set this
+   * provider provides has an id that starts with spaceId + '-' (see tx/library/resource-ids.js)
    */
   spaceId;
 
@@ -12,14 +16,25 @@ class AbstractValueSetProvider {
     throw new Error('code must be implemented by AbstractValueSetProvider subclass');
   }
   /**
-   * ensure that the ids on the value sets are unique, if they are
-   * in the global namespace
+   * Put this provider in an id space: set spaceId, and prefix the ids of the value sets 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 AbstractValueSetProvider subclass');
+  assignIds(spaceId) {
+    if (assignIdSpace(this, spaceId)) {
+      this.prefixIds();
+    }
+  }
+
+  /**
+   * Prefix the ids of the value sets this provider provides with spaceId + '-', once spaceId
+   * is set (by assignIds). Value sets the provider loads later must be given ids
+   * in the same space.
+   */
+  prefixIds() {
+    throw new Error('prefixIds must be implemented by AbstractValueSetProvider subclass');
   }
 
   /**
@@ -35,11 +50,11 @@ class AbstractValueSetProvider {
   }
 
   /**
-   * Fetches a specific value set by id. ValueSet providers must enforce that value set ids are unique
-   * either globally (as enforced by assignIds) or in their space
+   * Fetches a specific value set by id. The id is in this provider's space (spaceId + '-' + the
+   * value set's own id); an id that isn't - including an unprefixed one - finds nothing
    *
    * @param {string} id - The id of the value set
-   * @returns {Promise<ValueSet>} The requested value set
+   * @returns {Promise<ValueSet>} The requested value set, or null
    * @throws {Error} Must be implemented by subclasses
    */
   // eslint-disable-next-line no-unused-vars

package/tx/vs/vs-database.js

@@ -1114,10 +1114,6 @@ class ValueSetDatabase {
     return { query, params };
   }
 
-  // eslint-disable-next-line no-unused-vars
-  assignIds(ids) {
-    // nothing - we don't do any assigning.
-  }
 
   /**
    * Get a list of all ValueSet URLs in the database