fhirsmith 0.14.1 → 0.15.0

package/testing/openapi.js

@@ -0,0 +1,15 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+// The testing module's OpenAPI description: openapi.yaml (the paths, written by hand) plus
+// openapi-schemas.json (the FHIR resource schemas, generated from the R5 StructureDefinitions
+// by utilities/generate-openapi-schemas.js - see openapi-schemas.config.js).
+
+const path = require('path');
+const { createOpenApiDoc } = require('../library/openapi-doc');
+
+module.exports = createOpenApiDoc(path.join(__dirname, 'openapi.yaml'), '/testing',
+  { schemasPath: path.join(__dirname, 'openapi-schemas.json') });

package/testing/openapi.yaml

@@ -0,0 +1,273 @@
+# OpenAPI description of the FHIRsmith testing module (/testing): a FHIR API for TestReports.
+#
+# The paths are maintained here by hand. The FHIR resource schemas (TestReport,
+# OperationOutcome, Bundle, the datatypes they use, and TestReportSearchBundle) are generated
+# from the R5 StructureDefinitions into openapi-schemas.json, and merged into
+# components.schemas when the spec is served - see openapi-schemas.config.js.
+#
+# tests/testing/openapi.test.js keeps this honest: every route must be described here or
+# explicitly excluded, the search parameters must be the ones search.js understands, and
+# the TestReport schema must require everything validateReport() in testing.js requires.
+#
+# Administrative routes (DELETE, the login and admin pages) are deliberately not described.
+# info.version is filled in from package.json when the spec is served.
+
+openapi: 3.1.0
+info:
+  title: FHIRsmith Test Reports
+  version: "0.0.0"
+  summary: A FHIR repository for TestReports
+  description: |
+    Receives FHIR TestReports - from TxTester, and from any other tool that produces them -
+    and makes them available for reading and searching. This is a small FHIR R5 server with
+    one resource type, TestReport, and three interactions: create, read and search.
+
+    * **R4 and R5** TestReports are accepted alike (they differ only in `testScript`).
+    * **Reports are immutable**: the server assigns the id and `meta.lastUpdated`, drops
+      `meta.versionId`, and each POST is a new report, even of the same report.
+    * **Contained resources are not accepted.**
+    * The server checks only what the TestReport schema marks as required (and that
+      `issued` is a valid dateTime and `score` a number). The schema describes a valid
+      report; reports that don't conform to it in other ways may still be accepted, but
+      shouldn't be sent.
+
+    **Content negotiation.** Read and search return an HTML page to a browser (an
+    `Accept` containing `text/html`); `_format=json` or `_format=html` overrides that.
+  license:
+    name: BSD-3-Clause
+    url: https://opensource.org/license/bsd-3-clause
+externalDocs:
+  description: The TestReport resource (FHIR R5)
+  url: https://hl7.org/fhir/R5/testreport.html
+servers:
+  - url: /testing
+
+paths:
+  /TestReport:
+    post:
+      tags: [TestReport]
+      operationId: createTestReport
+      summary: Submit a report
+      description: |
+        Stores the report and returns it with its new id and `meta.lastUpdated`. Reports
+        are limited in size (500 KB by default) and submissions are rate limited.
+
+        If the server is configured with a token, every submission must carry it, in the
+        `Authorization` header by default (`Bearer <token>`; the header is configurable).
+      security:
+        - {}
+        - submitToken: []
+      parameters:
+        - name: Prefer
+          in: header
+          description: '`return=minimal` (no body), `return=representation` (the default), or `return=OperationOutcome`.'
+          schema: { type: string }
+          example: return=minimal
+      requestBody:
+        required: true
+        content:
+          application/fhir+json:
+            schema: { $ref: '#/components/schemas/TestReport' }
+          application/json:
+            schema: { $ref: '#/components/schemas/TestReport' }
+      responses:
+        '201':
+          description: Stored. The body is the stored report, nothing, or an OperationOutcome, as `Prefer` asks.
+          headers:
+            Location:
+              description: The new report's URL
+              schema: { type: string, format: uri }
+            Last-Modified:
+              schema: { type: string }
+          content:
+            application/fhir+json:
+              schema:
+                anyOf:
+                  - $ref: '#/components/schemas/TestReport'
+                  - $ref: '#/components/schemas/OperationOutcome'
+        '400': { $ref: '#/components/responses/Invalid' }
+        '401':
+          description: A token is required and wasn't supplied, or is wrong
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+        '413':
+          description: The report is too big
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+        '415':
+          description: The body isn't JSON
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+        '429':
+          description: Too many submissions; try again later
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+
+    get:
+      tags: [TestReport]
+      operationId: searchTestReports
+      summary: Search reports
+      description: |
+        Returns a searchset Bundle, newest received first unless `_sort` says otherwise.
+        `total` is always present.
+
+        Comma separated values are ORed; repeated parameters are ANDed. The search
+        parameters aren't yet formally defined as SearchParameter resources; their
+        behaviour is as described here. Modifiers are written after the name
+        (`name:exact=...`).
+
+        Unknown parameters are ignored, with a warning OperationOutcome entry
+        (`search.mode = outcome`) in the Bundle - unless the request has
+        `Prefer: handling=strict`, when they're a 400. Values that can't be understood (a
+        bad date or number) are always a 400.
+      parameters:
+        - name: _id
+          in: query
+          description: The report's id.
+          schema: { type: string }
+        - name: name
+          in: query
+          description: '`name` starts with this, case-insensitively. Modifiers: `:exact`, `:contains`, `:missing`.'
+          schema: { type: string }
+          example: tx-ecosystem
+        - name: tester
+          in: query
+          description: '`tester` starts with this, case-insensitively. Modifiers: `:exact`, `:contains`, `:missing`.'
+          schema: { type: string }
+        - name: status
+          in: query
+          description: '`status`, exactly (a `system|` prefix is ignored). Modifiers: `:not`, `:missing`.'
+          schema: { type: string }
+          example: completed
+        - name: result
+          in: query
+          description: '`result`, exactly. Modifiers: `:not`, `:missing`.'
+          schema: { type: string }
+          example: fail
+        - name: testscript
+          in: query
+          description: '`testScript` (the R5 canonical, or the R4 reference), exactly. Modifiers: `:below` (starts with), `:missing`.'
+          schema: { type: string }
+        - name: participant
+          in: query
+          description: 'The `uri` of any participant, exactly. Modifier: `:below` (starts with).'
+          schema: { type: string }
+          example: http://tx.fhir.org/r4
+        - name: score
+          in: query
+          description: '`score`, with a prefix (`eq` `ne` `gt` `lt` `ge` `le` `sa` `eb` `ap`); `eq` has implicit precision (`90` means 89.5 to 90.5). Modifier: `:missing`.'
+          schema: { type: string }
+          example: ge90
+        - name: issued
+          in: query
+          description: '`issued`, with a prefix; dates are ranges (`issued=2026-09` is all of September).'
+          schema: { type: string }
+          example: ge2026-09
+        - name: _lastUpdated
+          in: query
+          description: When the report was received, with a prefix.
+          schema: { type: string }
+        - name: _sort
+          in: query
+          description: Any of the parameters above except `_id`, comma separated, `-` for descending.
+          schema: { type: string }
+          example: -issued
+        - name: _count
+          in: query
+          description: Page size; defaults to 50, at most 500. `0` returns just the total.
+          schema: { type: integer, minimum: 0, maximum: 500 }
+        - name: _offset
+          in: query
+          description: Where the page starts. The Bundle has first, previous, next and last links.
+          schema: { type: integer, minimum: 0 }
+        - name: _summary
+          in: query
+          description: '`count` returns just the total.'
+          schema: { type: string, enum: [count] }
+        - name: _format
+          in: query
+          description: '`json` or `html`, overriding the `Accept` header.'
+          schema: { type: string }
+        - name: _total
+          in: query
+          description: Accepted, and has no effect - the total is always returned.
+          schema: { type: string }
+        - name: _pretty
+          in: query
+          description: Accepted, and has no effect - responses are always indented.
+          schema: { type: string }
+        - name: Prefer
+          in: header
+          description: '`handling=strict` makes unknown parameters an error.'
+          schema: { type: string }
+      responses:
+        '200':
+          description: The matching reports
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/TestReportSearchBundle' }
+            text/html:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/Invalid' }
+
+  /TestReport/{id}:
+    get:
+      tags: [TestReport]
+      operationId: readTestReport
+      summary: Read a report
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: The report, or a rendering of it for a browser
+          headers:
+            Last-Modified:
+              schema: { type: string }
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/TestReport' }
+            text/html:
+              schema: { type: string }
+        '404':
+          description: No such report
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/OperationOutcome' }
+
+  /metadata:
+    get:
+      tags: [server]
+      operationId: capabilities
+      summary: The server's CapabilityStatement
+      description: |
+        Lists the interactions and search parameters. The search parameters have no
+        definitions (see the search operation for what they do).
+      responses:
+        '200':
+          description: A CapabilityStatement
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/AnyResource' }
+
+components:
+  securitySchemes:
+    submitToken:
+      type: http
+      scheme: bearer
+      description: |
+        Required for submitting reports if the server is configured with a token. Sent in the
+        `Authorization` header by default; a server can be configured to use another header.
+
+  responses:
+    Invalid:
+      description: The request isn't acceptable - the issues say why
+      content:
+        application/fhir+json:
+          schema: { $ref: '#/components/schemas/OperationOutcome' }

