fhirsmith 0.14.1 → 0.14.2

package/tx/openapi.js

@@ -0,0 +1,289 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+// The terminology server's OpenAPI description (R5 endpoints only): openapi.yaml (the
+// overview, /metadata, /$versions, the shared components), plus the paths made here from
+// the operations in openapi-operations.js and the read and search interactions, plus the
+// FHIR resource schemas generated into openapi-schemas.json (see openapi-schemas.config.js).
+
+const path = require('path');
+const { createOpenApiDoc } = require('../library/openapi-doc');
+const { OPERATIONS, COMMON } = require('./openapi-operations');
+
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+const param = (name) => ({ $ref: `#/components/parameters/${name}` });
+
+const RESOURCE_TYPES = ['CodeSystem', 'ValueSet', 'ConceptMap'];
+
+const PRIMITIVES = new Set([
+  'boolean', 'canonical', 'code', 'date', 'dateTime', 'decimal', 'id', 'instant', 'integer',
+  'integer64', 'markdown', 'oid', 'positiveInt', 'string', 'time', 'unsignedInt', 'uri', 'url', 'uuid'
+]);
+
+function isPrimitive(type) {
+  return PRIMITIVES.has(type);
+}
+
+/** The JSON schema of a primitive parameter, as a query parameter. */
+function querySchema(type) {
+  switch (type) {
+    case 'boolean': return { type: 'boolean' };
+    case 'integer': return { type: 'integer' };
+    case 'positiveInt': return { type: 'integer', minimum: 1 };
+    case 'unsignedInt': return { type: 'integer', minimum: 0 };
+    case 'decimal': return { type: 'number' };
+    default: return { type: 'string', 'x-fhir-type': type };
+  }
+}
+
+// a table cell: backslashes escaped first, then the pipes (which would end the cell)
+function cell(s) {
+  return String(s || '').replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+function typeCell(p) {
+  if (p.type === '(parts)') {
+    return 'parts';
+  }
+  return isPrimitive(p.type) ? `\`${p.type}\`` : p.type;
+}
+
+/** A markdown table of parameters. */
+function paramTable(params, inbound) {
+  const rows = [];
+  for (const p of params) {
+    let doc = p.doc || '';
+    if (inbound && !isPrimitive(p.type)) {
+      doc += (doc ? ' ' : '') + '(POST, in a Parameters resource, only)';
+    }
+    rows.push(`| \`${cell(p.name)}\` | ${typeCell(p)} | ${p.min}..${p.max} | ${cell(doc)} |`);
+    for (const part of p.parts || []) {
+      rows.push(`|   \`${cell(p.name)}.${cell(part.name)}\` | ${typeCell(part)} | ${part.min}..${part.max} | ${cell(part.doc)} |`);
+    }
+  }
+  return '| Name | Type | Card. | Description |\n|---|---|---|---|\n' + rows.join('\n');
+}
+
+function camel(s) {
+  return s.replace(/-([a-z])/g, (m, c) => c.toUpperCase());
+}
+
+function errorResponses(extra = {}) {
+  return {
+    '400': { $ref: '#/components/responses/Outcome', description: 'The request is not valid' },
+    '404': { $ref: '#/components/responses/Outcome', description: 'Something the request names was not found' },
+    '422': { $ref: '#/components/responses/Outcome', description: 'The request could not be processed (e.g. the value set is not valid, or the expansion is too large)' },
+    '500': { $ref: '#/components/responses/Outcome', description: 'The server failed' },
+    ...extra
+  };
+}
+
+function okResponse(op) {
+  const schema = ref(op.returns || 'Parameters');
+  return {
+    description: op.returnsDoc || 'The out parameters (see the table)',
+    content: { 'application/fhir+json': { schema }, 'application/json': { schema } }
+  };
+}
+
+/** The paths of one operation: its levels, and its methods. */
+function queryParameter(qp) {
+  const schema = querySchema(qp.type);
+  const result = {
+    name: qp.name,
+    in: 'query',
+    description: qp.doc,
+    schema: qp.max === '*' ? { type: 'array', items: schema } : schema
+  };
+  if (qp.min > 0) {
+    result.required = true;
+  }
+  if (qp.max === '*') {
+    result.style = 'form';
+    result.explode = true;
+  }
+  return result;
+}
+
+function formSchema(params) {
+  const form = { type: 'object', properties: {} };
+  for (const fp of params) {
+    form.properties[fp.name] = fp.max === '*' ? { type: 'array', items: querySchema(fp.type) } : querySchema(fp.type);
+  }
+  return form;
+}
+
+/** The common parameters: in the overview, and as components the operations refer to. */
+function addCommon(spec) {
+  spec.info.description += '\n**Common parameters.** These are read by $expand, $validate-code, ' +
+    '$lookup, $subsumes, $translate and $compare, as well as their own parameters:\n\n' + paramTable(COMMON, true) + '\n';
+  for (const cp of COMMON.filter(x => isPrimitive(x.type))) {
+    spec.components.parameters[`common-${cp.name}`] = queryParameter(cp);
+  }
+}
+
+function addOperation(spec, op) {
+  const methods = op.methods || ['get', 'post'];
+  const queryParams = op.in.filter(p => isPrimitive(p.type));
+  const commonQuery = op.common ? COMMON.filter(x => isPrimitive(x.type)) : [];
+  let description = (op.description || '') + '\n\n**In parameters**' +
+    (op.common ? ' (and the common parameters - see the overview)' : '') + '\n\n' + paramTable(op.in, true);
+  if (op.out) {
+    description += '\n\n**Out parameters** (a Parameters resource)\n\n' + paramTable(op.out, false);
+  }
+  for (const level of op.levels) {
+    const p = level === 'system' ? `/$${op.name}`
+      : level === 'type' ? `/${op.resource}/$${op.name}`
+        : `/${op.resource}/{id}/$${op.name}`;
+    const item = spec.paths[p] = spec.paths[p] || {};
+    const baseId = camel(op.name) + (op.resource || '') + (level === 'instance' ? 'Instance' : '');
+    const common = [param('acceptLanguage'), param('cacheId'), param('format')];
+    if (level === 'instance') {
+      common.unshift(param('id'));
+    }
+    const levelDoc = level === 'instance' ? `\n\nThe ${op.resource} is the one with this id.` : '';
+    for (const method of methods) {
+      const o = {
+        tags: [op.resource || 'Server'],
+        operationId: method === 'get' || methods.length === 1 ? baseId : baseId + 'Post',
+        summary: op.summary,
+        description: description + levelDoc
+      };
+      if (method === 'get') {
+        o.parameters = [...common, ...queryParams.map(queryParameter), ...commonQuery.map(cp => param(`common-${cp.name}`))];
+      } else {
+        // parameters that are in the query even for a POST
+        o.parameters = [...common, ...op.in.filter(x => x.inQuery).map(qp => ({
+          name: qp.name, in: 'query', description: qp.doc, required: qp.min > 0, schema: querySchema(qp.type)
+        }))];
+        const bodies = op.postBody || ['Parameters'];
+        const schema = bodies.length === 1 ? ref(bodies[0]) : { anyOf: bodies.map(ref) };
+        const form = formSchema([...queryParams.filter(x => !x.inQuery), ...commonQuery]);
+        o.requestBody = {
+          required: true,
+          description: bodies.length === 1 ? 'The in parameters, as a Parameters resource (or a form)'
+            : `The in parameters, as a Parameters resource (or a form), or the ${bodies[1]} itself`,
+          content: {
+            'application/fhir+json': { schema },
+            'application/json': { schema },
+            'application/x-www-form-urlencoded': { schema: form }
+          }
+        };
+      }
+      o.responses = { '200': okResponse(op), ...errorResponses(op.responses || {}) };
+      item[method] = o;
+    }
+  }
+}
+
+const SEARCH_DOCS = {
+  url: 'The canonical url (exact)',
+  system: 'The canonical url (exact; the same as url)',
+  version: 'The version (contains)',
+  name: 'The name (contains)',
+  title: 'The title (contains)',
+  status: 'The status (contains)',
+  publisher: 'The publisher (contains)',
+  description: 'The description (contains)',
+  date: 'The date (contains)',
+  identifier: 'An identifier (contains)',
+  jurisdiction: 'A jurisdiction: a code or display (contains)',
+  text: 'The title or description (contains)',
+  'content-mode': 'CodeSystem: the content mode (contains)',
+  supplements: 'CodeSystem: what it supplements (contains)',
+  'source-system': 'ConceptMap: the source code system',
+  'target-system': 'ConceptMap: the target code system',
+  _offset: 'Paging: where to start (0 based)',
+  _count: 'Paging: how many to return (at most 200, or 2000 with _elements)',
+  _elements: 'The elements to return (comma separated)',
+  _sort: 'The element to sort by (default id)',
+  _summary: '`true`, `text`, `data`, `count` or `false`',
+  _total: '`none` to leave out the total (default accurate)'
+};
+
+/** Read, and search (GET, and POST _search), for each resource type. */
+function addReadSearch(spec) {
+  // required here: the search worker requires tx-html, which requires this
+  const SEARCH_PARAMS = require('./workers/search').ALLOWED_PARAMS;
+  for (const type of RESOURCE_TYPES) {
+    const searchParams = SEARCH_PARAMS.filter(n => n !== '_format').map(n => ({
+      name: n,
+      in: 'query',
+      description: SEARCH_DOCS[n] || '',
+      schema: ['_offset', '_count'].includes(n) ? { type: 'integer', minimum: 0 } : { type: 'string' }
+    }));
+    if (type !== 'CodeSystem') {
+      searchParams.push({ name: 'source', in: 'query', description: 'Only those from this source (package)', schema: { type: 'string' } });
+    }
+    const bundle = ref(`${type}SearchBundle`);
+    const searchDoc = `Searches the ${type}s the server has. Text matches are case insensitive and partial ` +
+      '(contains), except url and system; all the parameters given must match.';
+    const searchResponses = {
+      '200': { description: `A searchset Bundle of ${type}s`, content: { 'application/fhir+json': { schema: bundle } } },
+      '500': { $ref: '#/components/responses/Outcome' }
+    };
+    spec.paths[`/${type}`] = {
+      get: {
+        tags: [type], operationId: `search${type}`, summary: `Search ${type}s`, description: searchDoc,
+        parameters: [...searchParams, param('format')], responses: searchResponses
+      }
+    };
+    const form = { type: 'object', properties: {} };
+    searchParams.forEach(sp => {
+      form.properties[sp.name] = sp.schema;
+    });
+    spec.paths[`/${type}/_search`] = {
+      post: {
+        tags: [type], operationId: `search${type}Post`, summary: `Search ${type}s (POST)`,
+        description: searchDoc + ' The parameters are in a form body.',
+        requestBody: { content: { 'application/x-www-form-urlencoded': { schema: form } } },
+        responses: searchResponses
+      }
+    };
+    spec.paths[`/${type}/{id}`] = {
+      get: {
+        tags: [type], operationId: `read${type}`, summary: `Read a ${type}`,
+        parameters: [param('id'), param('format')],
+        responses: {
+          '200': { description: `The ${type}`, content: { 'application/fhir+json': { schema: ref(type) } } },
+          '404': { $ref: '#/components/responses/Outcome', description: 'There is no such resource' }
+        }
+      }
+    };
+  }
+}
+
+function build(spec) {
+  addCommon(spec);
+  addReadSearch(spec);
+  for (const op of OPERATIONS) {
+    addOperation(spec, op);
+  }
+}
+
+const SPEC_PATH = path.join(__dirname, 'openapi.yaml');
+const SCHEMAS_PATH = path.join(__dirname, 'openapi-schemas.json');
+
+const docs = new Map();
+
+/**
+ * The description, for an R5 endpoint (its servers url is the endpoint)
+ * @param {string} endpointPath - e.g. /tx/r5
+ */
+function forEndpoint(endpointPath) {
+  if (!docs.has(endpointPath)) {
+    docs.set(endpointPath, createOpenApiDoc(SPEC_PATH, endpointPath,
+      { schemasPath: SCHEMAS_PATH, build, serverUrl: endpointPath }));
+  }
+  return docs.get(endpointPath);
+}
+
+/** Whether an endpoint's FHIR version is the one described (R5) */
+function describes(fhirVersion) {
+  return String(fhirVersion).startsWith('5');
+}
+
+module.exports = { forEndpoint, describes, isPrimitive, RESOURCE_TYPES, SEARCH_DOCS };

package/tx/openapi.yaml

@@ -0,0 +1,151 @@
+# OpenAPI description of the FHIRsmith terminology server (an R5 endpoint, e.g. /tx/r5).
+#
+# Three parts, merged when the spec is served (see openapi.js):
+#  - this file: the overview, /metadata and /$versions, and the shared components
+#  - openapi-operations.js: the terminology operations, as data. openapi.js makes their
+#    paths (type and instance level, GET and POST) and their parameter tables, and the
+#    read and search paths
+#  - openapi-schemas.json: the FHIR R5 resource schemas, generated from the
+#    StructureDefinitions by utilities/generate-openapi-schemas.js (see
+#    openapi-schemas.config.js)
+#
+# tests/tx/openapi.test.js keeps this honest: every route must be described or explicitly
+# excluded, the parameters must be the ones the code reads, and real responses must
+# validate against the schemas.
+#
+# HTML pages (/, /op.html, /ecl, /problems.html, /info, /library) are not described.
+# info.version is filled in from package.json, and servers from the endpoint, when the spec
+# is served.
+
+openapi: 3.1.0
+info:
+  title: FHIRsmith Terminology Server
+  version: "0.0.0"
+  summary: A FHIR terminology server (R5)
+  description: |
+    A FHIR terminology server: code systems, value sets and concept maps, and the
+    terminology operations on them - $expand, $validate-code, $lookup, $subsumes,
+    $translate, and more. This describes an R5 endpoint; the server's R4 and R3 endpoints
+    work the same way, with the resources of that version.
+
+    The operations are the ones FHIR defines (see the [terminology
+    service](https://hl7.org/fhir/R5/terminology-service.html)), with the behaviour the
+    [terminology ecosystem IG](https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig/) asks of
+    the servers in the ecosystem. Each operation lists the parameters this server reads.
+
+    **Requests.** An operation can be invoked with GET, with its parameters in the query, or
+    with POST, with a Parameters resource (`application/fhir+json`), or a form. Parameters
+    whose values are not primitives (a Coding, a resource) can only be sent in a Parameters
+    resource.
+
+    **Responses** are JSON by default; `application/fhir+xml` (or `_format=xml`) gets XML,
+    and a browser (or `_format=html`) gets an HTML page. Only the JSON is described here.
+    Errors are OperationOutcomes, and every issue (except information) has a tx-issue-type
+    code in `details.coding` and its message in `details.text`.
+
+    **Schemas.** The resource schemas describe what this server handles and returns: it
+    doesn't reject content outside them (an extension with a Quantity value, say), but it
+    isn't designed to do anything with it. They have the JSON `_x` elements (the id and
+    extensions of a primitive) and modifierExtension wherever FHIR allows them. Contained
+    resources are value sets, in a value set, only.
+
+    **Caching.** A client that sends the same resources (`tx-resource`) with many requests
+    can keep them on the server with `$cache-control`, and then send the cache's id in the
+    `X-Cache-Id` header.
+  license:
+    name: BSD-3-Clause
+    url: https://opensource.org/license/bsd-3-clause
+externalDocs:
+  description: The FHIR R5 terminology service
+  url: https://hl7.org/fhir/R5/terminology-service.html
+servers:
+  - url: /tx/r5
+
+tags:
+  - name: Server
+    description: What the server does, and operations on the server as a whole
+  - name: CodeSystem
+    description: Code systems, and $lookup, $validate-code and $subsumes
+  - name: ValueSet
+    description: Value sets, and $expand, $validate-code and $compare
+  - name: ConceptMap
+    description: Concept maps, and $translate
+
+paths:
+  /metadata:
+    get:
+      tags: [Server]
+      operationId: metadata
+      summary: The server's capabilities
+      description: |
+        The CapabilityStatement, or with `mode=terminology`, the TerminologyCapabilities:
+        the code systems (and versions) the server has, and the expansion parameters it
+        understands.
+      parameters:
+        - name: mode
+          in: query
+          description: '`terminology` for the TerminologyCapabilities'
+          schema: { type: string, enum: [terminology] }
+        - $ref: '#/components/parameters/format'
+      responses:
+        '200':
+          description: The CapabilityStatement, or the TerminologyCapabilities
+          content:
+            application/fhir+json:
+              schema:
+                anyOf:
+                  - $ref: '#/components/schemas/CapabilityStatement'
+                  - $ref: '#/components/schemas/TerminologyCapabilities'
+
+  /$versions:
+    get:
+      tags: [Server]
+      operationId: versions
+      summary: The FHIR versions of this endpoint
+      description: |
+        The FHIR version this endpoint uses. With `Accept: application/fhir+json` the answer
+        is a Parameters resource (`version` and `default`); otherwise, a simple JSON object.
+      responses:
+        '200':
+          description: The versions
+          content:
+            application/fhir+json:
+              schema: { $ref: '#/components/schemas/Parameters' }
+            application/json:
+              schema:
+                type: object
+                properties:
+                  versions: { type: array, items: { type: string }, example: ['5.0'] }
+                  default: { type: string, example: '5.0' }
+                required: [versions, default]
+
+components:
+  parameters:
+    id:
+      name: id
+      in: path
+      required: true
+      description: The resource's id
+      schema: { type: string }
+    format:
+      name: _format
+      in: query
+      description: '`json`, `xml` or `html`, instead of the Accept header'
+      schema: { type: string, enum: [json, xml, html] }
+    acceptLanguage:
+      name: Accept-Language
+      in: header
+      description: The language(s) for displays and messages
+      schema: { type: string }
+      example: en
+    cacheId:
+      name: X-Cache-Id
+      in: header
+      description: A cache of resources, started with $cache-control
+      schema: { type: string }
+  responses:
+    Outcome:
+      description: An error, as an OperationOutcome
+      content:
+        application/fhir+json:
+          schema: { $ref: '#/components/schemas/OperationOutcome' }

package/tx/operation-context.js

@@ -1084,6 +1084,21 @@ class OperationContext {
     this.contexts.push(vurl);
   }
 
+  /**
+   * Stop tracking a context, once processing of that value set is finished. The tracked
+   * contexts are the chain of value sets currently being processed, not every value set
+   * seen in the operation: a value set used twice (imported by two others, or twice by
+   * one) is not a circularity - only one that is reached again while it's being
+   * processed is.
+   * @param {string} vurl - the url passed to seeContext
+   */
+  unseeContext(vurl) {
+    const i = this.contexts.lastIndexOf(vurl);
+    if (i >= 0) {
+      this.contexts.splice(i, 1);
+    }
+  }
+
   /**
    * Clear all tracked contexts
    */

package/tx/params.js

@@ -372,11 +372,6 @@ class TxParameters {
         if (claim('no-cache') && asBool()) this.FUid = crypto.randomUUID();
         break;
       }
-      case '_incomplete':
-      case 'limitedExpansion': {
-        if (claim('limitedExpansion')) this.limitedExpansion = asBool();
-        break;
-      }
       case 'includeDesignations': {
         if (claim('includeDesignations')) this.includeDesignations = asBool();
         break;
@@ -405,10 +400,6 @@ class TxParameters {
         if (claim('default-to-latest-version')) this.defaultToLatestVersion = asBool();
         break;
       }
-      case 'incomplete-ok': {
-        if (claim('incomplete-ok')) this.incompleteOK = asBool();
-        break;
-      }
       case 'diagnostics': {
         if (claim('diagnostics')) this.diagnostics = asBool();
         break;
@@ -629,11 +620,11 @@ class TxParameters {
       s = s + '$' + [...this.supplements].sort().join(',') + '|';
     }
     // Further result-affecting parameters that were previously omitted from the
-    // key: the text filter (changes which codes expand), limited/incomplete
-    // expansion handling, whether abstract codes are included, and diagnostics.
+    // key: the text filter (changes which codes expand), whether abstract codes
+    // are included, and diagnostics.
     // filter is free text, so JSON.stringify it to avoid delimiter collisions.
     s = s + 'f:' + JSON.stringify(this.filter || '') + '|' +
-      b(this.limitedExpansion) + b(this.incompleteOK) + b(this.abstractOk) + b(this.diagnostics);
+      b(this.abstractOk) + b(this.diagnostics);
     for (let t of this.FVersionRules) {
       s = s + t.asString() + '|';
     }

package/tx/provider.js

@@ -172,7 +172,16 @@ class Provider {
 
     const resources = await contentLoader.getResourcesByType("CodeSystem");
     for (const resource of resources) {
-      const cs = new CodeSystem(await contentLoader.loadFile(resource, contentLoader.fhirVersion()));
+      let cs;
+      try {
+        cs = new CodeSystem(await contentLoader.loadFile(resource, contentLoader.fhirVersion()));
+      } catch (e) {
+        // one unacceptable resource (e.g. contained resources the server doesn't support)
+        // must not stop the rest of the package loading
+        require('../library/logger').getInstance().child({ module: 'tx' })
+          .warn(`Package ${contentLoader.pid()}: skipping CodeSystem ${resource.id || resource.filename || ''}: ${e.message}`);
+        continue;
+      }
       cs.sourcePackage = contentLoader.pid();
       this.addCodeSystem(cs);
     }

package/tx/tx-html.js

@@ -21,6 +21,7 @@ const {OperationOutcomeXML} = require("./xml/operationoutcome-xml");
 const {debugLog} = require("./operation-context");
 const {InvalidError} = require("./library/errors");
 const {VALID_FILTER_OPS} = require("./library/renderer");
+const txOpenApi = require("./openapi");
 
 const txHtmlLog = Logger.getInstance().child({ module: 'tx-html' });
 
@@ -262,6 +263,11 @@ class TxHtmlRenderer {
         ? '<a href="' + escape(endpoint.path) + '/library" style="color: gold">Library</a>  &nbsp;|&nbsp;'
         : ''
     };
+    // the OpenAPI description, on the endpoints it describes (R5)
+    if (txOpenApi.describes(endpoint.fhirVersion)) {
+      options.apiLink = '<a href="' + escape(endpoint.path) + '/openapi" style="color: gold">API</a>  &nbsp;|&nbsp;';
+      options.apiHead = '<link rel="service-desc" type="application/json" href="' + escape(endpoint.path) + '/openapi.json"/>';
+    }
 
     return htmlServer.renderPage('tx', title, content, options);
   }

package/tx/tx.js

@@ -54,6 +54,7 @@ const {BundleXML} = require("./xml/bundle-xml");
 const ConceptUsageTracker = require("./usage-tracker");
 const ProblemFinder = require("./problems");
 const { buildOperationOutcome, outcomeFromError } = require('./library/operation-outcome');
+const txOpenApi = require('./openapi');
 // const {writeFileSync} = require("fs");
 
 class TXModule {
@@ -521,6 +522,11 @@ class TXModule {
 
     app.use(express.urlencoded({ extended: true }));
 
+    // The OpenAPI description, on the endpoints it describes (R5)
+    if (txOpenApi.describes(fhirVersion)) {
+      this.setupOpenApi(router, endpointInfo);
+    }
+
     // Set up routes
     this.setupRoutes(router, endpointInfo.path);
 
@@ -540,6 +546,55 @@ class TXModule {
     this.log.info(`Endpoint ${endpointPath} registered`);
   }
 
+  /**
+   * The OpenAPI description of an endpoint: /openapi.json, /openapi.yaml, and /openapi (an
+   * HTML reference for browsers, the JSON otherwise), and an RFC 8631 Link header on every
+   * response that points to them. These are sent directly, not through the res.json the
+   * endpoint wraps for FHIR resources.
+   *
+   * @param {express.Router} router
+   * @param {Object} endpointInfo
+   */
+  setupOpenApi(router, endpointInfo) {
+    const doc = txOpenApi.forEndpoint(endpointInfo.path);
+    const sendJson = (res) => res.type('application/json').send(doc.getJson());
+    router.use((req, res, next) => {
+      res.setHeader('Link', `<${req.baseUrl}/openapi.json>; rel="service-desc", <${req.baseUrl}/openapi>; rel="service-doc"`);
+      next();
+    });
+    const count = (start) => this.countRequest(endpointInfo.path, 'openapi', Date.now() - start);
+    router.get('/openapi.json', (req, res) => {
+      const start = Date.now();
+      try {
+        sendJson(res);
+      } finally {
+        count(start);
+      }
+    });
+    router.get('/openapi.yaml', (req, res) => {
+      const start = Date.now();
+      try {
+        res.type('application/yaml').send(doc.getYaml());
+      } finally {
+        count(start);
+      }
+    });
+    router.get('/openapi', async (req, res) => {
+      const start = Date.now();
+      try {
+        if (!txHtml.acceptsHtml(req)) {
+          return sendJson(res);
+        }
+        const txhtml = new TxHtmlRenderer(new Renderer(req.txOpContext, req.txProvider), this.liquid, this.languages, this.i18n, endpointInfo.path);
+        const html = await txhtml.renderPage('API', doc.renderHtml(), endpointInfo, req.txStartTime);
+        res.setHeader('Content-Type', 'text/html');
+        res.send(html);
+      } finally {
+        count(start);
+      }
+    });
+  }
+
   /**
    * Set up routes for an endpoint
    * @param {express.Router} router - Express router

package/tx/vs/vs-database.js

@@ -743,7 +743,17 @@ class ValueSetDatabase {
           const valueSetMap = new Map();
 
           for (const row of rows) {
-            const valueSet = new ValueSet(JSON.parse(row.content));
+            let valueSet;
+            try {
+              valueSet = new ValueSet(JSON.parse(row.content));
+            } catch (e) {
+              // one unacceptable value set (e.g. one containing a CodeSystem, which the
+              // server doesn't support) must not take the whole package's value sets with it
+              require('../../library/logger').getInstance().child({ module: 'tx' })
+                .warn(`${source || 'ValueSet database'}: skipping ValueSet ${row.url || row.id}${row.version ? '|' + row.version : ''}: ${e.message}`);
+              this.vsCount--;
+              continue;
+            }
             valueSet.sourcePackage = source;
             // Attach the stored content hash so callers can detect changes
             // without recomputing over the full JSON.
@@ -839,10 +849,9 @@ class ValueSetDatabase {
             });
           } else {
             // Fall back to parsing JSON
-            results = rows.map(row => {
-              const vs = map.get(row.id);
-              return vs;
-            });
+            // a value set the map doesn't have was rejected when the map was loaded
+            // (see loadAllValueSets), so it isn't a result
+            results = rows.map(row => map.get(row.id)).filter(vs => vs);
           }
 
           resolve(results);

package/tx/vs/vs-package.js

@@ -3,6 +3,7 @@ const fs = require('fs').promises;
 const { AbstractValueSetProvider } = require('./vs-api');
 const { PackageContentLoader } = require('../../library/package-manager');
 const { ValueSetDatabase } = require('./vs-database');
+const { checkContained } = require('../library/canonical-resource');
 const { VersionUtilities } = require('../../library/version-utilities');
 const {validateParameter} = require("../../library/utilities");
 
@@ -126,6 +127,15 @@ class PackageValueSetProvider extends AbstractValueSetProvider {
     for (const entry of valueSetEntries) {
       const valueSet = await this.packageLoader.loadFile(entry);
       if (valueSet.url) {
+        try {
+          // don't store a value set the server can't use (e.g. one that contains a
+          // CodeSystem): it would be listed by search, and fail when read
+          checkContained(valueSet);
+        } catch (e) {
+          require('../../library/logger').getInstance().child({ module: 'tx' })
+            .warn(`Package ${this.packageLoader.pid ? this.packageLoader.pid() : ''}: skipping ValueSet ${valueSet.url}: ${e.message}`);
+          continue;
+        }
         valueSets.push(valueSet);
       }
     }