fhirsmith 0.18.0 → 0.18.2

package/library/daily-report.js

@@ -85,6 +85,15 @@ function formatSpan(ms) {
   return parts.join(' ');
 }
 
+/** "24 hours", "3 days" - for the report title; rounded, since it's a description of the period */
+function describeSpan(ms) {
+  const hours = Math.round(ms / 3600000);
+  if (hours < 48) {
+    return plural(Math.max(1, hours), 'hour');
+  }
+  return plural(Math.round(hours / 24), 'day');
+}
+
 function plural(n, word) {
   return `${n} ${word}${n === 1 ? '' : 's'}`;
 }
@@ -243,8 +252,7 @@ class DailyReport {
    */
   async build(since, now = Date.now()) {
     const parts = [];
-    parts.push(`# ${this.serverId} daily report`);
-    parts.push(`${localDateTime(now)}, covering the ${formatSpan(now - since)} since ${localDateTime(since)}.`);
+    parts.push(`# ${this.serverId} daily report for ${localDateTime(now)} covering the last ${describeSpan(now - since)}`);
     parts.push('## Stability');
     parts.push(this.stabilityParagraph(since, now));
     for (const [name, module] of Object.entries(this.modules)) {
@@ -347,25 +355,26 @@ class DailyReport {
    * the disk they're on.
    */
   systemParagraph(now) {
-    const sentences = [];
-    sentences.push(`${this.serverId} is running FHIRsmith v${this.version} on Node.js ${process.version} (${os.type()} ${os.release()}, ${os.arch()}).`);
+    // one line each; the two trailing spaces are markdown's line break
+    const lines = [];
+    lines.push(`Versions: FHIRsmith = v${this.version}. Node = ${process.version} (${os.type()} ${os.release()}, ${os.arch()})`);
     if (this.stats && typeof this.stats.startTime === 'number') {
-      let up = `This run has been up for ${formatSpan(now - this.stats.startTime)}, since ${localDateTime(this.stats.startTime)}`;
+      let up = `Uptime: This run = ${formatSpan(now - this.stats.startTime)}`;
       const overall = typeof this.stats.overallUptime === 'function' ? this.stats.overallUptime(now) : null;
       if (overall) {
         const pct = overall.percent >= 100 ? '100' : (Math.floor(overall.percent * 10) / 10).toFixed(1);
-        up += `; over all its recorded runs (since ${localDate(overall.since)}) the server has been up ${pct}% of the time`;
+        up += `. All runs, ${pct}%`;
       }
-      sentences.push(up + '.');
+      lines.push(up);
     }
-    sentences.push(this.logsSentence());
+    lines.push(`Space: ${this.logsText()}`);
     if (this.npmAudit && typeof this.npmAudit.reportText === 'function') {
       const audit = this.npmAudit.reportText();
       if (audit) {
-        sentences.push(audit);
+        lines.push(`Audit: ${audit}`);
       }
     }
-    return sentences.join(' ');
+    return lines.join('  \n');
   }
 
   /**
@@ -388,7 +397,7 @@ class DailyReport {
     return `${plural(failed.length, 'background task')} ${failed.length === 1 ? 'is' : 'are'} in a failed state:\n\n${lines.join('\n')}`;
   }
 
-  logsSentence() {
+  logsText() {
     const logDir = folders.logsDir();
     try {
       const files = fs.readdirSync(logDir).filter(f => f.endsWith('.log'));
@@ -402,13 +411,13 @@ class DailyReport {
         const free = fstats.bavail * fstats.bsize;
         const size = fstats.blocks * fstats.bsize;
         const freePct = size > 0 ? Math.round((free * 100) / size) : 0;
-        disk = `, on a disk with ${formatBytes(free)} free of ${formatBytes(size)} (${freePct}% free)`;
+        disk = ` on a disk with ${formatBytes(free)} free of ${formatBytes(size)} (${freePct}% free)`;
       } catch {
-        disk = ', on a disk whose free space could not be read';
+        disk = ' on a disk whose free space could not be read';
       }
-      return `The logs folder (${logDir}) holds ${plural(files.length, 'log file')} totalling ${formatBytes(total)}${disk}.`;
+      return `${plural(files.length, 'log file')} totalling ${formatBytes(total)}${disk}.`;
     } catch (e) {
-      return `The logs folder (${logDir}) could not be read: ${e.message}.`;
+      return `the logs folder (${logDir}) could not be read: ${e.message}.`;
     }
   }
 }
@@ -417,6 +426,7 @@ module.exports = DailyReport;
 module.exports.nextMidnight = nextMidnight;
 module.exports.localDate = localDate;
 module.exports.formatSpan = formatSpan;
+module.exports.describeSpan = describeSpan;
 // for modules writing their paragraph: "3 packages", "1 package"
 module.exports.plural = plural;
 module.exports.localDateTime = localDateTime;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fhirsmith",
-  "version": "0.18.0",
-  "txVersion": "1.9.6",
+  "version": "0.18.2",
+  "txVersion": "1.10.1",
   "description": "A Node.js server that provides a collection of tools to serve the FHIR ecosystem",
   "main": "server.js",
   "engines": {
@@ -48,7 +48,7 @@
     "express-rate-limit": "^7.4.1",
     "express-session": "^1.19.0",
     "fast-xml-parser": "^5.3.4",
-    "fhir-validator-wrapper": "1.5.0",
+    "fhir-validator-wrapper": "1.6.1",
     "fhirpath": "^5.2.1",
     "fs-extra": "^11.3.3",
     "ini": "^6.0.0",

package/registry/api.js

@@ -27,6 +27,20 @@ function securityFlags(security) {
   }
 }
 
+// Code systems that tx.fhir.org handles specially. When the registry doesn't settle where
+// a request involving one of these goes, it goes to the primary server (see chooseServer)
+const SNOMED_CT = 'http://snomed.info/sct';
+const PRIMARY_SERVER_SYSTEMS = ['http://unitsofmeasure.org', 'http://loinc.org', SNOMED_CT,
+  'http://www.nlm.nih.gov/research/umls/rxnorm', 'http://hl7.org/fhir/sid/cvx', 'urn:ietf:bcp:13', 'urn:ietf:bcp:47',
+  'urn:ietf:rfc:3986', 'http://www.ama-assn.org/go/cpt', 'urn:oid:1.2.36.1.2001.1005.17', 'urn:iso:std:iso:3166',
+  'http://varnomen.hgvs.org', 'http://unstats.un.org/unsd/methods/m49/m49.htm', 'urn:iso:std:iso:4217',
+  'http://hl7.org/fhir/sid/ndc', 'http://fhir.ohdsi.org/CodeSystem/concepts', 'http://fdasis.nlm.nih.gov', 'https://www.usps.com/'];
+
+function isTxFhirOrg(server) {
+  const s = server.replace('http://', 'https://');
+  return s.startsWith('https://tx.fhir.org/') || s.startsWith('https://tx-dev.fhir.org/');
+}
+
 class RegistryAPI {
   constructor(crawler) {
     this.crawler = crawler;
@@ -592,6 +606,170 @@ class RegistryAPI {
     };
   }
 
+  /**
+   * Choose one server for a request that involves a set of code systems.
+   *
+   * This is a server side copy of the routing logic in the HL7 Java tooling
+   * (TerminologyClientManager.chooseServer in org.hl7.fhir.core), for clients that aren't
+   * Java. It doesn't replace that code. The Java client does the work that needs its own
+   * context before routing, and so must the caller here:
+   *
+   * - systems: the code systems involved, as url or url|version, from the codings and the
+   *   value set's includes and excludes, following imported value sets. Versions fixed by
+   *   expansion parameters (system-version, force-system-version) should already be applied.
+   *   If the caller couldn't follow an import, it should just use its default server.
+   * - language: only for language sensitive requests (see resolveCodeSystem).
+   *
+   * Differences from the Java code:
+   * - 'Does a candidate really have the code system' is answered from the content mode the
+   *   server reported in its TerminologyCapabilities, not by searching the server. If it
+   *   didn't report one, the candidate is assumed to be usable.
+   * - The 'primary server' for the systems tx.fhir.org handles specially is the default.
+   * - The value set's source server is found by resolving the value set here.
+   * - Ties are broken by order (the first system, then registration order), not hash order.
+   *
+   * @returns {{server: string, log: string[]}} the server to use, and why
+   */
+  chooseServer(fhirVersion, systems, defaultServer, valueSet = '', usage = '', language = '') {
+    if (!fhirVersion) {
+      throw new Error('A FHIR version is required');
+    }
+    if (!defaultServer) {
+      throw new Error('A default server is required');
+    }
+    const log = [];
+    const list = [...new Set((systems || []).filter(s => s))];
+    if (valueSet) {
+      log.push(`Value set: ${valueSet}`);
+    }
+    if (list.length === 0) {
+      log.push('No code systems: using the default server');
+      return { server: defaultServer, log };
+    }
+    const server = this._chooseServer(fhirVersion, list, defaultServer, valueSet, usage, language, log);
+    return { server, log };
+  }
+
+  _chooseServer(fhirVersion, systems, defaultServer, valueSet, usage, language, log) {
+    // what the registry says about each system on its own
+    const choices = systems.map(system => {
+      const r = this.resolveCodeSystem(fhirVersion, system, false, usage, language).result;
+      const choice = { system, authoritative: [], candidates: [], content: {} };
+      for (const e of r.authoritative || []) {
+        if (!choice.authoritative.includes(e.url)) choice.authoritative.push(e.url);
+      }
+      for (const e of r.candidates || []) {
+        if (!choice.candidates.includes(e.url)) {
+          choice.candidates.push(e.url);
+          choice.content[e.url] = e.content;
+        }
+      }
+      log.push(`${system}: authoritative [${choice.authoritative.join(', ')}], candidates [${choice.candidates.join(', ')}]`);
+      return choice;
+    });
+    // the registry knows no server at all for the system
+    const unresolved = c => c.authoritative.length === 0 && c.candidates.length === 0;
+
+    // 1. a server that's authoritative for all of them
+    for (const c of choices) {
+      for (const s of c.authoritative) {
+        if (choices.every(t => t.authoritative.includes(s))) {
+          log.push(`Found authoritative server ${s}`);
+          return s;
+        }
+      }
+    }
+
+    // 2. a server that's authoritative for one of them, and a candidate for the others. A
+    // system that no server is known for doesn't constrain the choice
+    for (const c of choices) {
+      for (const s of c.authoritative) {
+        if (choices.every(t => unresolved(t) || t.authoritative.includes(s) || t.candidates.includes(s))) {
+          log.push(`Found partially authoritative server ${s}`);
+          return s;
+        }
+      }
+    }
+
+    // 3. code systems with special handling on tx.fhir.org, that might not be resolved above.
+    // We don't want them going to secondary servers by accident
+    const bases = systems.map(s => s.includes('|') ? s.substring(0, s.indexOf('|')) : s);
+    if (systems.length > 1 && bases.includes(SNOMED_CT)) {
+      log.push(`Several code systems including SNOMED CT: choosing for SNOMED CT alone`);
+      return this._chooseServer(fhirVersion, [SNOMED_CT], defaultServer, valueSet, usage, language, log);
+    }
+    const special = bases.find(b => PRIMARY_SERVER_SYSTEMS.includes(b));
+    if (special) {
+      log.push(`Use primary server (the default) for ${special}`);
+      return defaultServer;
+    }
+
+    // 4. a server that's a candidate for all of them (again, systems no server is known for
+    // don't constrain the choice), and that has a usable copy of the code systems
+    for (const c of choices) {
+      for (const s of c.candidates) {
+        if (choices.every(t => unresolved(t) || t.candidates.includes(s)) &&
+          this._supportsAll(s, choices, unresolved, log)) {
+          log.push(`Found candidate server ${s}`);
+          return s;
+        }
+      }
+    }
+
+    // 5. no agreement - take the one that is most authoritative
+    const counts = new Map();
+    for (const c of choices) {
+      for (const s of c.authoritative) {
+        counts.set(s, (counts.get(s) || 0) + 1);
+      }
+    }
+    let max = null;
+    for (const [s, n] of counts) {
+      if (max === null || n > counts.get(max)) max = s;
+    }
+    if (max !== null) {
+      log.push(`Found most authoritative server ${max}`);
+      return max;
+    }
+
+    // 6. nothing. Use the server the value set comes from, if it comes from one, else the default
+    const why = systems.length === 1 ? 'Not handled by any servers' : 'Handled by multiple servers';
+    if (valueSet) {
+      const r = this.resolveValueSet(fhirVersion, valueSet, false, usage).result;
+      let source = (r.authoritative || []).concat(r.candidates || []).map(e => e.url)[0];
+      if (source === 'https://vsac.nlm.nih.gov') {
+        source = defaultServer;
+      }
+      if (source) {
+        log.push(`${why}. Using source @ '${source}'`);
+        return source;
+      }
+    }
+    log.push(`${why}. Using the default server`);
+    return defaultServer;
+  }
+
+  /**
+   * Whether a candidate server has a usable copy (complete or fragment) of each code system
+   * it's a candidate for. Systems for which tx.fhir.org is a candidate aren't checked
+   */
+  _supportsAll(server, choices, unresolved, log) {
+    if (isTxFhirOrg(server)) {
+      return true;
+    }
+    for (const t of choices) {
+      if (unresolved(t) || !t.candidates.includes(server) || t.candidates.some(isTxFhirOrg)) {
+        continue;
+      }
+      const content = t.content[server];
+      if (content && content !== 'complete' && content !== 'fragment') {
+        log.push(`Candidate server ${server} dropped for ${t.system}: its copy of the code system is '${content}'`);
+        return false;
+      }
+    }
+    return true;
+  }
+
   /**
    * The ecosystem Discovery API (GET {root} as JSON): one row per server endpoint.
    *
@@ -774,7 +952,7 @@ class RegistryAPI {
       }
       html += '</td>\n';
 
-      html += `<td>${row.security}/td>\n`;
+      html += `<td>${escape(row.security)}</td>\n`;
 
       html += '</tr>\n';
     }

package/registry/crawler.js

@@ -160,6 +160,8 @@ class RegistryCrawler {
       }
       
       newData.doco = masterJson.documentation || '';
+      newData.registration = masterJson.registration || '';
+      newData.ecosystemDoco = masterJson['ecosystem-documentation'] || '';
       
       // Process each registry
       const registries = masterJson.registries || [];

package/registry/documentation/api.md

@@ -15,12 +15,13 @@ contract:
 Every response carries `Link: </tx-reg/openapi.json>; rel="service-desc"` (RFC 8631), and the
 HTML pages the matching `<link>` element.
 
-There are two operations, both `GET`:
+There are two operations from the ecosystem IG, and one extension, all `GET`:
 
 | Endpoint | |
 |---|---|
 | `/tx-reg/` | **Discovery** - the server endpoints in the ecosystem |
 | `/tx-reg/resolve` | **Resolution** - which endpoints to use for a code system or value set |
+| `/tx-reg/choose-server` | **Server choice** - which one server to use for a request involving several code systems (JSON only; [below](#server-choice-get-tx-regchoose-server)) |
 
 Both answer JSON, or an HTML page when the request's `Accept` header contains `text/html`.
 `/tx-reg/resolve` in a browser without parameters is a form for trying it. Parameters are read
@@ -143,7 +144,72 @@ when empty, so an empty object means nobody hosts it.
 * Resolve takes `version` as an alternative to `url|version`.
 * Resolve omits `authoritative` and `candidates` when they are empty.
 
-## Operational pages
+## Server choice: `GET /tx-reg/choose-server`
+
+Not in the ecosystem IG. A request often involves several code systems - a value set that
+includes LOINC and a national code system, a CodeableConcept with codings from three - and
+resolution answers for one at a time. The HL7 Java tooling combines the answers into a choice
+of one server (`TerminologyClientManager.chooseServer` in org.hl7.fhir.core); this makes the
+same choice here for clients that aren't Java. It doesn't replace the Java code, which still
+does its own choosing.
+
+| Parameter | |
+|---|---|
+| `fhirVersion` | Required, as for resolve |
+| `system` | A code system the request involves, `url` or `url\|version`. Repeat it for each (`system=a&system=b`) - the one parameter that isn't first-value-only |
+| `default` | Required. The client's default terminology server: the fallback, and the server for the code systems tx.fhir.org handles specially |
+| `valueSet` | The value set the request is about, `url` or `url\|version`, if there is one |
+| `language` | As for resolve, but only for language sensitive requests (an expansion where the display language matters, a validation that checks a display, a lookup that returns designations) |
+| `usage` | As for resolve |
+
+```json
+{
+  "server": "https://tx.ontoserver.csiro.au/fhir",
+  "log": [
+    "https://healthterminologies.gov.au/fhir/CodeSystem/x: authoritative [https://tx.ontoserver.csiro.au/fhir], candidates []",
+    "http://terminology.hl7.org/CodeSystem/v2-0203: authoritative [http://tx.fhir.org/r4], candidates [https://tx.ontoserver.csiro.au/fhir]",
+    "Found partially authoritative server https://tx.ontoserver.csiro.au/fhir"
+  ]
+}
+```
+
+`log` is for people: what resolution says about each code system, then the rule that decided.
+
+### What the client does first
+
+What the Java tooling works out before it chooses, a client must too:
+
+* The code systems: from the codings, and from the value set's includes and excludes,
+  following imported value sets. The imports are often only in the client's own context (the
+  IG being built), so the registry can't follow them. If the client can't follow one, it
+  should use its default server without asking.
+* Versions: those fixed by the expansion parameters (`system-version`,
+  `force-system-version`) applied to the systems.
+* Language: for an expansion, the `displayLanguage` of the expansion parameters if no other.
+
+### How the choice is made
+
+In order:
+
+1. A server authoritative for all the code systems.
+2. A server authoritative for one, and authoritative or a candidate for each of the others.
+3. Several code systems including SNOMED CT: the choice for SNOMED CT alone. Otherwise, if a
+   code system is one tx.fhir.org handles specially (LOINC, UCUM, RxNorm, CVX, NDC, CPT,
+   BCP-13/47, ISO 3166/4217 ...): the default.
+4. A server that is a candidate for all of them, and has a usable copy of each - its
+   TerminologyCapabilities says `complete` or `fragment`, or gives no content mode. Not
+   checked for a code system tx.fhir.org is also a candidate for.
+5. The server authoritative for the most of them (the first, on a tie).
+6. The server the value set comes from (by resolving `valueSet`), else the default.
+
+In 2 and 4, a code system that no server hosts doesn't count against a server.
+
+Where this differs from the Java tooling: step 4 uses the content mode the registry scanned
+instead of searching the server, and trusts a server that didn't say; the special handling in
+step 3 sends to `default` rather than to whichever of tx.fhir.org / tx-dev the client has used;
+ties go to the first rather than to hash order. Step 3 is tx.fhir.org specific, and applies to
+any ecosystem for now.
+
 
 These are HTML, not part of the API, and never secured:
 

package/registry/documentation/internals.md

@@ -28,7 +28,10 @@ How the module works, for anyone changing it. The user-facing behaviour is in
 `RegistryCrawler.crawl()` runs every `crawlInterval` minutes (first 5 seconds after start),
 and never concurrently with itself. A scan builds a fresh `ServerRegistries` from scratch:
 
-1. fetch the master registration file (`formatVersion` must be `"1"`);
+1. fetch the master registration file (`formatVersion` must be `"1"`); its optional
+   `registration` and `ecosystem-documentation` URLs are the "Register your own server" and
+   "Documentation" links on the home page (each is omitted if the file doesn't give it), since
+   they depend on the ecosystem;
 2. for each registry it lists, fetch the registry file and build a `ServerRegistry`;
 3. for each server, a `ServerInformation` with its claims (`authoritative`,
    `authoritative-valuesets`, `languages`, `usage`, `exclusions`), and for each of its

package/registry/documentation/readme.md

@@ -27,8 +27,9 @@ it, [api.md](api.md) says so.
 
 **The registration files.** The ecosystem is declared by a *master registration file* that
 lists *registries*, each of which lists *servers*, each of which lists its endpoints (one per
-FHIR version) and its claims. The format is documented in the ig-registry repository's
-[tx-registry-doco.md](https://github.com/FHIR/ig-registry/blob/master/tx-registry-doco.md).
+FHIR version) and its claims. The format is documented on the IG's ecosystem page; HL7's own
+ecosystem (its locations, and how to register a server in it) is documented in the ig-registry
+repository's [tx-registry-doco.md](https://github.com/FHIR/ig-registry/blob/master/tx-registry-doco.md).
 HL7's master file is https://fhir.github.io/ig-registry/tx-servers.json, and its registries
 are the per-affiliate `*-tx-servers.json` files in the same repository (HL7 International,
 HL7 Australia, HL7 Europe, and so on). A server's registration carries:

package/registry/model.js

@@ -362,6 +362,8 @@ class ServerRegistries {
   constructor() {
     this.address = '';
     this.doco = '';
+    this.registration = ''; // URL: how to register your own server in this ecosystem
+    this.ecosystemDoco = ''; // URL: documentation for this ecosystem
     this.lastRun = null; // Date object
     this.outcome = '';
     this.registries = []; // Array of ServerRegistry
@@ -386,6 +388,8 @@ class ServerRegistries {
     this.lastRun = source.lastRun;
     this.outcome = source.outcome;
     this.doco = source.doco;
+    this.registration = source.registration;
+    this.ecosystemDoco = source.ecosystemDoco;
     
     source.registries.forEach(sourceRegistry => {
       const existing = this.getRegistry(sourceRegistry.code);
@@ -402,6 +406,8 @@ class ServerRegistries {
       version: '1',
       address: this.address,
       doco: this.doco,
+      registration: this.registration,
+      'ecosystem-documentation': this.ecosystemDoco,
       'last-run': this.lastRun?.toISOString() || '',
       outcome: this.outcome,
       registries: this.registries.map(r => r.toJSON())
@@ -416,6 +422,8 @@ class ServerRegistries {
     const instance = new ServerRegistries();
     instance.address = json.address || '';
     instance.doco = json.doco || '';
+    instance.registration = json.registration || '';
+    instance.ecosystemDoco = json['ecosystem-documentation'] || '';
     instance.lastRun = json['last-run'] ? new Date(json['last-run']) : null;
     instance.outcome = json.outcome || '';
     instance.registries = (json.registries || []).map(r => ServerRegistry.fromJSON(r));

package/registry/openapi.yaml

@@ -25,6 +25,9 @@ info:
     * **Resolution** (`GET /resolve`): which server should be used for this code system
       or value set?
 
+    It also offers **server choice** (`GET /choose-server`): given all the code systems a
+    request involves, and the client's default server, which one server should it go to?
+
     Servers can claim to be **authoritative** for code systems and value sets (by URL
     mask) in their registration. A server that hosts the content but makes no claim is a
     **candidate**. A server is only ever returned for content it actually hosts.
@@ -182,6 +185,77 @@ paths:
               schema: { $ref: '#/components/schemas/Error' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
+  /choose-server:
+    get:
+      tags: [resolution]
+      operationId: chooseServer
+      summary: Choose one server for a request involving several code systems
+      description: |
+        For clients that aren't the HL7 Java tooling: the same choice the Java tooling makes
+        (TerminologyClientManager.chooseServer), made from the registry's own data. Returns
+        the server to send the request to, and a log of how it was chosen.
+
+        The client works out the code systems the request involves - from the codings, and
+        the value set's includes and excludes, following imported value sets - and applies
+        any versions fixed by expansion parameters. If it can't follow an import, it should
+        use its default server without asking.
+
+        In order, the choice is:
+
+        1. a server authoritative for all the code systems
+        2. a server authoritative for one, and authoritative or a candidate for the others
+        3. for several code systems including SNOMED CT, the choice for SNOMED CT alone; for
+           a code system tx.fhir.org handles specially (LOINC, UCUM, RxNorm ...), the default
+        4. a server that is a candidate for all of them, and reports a usable (complete or
+           fragment) copy of each, or no content mode at all
+        5. the server authoritative for the most of them
+        6. the server the value set comes from (resolved by `valueSet`), else the default
+
+        In 2 and 4, a code system that no server hosts doesn't count against a server.
+      parameters:
+        - name: fhirVersion
+          in: query
+          required: true
+          description: The FHIR version, as a release code (`R4`, `R4B`, `R5` ...) or a version (`4.0.1`, `4.0`).
+          schema: { type: string }
+          example: R4
+        - name: system
+          in: query
+          description: |
+            A code system the request involves, `url` or `url|version`. Repeat for each one
+            (`system=a&system=b`). With none, the answer is the default server.
+          schema: { type: array, items: { type: string } }
+          style: form
+          explode: true
+          example: [http://loinc.org, http://snomed.info/sct|http://snomed.info/sct/32506021000036107]
+        - name: default
+          in: query
+          required: true
+          description: The client's default terminology server (the one it would use without the ecosystem).
+          schema: { type: string, format: uri }
+          example: http://tx.fhir.org/r4
+        - name: valueSet
+          in: query
+          description: The value set the request is about, `url` or `url|version`, if there is one. Used for the log, and in step 6.
+          schema: { type: string }
+        - $ref: '#/components/parameters/language'
+        - name: usage
+          in: query
+          description: What the client is doing, for servers that restrict their use (as for `/resolve`).
+          schema: { type: string }
+      responses:
+        '200':
+          description: The chosen server
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ChooseServerResult' }
+        '400':
+          description: A required parameter is missing, or a URL is malformed
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
 components:
   securitySchemes:
     bearer:
@@ -311,6 +385,16 @@ components:
           type: array
           items: { $ref: '#/components/schemas/ResolvedServer' }
 
+    ChooseServerResult:
+      type: object
+      required: [server, log]
+      properties:
+        server: { type: string, format: uri, description: The FHIR endpoint to send the request to }
+        log:
+          type: array
+          items: { type: string }
+          description: How the server was chosen - what the registry says about each code system, then the rule that decided. For people, not for parsing
+
     ResolvedServer:
       allOf:
         - $ref: '#/components/schemas/SecurityFlags'