package/testing/readme.md

@@ -13,7 +13,9 @@ makes them available through a FHIR API and a set of web pages. It runs at `/tes
 R4 and R5 TestReports are treated the same. A report is accepted if it is JSON, has
 `resourceType: TestReport`, and has `name`, `status`, `result`, `tester`, `issued` (a valid
 dateTime) and at least one `participant` with a `uri`. `score`, if present, must be a number.
-Nothing else is checked.
+Contained resources are not accepted. Nothing else is checked - but the TestReport schema in
+the OpenAPI description (below) says what a valid report looks like, and reports should
+conform to it.
 
 The server gives the report a new id (any id sent is ignored), sets `meta.lastUpdated` to the
 time it was received, and drops `meta.versionId`: reports can't be changed once received, so
@@ -65,6 +67,46 @@ Unknown parameters are ignored, with a warning OperationOutcome in the Bundle, u
 request has `Prefer: handling=strict`, in which case they're a 400. Values that can't be
 understood (a bad date or number) are always a 400.
 
+## OpenAPI description
+
+The FHIR API (create, read, search, metadata) is described by an OpenAPI 3.1 spec:
+
+| URL | |
+|---|---|
+| `/testing/openapi` | Browsable reference (HTML), with a "try it" form for each GET operation |
+| `/testing/openapi.json` | The spec as JSON |
+| `/testing/openapi.yaml` | The hand-written part, as YAML ([openapi.yaml](openapi.yaml)) |
+
+Every response carries a `Link: </testing/openapi.json>; rel="service-desc"` header (RFC 8631),
+and the HTML pages carry the matching `<link>` element. Deleting reports and the
+administration pages are deliberately not described.
+
+The spec is in two parts:
+
+* [openapi.yaml](openapi.yaml) - the paths, parameters and responses, written by hand
+* [openapi-schemas.json](openapi-schemas.json) - the FHIR schemas (TestReport, Bundle,
+  OperationOutcome, the datatypes they use, and `TestReportSearchBundle`), generated from the R5
+  StructureDefinitions by `library/fhir-openapi-schema.js`, as configured in
+  [openapi-schemas.config.js](openapi-schemas.config.js). The loader merges them into the spec.
+
+The generated schemas are closed (no properties FHIR doesn't define), include the `_x`
+siblings of primitive elements (so extensions on primitives, like `_name`, are allowed), and
+use the codes of required bindings as enums. Recursion is cut at two boundaries: an extension's
+value isn't described, and a resource inside another (`Bundle.entry.resource`) is "any resource"
+unless the config narrows it. `contained` is left out, so it isn't allowed. The config's overlay
+adds what this server requires beyond the base resource, and lets `testScript` be an R4
+Reference.
+
+After changing the config, regenerate (this needs `hl7.fhir.r5.core#5.0.0` in the
+terminology cache):
+
+    node utilities/generate-openapi-schemas.js testing
+
+`tests/testing/openapi.test.js` fails if the generated file is out of date, if a route or search
+parameter isn't described (or excluded), or if the TestReport schema doesn't require everything
+`validateReport()` requires. It also validates what the server actually returns (a stored
+report, a search Bundle, an OperationOutcome) against the schemas, using ajv.
+
 ## Web pages
 
 * `/testing` - the list of reports, with filters (these map onto the search parameters above),

package/testing/search.js

@@ -374,5 +374,5 @@ function capabilitySearchParams() {
 
 module.exports = {
   parseSearch, dateRange, splitValues, capabilitySearchParams,
-  PARAMS, DEFAULT_COUNT, MAX_COUNT
+  PARAMS, CONTROL, DEFAULT_COUNT, MAX_COUNT
 };

package/testing/testing-template.html

@@ -9,6 +9,7 @@
   <meta content="http://hl7.org/fhir" name="author"/>
   <meta charset="utf-8" http-equiv="X-UA-Compatible" content="IE=edge" />
 
+  <link rel="service-desc" type="application/json" href="/testing/openapi.json"/>
   <link rel="stylesheet" href="/fhir.css"/>
 
 
@@ -59,6 +60,7 @@
   <a href="/" style="color: gold"> Server Home</a> &nbsp;|&nbsp;
   <a href="/testing" style="color: gold">Test Reports</a>  &nbsp;|&nbsp;
   <a href="/testing/summary" style="color: gold">Summary</a>  &nbsp;|&nbsp;
+  <a href="/testing/openapi" style="color: gold">API</a>
 		</div>  <!-- /container -->
 		</div>  <!-- /container -->
 </div>

package/testing/testing.js

@@ -46,6 +46,7 @@ const { requireSameOrigin } = require('../library/same-origin');
 const packageJson = require('../package.json');
 const { TestReportStore } = require('./store');
 const { parseSearch, dateRange, capabilitySearchParams } = require('./search');
+const testingOpenApi = require('./openapi');
 const {
   renderList, renderSummary, renderReport, renderLogin, renderLinks, renderUsers, listQueryToSearch
 } = require('./render');
@@ -94,6 +95,11 @@ function validateReport(r) {
   if (r.meta !== undefined && (r.meta === null || typeof r.meta !== 'object' || Array.isArray(r.meta))) {
     problems.push('TestReport.meta must be an object');
   }
+  // contained resources aren't accepted: nothing in a report needs them, and allowing them
+  // would mean describing (and rendering) any resource at all
+  if (r.contained !== undefined) {
+    problems.push('TestReport.contained is not allowed: reports may not contain resources');
+  }
   return problems;
 }
 
@@ -223,6 +229,24 @@ class TestingModule {
       }));
     }
 
+    // RFC 8631: where to find the machine-readable description of this API
+    r.use((req, res, next) => {
+      res.setHeader('Link', `<${req.baseUrl}/openapi.json>; rel="service-desc", <${req.baseUrl}/openapi>; rel="service-doc"`);
+      next();
+    });
+
+    // the OpenAPI description: /openapi.json, /openapi.yaml, and /openapi (an HTML reference
+    // for browsers, the JSON otherwise)
+    r.get('/openapi.json', (req, res) => this.handle(req, res, 'openapi', () => res.type('application/json').send(testingOpenApi.getJson())));
+    r.get('/openapi.yaml', (req, res) => this.handle(req, res, 'openapi', () =>
+      res.set('Content-Type', 'application/yaml').send(testingOpenApi.getYaml())));
+    r.get('/openapi', (req, res) => this.handle(req, res, 'openapi', () => {
+      if (!wantsHtml(req)) {
+        return res.type('application/json').send(testingOpenApi.getJson());
+      }
+      return this.sendHtml(res, 'Test Report API', testingOpenApi.renderHtml(), Date.now());
+    }));
+
     r.get('/', ...this.web, (req, res) => this.handle(req, res, 'list', () => this.htmlList(req, res)));
     r.get('/summary', ...this.web, (req, res) => this.handle(req, res, 'summary', () => this.htmlSummary(req, res)));
     r.get('/metadata', (req, res) => this.handle(req, res, 'metadata', () => this.metadata(req, res)));

package/translations/Messages.properties

@@ -1288,6 +1288,7 @@ VALUESET_INCLUDE_CSVER_NOT_FOUND = No matching contained code system found for s
 VALUESET_INCLUDE_CSVER_SUPPLEMENT = The value set references CodeSystem ''{0}'' version ''{2}'' which is a supplement. It must reference the underlying CodeSystem ''{1}'' and use the http://hl7.org/fhir/StructureDefinition/valueset-supplement extension for the supplement
 VALUESET_INCLUDE_INVALID_CONCEPT_CODE = The code ''{1}'' is not valid in the system {0} ({2})
 VALUESET_INCLUDE_INVALID_CONCEPT_CODE_VER = The code ''{2}'' is not valid in the system {0} version {1} ({2})
+VALUESET_NO_COMPOSE = The value set {0} has no compose and no expansion, so it cannot be expanded
 VALUESET_INCLUDE_SYSTEM_ABSOLUTE = URI values in ValueSet.compose.include.system must be absolute
 VALUESET_INCLUDE_SYSTEM_ABSOLUTE_FRAG = URI values in ValueSet.compose.include.system must be absolute. To reference a contained code system, use the full CodeSystem URL and reference it using the http://hl7.org/fhir/StructureDefinition/valueset-system extension
 VALUESET_INCLUDE_WRONG_CS_OID = It is not valid to refer to a CodeSystem by an identifier like this ''{0}'' - use ''{1}''

package/tx/README.md

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

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