fhirsmith 0.14.1 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/README.md +3 -2
  3. package/config-template.json +9 -0
  4. package/library/changelog.js +57 -0
  5. package/library/fhir-openapi-schema.js +441 -0
  6. package/library/html-server.js +9 -3
  7. package/library/npm-audit.js +265 -0
  8. package/library/openapi-doc.js +557 -0
  9. package/library/utilities.js +21 -0
  10. package/package.json +10 -4
  11. package/packages/openapi.js +13 -0
  12. package/packages/openapi.yaml +603 -0
  13. package/packages/packages-template.html +4 -2
  14. package/packages/packages.js +286 -81
  15. package/packages/readme.md +120 -0
  16. package/registry/api.js +117 -41
  17. package/registry/crawler.js +41 -0
  18. package/registry/fhirsmith-releases.js +167 -0
  19. package/registry/model.js +13 -0
  20. package/registry/openapi.js +13 -0
  21. package/registry/openapi.yaml +311 -0
  22. package/registry/readme.md +107 -208
  23. package/registry/registry-template.html +4 -1
  24. package/registry/registry.js +198 -19
  25. package/server.js +19 -5
  26. package/testing/openapi-schemas.config.js +58 -0
  27. package/testing/openapi-schemas.json +1920 -0
  28. package/testing/openapi.js +15 -0
  29. package/testing/openapi.yaml +273 -0
  30. package/testing/readme.md +43 -1
  31. package/testing/search.js +1 -1
  32. package/testing/testing-template.html +2 -0
  33. package/testing/testing.js +24 -0
  34. package/translations/Messages.properties +1 -0
  35. package/tx/README.md +78 -4
  36. package/tx/cm/cm-api.js +25 -10
  37. package/tx/cm/cm-database.js +10 -5
  38. package/tx/cm/cm-package.js +61 -15
  39. package/tx/cs/cs-provider-api.js +22 -7
  40. package/tx/cs/cs-provider-list.js +10 -9
  41. package/tx/cs/cs-rxnorm.js +23 -6
  42. package/tx/html/tx-template.html +2 -0
  43. package/tx/library/canonical-resource.js +50 -1
  44. package/tx/library/codesystem.js +1 -0
  45. package/tx/library/conceptmap.js +1 -0
  46. package/tx/library/resource-ids.js +107 -0
  47. package/tx/library/valueset.js +16 -0
  48. package/tx/library.js +113 -26
  49. package/tx/ocl/cm-ocl.cjs +23 -15
  50. package/tx/ocl/cs-ocl.cjs +9 -10
  51. package/tx/ocl/vs-ocl.cjs +17 -17
  52. package/tx/openapi-operations.js +363 -0
  53. package/tx/openapi-schemas.config.js +118 -0
  54. package/tx/openapi-schemas.json +7903 -0
  55. package/tx/openapi.js +289 -0
  56. package/tx/openapi.yaml +151 -0
  57. package/tx/operation-context.js +15 -0
  58. package/tx/params.js +3 -12
  59. package/tx/provider.js +90 -14
  60. package/tx/tx-html.js +6 -0
  61. package/tx/tx.fhir.org.yml +16 -8
  62. package/tx/tx.js +62 -1
  63. package/tx/vs/vs-api.js +25 -10
  64. package/tx/vs/vs-database.js +14 -9
  65. package/tx/vs/vs-package.js +58 -31
  66. package/tx/vs/vs-vsac.js +20 -5
  67. package/tx/workers/expand.js +35 -16
  68. package/tx/workers/metadata.js +2 -14
  69. package/tx/workers/read.js +3 -18
  70. package/tx/workers/validate.js +65 -19
  71. package/tx/workers/worker.js +29 -8
  72. package/utilities/extract-schema-json.js +167 -0
  73. package/utilities/generate-openapi-schemas.js +49 -0
  74. package/xig/xig.js +2 -4
package/tx/openapi.js ADDED
@@ -0,0 +1,289 @@
1
+ //
2
+ // Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
3
+ //
4
+ // Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
5
+ //
6
+
7
+ // The terminology server's OpenAPI description (R5 endpoints only): openapi.yaml (the
8
+ // overview, /metadata, /$versions, the shared components), plus the paths made here from
9
+ // the operations in openapi-operations.js and the read and search interactions, plus the
10
+ // FHIR resource schemas generated into openapi-schemas.json (see openapi-schemas.config.js).
11
+
12
+ const path = require('path');
13
+ const { createOpenApiDoc } = require('../library/openapi-doc');
14
+ const { OPERATIONS, COMMON } = require('./openapi-operations');
15
+
16
+ const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
17
+ const param = (name) => ({ $ref: `#/components/parameters/${name}` });
18
+
19
+ const RESOURCE_TYPES = ['CodeSystem', 'ValueSet', 'ConceptMap'];
20
+
21
+ const PRIMITIVES = new Set([
22
+ 'boolean', 'canonical', 'code', 'date', 'dateTime', 'decimal', 'id', 'instant', 'integer',
23
+ 'integer64', 'markdown', 'oid', 'positiveInt', 'string', 'time', 'unsignedInt', 'uri', 'url', 'uuid'
24
+ ]);
25
+
26
+ function isPrimitive(type) {
27
+ return PRIMITIVES.has(type);
28
+ }
29
+
30
+ /** The JSON schema of a primitive parameter, as a query parameter. */
31
+ function querySchema(type) {
32
+ switch (type) {
33
+ case 'boolean': return { type: 'boolean' };
34
+ case 'integer': return { type: 'integer' };
35
+ case 'positiveInt': return { type: 'integer', minimum: 1 };
36
+ case 'unsignedInt': return { type: 'integer', minimum: 0 };
37
+ case 'decimal': return { type: 'number' };
38
+ default: return { type: 'string', 'x-fhir-type': type };
39
+ }
40
+ }
41
+
42
+ // a table cell: backslashes escaped first, then the pipes (which would end the cell)
43
+ function cell(s) {
44
+ return String(s || '').replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\n/g, ' ');
45
+ }
46
+
47
+ function typeCell(p) {
48
+ if (p.type === '(parts)') {
49
+ return 'parts';
50
+ }
51
+ return isPrimitive(p.type) ? `\`${p.type}\`` : p.type;
52
+ }
53
+
54
+ /** A markdown table of parameters. */
55
+ function paramTable(params, inbound) {
56
+ const rows = [];
57
+ for (const p of params) {
58
+ let doc = p.doc || '';
59
+ if (inbound && !isPrimitive(p.type)) {
60
+ doc += (doc ? ' ' : '') + '(POST, in a Parameters resource, only)';
61
+ }
62
+ rows.push(`| \`${cell(p.name)}\` | ${typeCell(p)} | ${p.min}..${p.max} | ${cell(doc)} |`);
63
+ for (const part of p.parts || []) {
64
+ rows.push(`|   \`${cell(p.name)}.${cell(part.name)}\` | ${typeCell(part)} | ${part.min}..${part.max} | ${cell(part.doc)} |`);
65
+ }
66
+ }
67
+ return '| Name | Type | Card. | Description |\n|---|---|---|---|\n' + rows.join('\n');
68
+ }
69
+
70
+ function camel(s) {
71
+ return s.replace(/-([a-z])/g, (m, c) => c.toUpperCase());
72
+ }
73
+
74
+ function errorResponses(extra = {}) {
75
+ return {
76
+ '400': { $ref: '#/components/responses/Outcome', description: 'The request is not valid' },
77
+ '404': { $ref: '#/components/responses/Outcome', description: 'Something the request names was not found' },
78
+ '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)' },
79
+ '500': { $ref: '#/components/responses/Outcome', description: 'The server failed' },
80
+ ...extra
81
+ };
82
+ }
83
+
84
+ function okResponse(op) {
85
+ const schema = ref(op.returns || 'Parameters');
86
+ return {
87
+ description: op.returnsDoc || 'The out parameters (see the table)',
88
+ content: { 'application/fhir+json': { schema }, 'application/json': { schema } }
89
+ };
90
+ }
91
+
92
+ /** The paths of one operation: its levels, and its methods. */
93
+ function queryParameter(qp) {
94
+ const schema = querySchema(qp.type);
95
+ const result = {
96
+ name: qp.name,
97
+ in: 'query',
98
+ description: qp.doc,
99
+ schema: qp.max === '*' ? { type: 'array', items: schema } : schema
100
+ };
101
+ if (qp.min > 0) {
102
+ result.required = true;
103
+ }
104
+ if (qp.max === '*') {
105
+ result.style = 'form';
106
+ result.explode = true;
107
+ }
108
+ return result;
109
+ }
110
+
111
+ function formSchema(params) {
112
+ const form = { type: 'object', properties: {} };
113
+ for (const fp of params) {
114
+ form.properties[fp.name] = fp.max === '*' ? { type: 'array', items: querySchema(fp.type) } : querySchema(fp.type);
115
+ }
116
+ return form;
117
+ }
118
+
119
+ /** The common parameters: in the overview, and as components the operations refer to. */
120
+ function addCommon(spec) {
121
+ spec.info.description += '\n**Common parameters.** These are read by $expand, $validate-code, ' +
122
+ '$lookup, $subsumes, $translate and $compare, as well as their own parameters:\n\n' + paramTable(COMMON, true) + '\n';
123
+ for (const cp of COMMON.filter(x => isPrimitive(x.type))) {
124
+ spec.components.parameters[`common-${cp.name}`] = queryParameter(cp);
125
+ }
126
+ }
127
+
128
+ function addOperation(spec, op) {
129
+ const methods = op.methods || ['get', 'post'];
130
+ const queryParams = op.in.filter(p => isPrimitive(p.type));
131
+ const commonQuery = op.common ? COMMON.filter(x => isPrimitive(x.type)) : [];
132
+ let description = (op.description || '') + '\n\n**In parameters**' +
133
+ (op.common ? ' (and the common parameters - see the overview)' : '') + '\n\n' + paramTable(op.in, true);
134
+ if (op.out) {
135
+ description += '\n\n**Out parameters** (a Parameters resource)\n\n' + paramTable(op.out, false);
136
+ }
137
+ for (const level of op.levels) {
138
+ const p = level === 'system' ? `/$${op.name}`
139
+ : level === 'type' ? `/${op.resource}/$${op.name}`
140
+ : `/${op.resource}/{id}/$${op.name}`;
141
+ const item = spec.paths[p] = spec.paths[p] || {};
142
+ const baseId = camel(op.name) + (op.resource || '') + (level === 'instance' ? 'Instance' : '');
143
+ const common = [param('acceptLanguage'), param('cacheId'), param('format')];
144
+ if (level === 'instance') {
145
+ common.unshift(param('id'));
146
+ }
147
+ const levelDoc = level === 'instance' ? `\n\nThe ${op.resource} is the one with this id.` : '';
148
+ for (const method of methods) {
149
+ const o = {
150
+ tags: [op.resource || 'Server'],
151
+ operationId: method === 'get' || methods.length === 1 ? baseId : baseId + 'Post',
152
+ summary: op.summary,
153
+ description: description + levelDoc
154
+ };
155
+ if (method === 'get') {
156
+ o.parameters = [...common, ...queryParams.map(queryParameter), ...commonQuery.map(cp => param(`common-${cp.name}`))];
157
+ } else {
158
+ // parameters that are in the query even for a POST
159
+ o.parameters = [...common, ...op.in.filter(x => x.inQuery).map(qp => ({
160
+ name: qp.name, in: 'query', description: qp.doc, required: qp.min > 0, schema: querySchema(qp.type)
161
+ }))];
162
+ const bodies = op.postBody || ['Parameters'];
163
+ const schema = bodies.length === 1 ? ref(bodies[0]) : { anyOf: bodies.map(ref) };
164
+ const form = formSchema([...queryParams.filter(x => !x.inQuery), ...commonQuery]);
165
+ o.requestBody = {
166
+ required: true,
167
+ description: bodies.length === 1 ? 'The in parameters, as a Parameters resource (or a form)'
168
+ : `The in parameters, as a Parameters resource (or a form), or the ${bodies[1]} itself`,
169
+ content: {
170
+ 'application/fhir+json': { schema },
171
+ 'application/json': { schema },
172
+ 'application/x-www-form-urlencoded': { schema: form }
173
+ }
174
+ };
175
+ }
176
+ o.responses = { '200': okResponse(op), ...errorResponses(op.responses || {}) };
177
+ item[method] = o;
178
+ }
179
+ }
180
+ }
181
+
182
+ const SEARCH_DOCS = {
183
+ url: 'The canonical url (exact)',
184
+ system: 'The canonical url (exact; the same as url)',
185
+ version: 'The version (contains)',
186
+ name: 'The name (contains)',
187
+ title: 'The title (contains)',
188
+ status: 'The status (contains)',
189
+ publisher: 'The publisher (contains)',
190
+ description: 'The description (contains)',
191
+ date: 'The date (contains)',
192
+ identifier: 'An identifier (contains)',
193
+ jurisdiction: 'A jurisdiction: a code or display (contains)',
194
+ text: 'The title or description (contains)',
195
+ 'content-mode': 'CodeSystem: the content mode (contains)',
196
+ supplements: 'CodeSystem: what it supplements (contains)',
197
+ 'source-system': 'ConceptMap: the source code system',
198
+ 'target-system': 'ConceptMap: the target code system',
199
+ _offset: 'Paging: where to start (0 based)',
200
+ _count: 'Paging: how many to return (at most 200, or 2000 with _elements)',
201
+ _elements: 'The elements to return (comma separated)',
202
+ _sort: 'The element to sort by (default id)',
203
+ _summary: '`true`, `text`, `data`, `count` or `false`',
204
+ _total: '`none` to leave out the total (default accurate)'
205
+ };
206
+
207
+ /** Read, and search (GET, and POST _search), for each resource type. */
208
+ function addReadSearch(spec) {
209
+ // required here: the search worker requires tx-html, which requires this
210
+ const SEARCH_PARAMS = require('./workers/search').ALLOWED_PARAMS;
211
+ for (const type of RESOURCE_TYPES) {
212
+ const searchParams = SEARCH_PARAMS.filter(n => n !== '_format').map(n => ({
213
+ name: n,
214
+ in: 'query',
215
+ description: SEARCH_DOCS[n] || '',
216
+ schema: ['_offset', '_count'].includes(n) ? { type: 'integer', minimum: 0 } : { type: 'string' }
217
+ }));
218
+ if (type !== 'CodeSystem') {
219
+ searchParams.push({ name: 'source', in: 'query', description: 'Only those from this source (package)', schema: { type: 'string' } });
220
+ }
221
+ const bundle = ref(`${type}SearchBundle`);
222
+ const searchDoc = `Searches the ${type}s the server has. Text matches are case insensitive and partial ` +
223
+ '(contains), except url and system; all the parameters given must match.';
224
+ const searchResponses = {
225
+ '200': { description: `A searchset Bundle of ${type}s`, content: { 'application/fhir+json': { schema: bundle } } },
226
+ '500': { $ref: '#/components/responses/Outcome' }
227
+ };
228
+ spec.paths[`/${type}`] = {
229
+ get: {
230
+ tags: [type], operationId: `search${type}`, summary: `Search ${type}s`, description: searchDoc,
231
+ parameters: [...searchParams, param('format')], responses: searchResponses
232
+ }
233
+ };
234
+ const form = { type: 'object', properties: {} };
235
+ searchParams.forEach(sp => {
236
+ form.properties[sp.name] = sp.schema;
237
+ });
238
+ spec.paths[`/${type}/_search`] = {
239
+ post: {
240
+ tags: [type], operationId: `search${type}Post`, summary: `Search ${type}s (POST)`,
241
+ description: searchDoc + ' The parameters are in a form body.',
242
+ requestBody: { content: { 'application/x-www-form-urlencoded': { schema: form } } },
243
+ responses: searchResponses
244
+ }
245
+ };
246
+ spec.paths[`/${type}/{id}`] = {
247
+ get: {
248
+ tags: [type], operationId: `read${type}`, summary: `Read a ${type}`,
249
+ parameters: [param('id'), param('format')],
250
+ responses: {
251
+ '200': { description: `The ${type}`, content: { 'application/fhir+json': { schema: ref(type) } } },
252
+ '404': { $ref: '#/components/responses/Outcome', description: 'There is no such resource' }
253
+ }
254
+ }
255
+ };
256
+ }
257
+ }
258
+
259
+ function build(spec) {
260
+ addCommon(spec);
261
+ addReadSearch(spec);
262
+ for (const op of OPERATIONS) {
263
+ addOperation(spec, op);
264
+ }
265
+ }
266
+
267
+ const SPEC_PATH = path.join(__dirname, 'openapi.yaml');
268
+ const SCHEMAS_PATH = path.join(__dirname, 'openapi-schemas.json');
269
+
270
+ const docs = new Map();
271
+
272
+ /**
273
+ * The description, for an R5 endpoint (its servers url is the endpoint)
274
+ * @param {string} endpointPath - e.g. /tx/r5
275
+ */
276
+ function forEndpoint(endpointPath) {
277
+ if (!docs.has(endpointPath)) {
278
+ docs.set(endpointPath, createOpenApiDoc(SPEC_PATH, endpointPath,
279
+ { schemasPath: SCHEMAS_PATH, build, serverUrl: endpointPath }));
280
+ }
281
+ return docs.get(endpointPath);
282
+ }
283
+
284
+ /** Whether an endpoint's FHIR version is the one described (R5) */
285
+ function describes(fhirVersion) {
286
+ return String(fhirVersion).startsWith('5');
287
+ }
288
+
289
+ module.exports = { forEndpoint, describes, isPrimitive, RESOURCE_TYPES, SEARCH_DOCS };
@@ -0,0 +1,151 @@
1
+ # OpenAPI description of the FHIRsmith terminology server (an R5 endpoint, e.g. /tx/r5).
2
+ #
3
+ # Three parts, merged when the spec is served (see openapi.js):
4
+ # - this file: the overview, /metadata and /$versions, and the shared components
5
+ # - openapi-operations.js: the terminology operations, as data. openapi.js makes their
6
+ # paths (type and instance level, GET and POST) and their parameter tables, and the
7
+ # read and search paths
8
+ # - openapi-schemas.json: the FHIR R5 resource schemas, generated from the
9
+ # StructureDefinitions by utilities/generate-openapi-schemas.js (see
10
+ # openapi-schemas.config.js)
11
+ #
12
+ # tests/tx/openapi.test.js keeps this honest: every route must be described or explicitly
13
+ # excluded, the parameters must be the ones the code reads, and real responses must
14
+ # validate against the schemas.
15
+ #
16
+ # HTML pages (/, /op.html, /ecl, /problems.html, /info, /library) are not described.
17
+ # info.version is filled in from package.json, and servers from the endpoint, when the spec
18
+ # is served.
19
+
20
+ openapi: 3.1.0
21
+ info:
22
+ title: FHIRsmith Terminology Server
23
+ version: "0.0.0"
24
+ summary: A FHIR terminology server (R5)
25
+ description: |
26
+ A FHIR terminology server: code systems, value sets and concept maps, and the
27
+ terminology operations on them - $expand, $validate-code, $lookup, $subsumes,
28
+ $translate, and more. This describes an R5 endpoint; the server's R4 and R3 endpoints
29
+ work the same way, with the resources of that version.
30
+
31
+ The operations are the ones FHIR defines (see the [terminology
32
+ service](https://hl7.org/fhir/R5/terminology-service.html)), with the behaviour the
33
+ [terminology ecosystem IG](https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig/) asks of
34
+ the servers in the ecosystem. Each operation lists the parameters this server reads.
35
+
36
+ **Requests.** An operation can be invoked with GET, with its parameters in the query, or
37
+ with POST, with a Parameters resource (`application/fhir+json`), or a form. Parameters
38
+ whose values are not primitives (a Coding, a resource) can only be sent in a Parameters
39
+ resource.
40
+
41
+ **Responses** are JSON by default; `application/fhir+xml` (or `_format=xml`) gets XML,
42
+ and a browser (or `_format=html`) gets an HTML page. Only the JSON is described here.
43
+ Errors are OperationOutcomes, and every issue (except information) has a tx-issue-type
44
+ code in `details.coding` and its message in `details.text`.
45
+
46
+ **Schemas.** The resource schemas describe what this server handles and returns: it
47
+ doesn't reject content outside them (an extension with a Quantity value, say), but it
48
+ isn't designed to do anything with it. They have the JSON `_x` elements (the id and
49
+ extensions of a primitive) and modifierExtension wherever FHIR allows them. Contained
50
+ resources are value sets, in a value set, only.
51
+
52
+ **Caching.** A client that sends the same resources (`tx-resource`) with many requests
53
+ can keep them on the server with `$cache-control`, and then send the cache's id in the
54
+ `X-Cache-Id` header.
55
+ license:
56
+ name: BSD-3-Clause
57
+ url: https://opensource.org/license/bsd-3-clause
58
+ externalDocs:
59
+ description: The FHIR R5 terminology service
60
+ url: https://hl7.org/fhir/R5/terminology-service.html
61
+ servers:
62
+ - url: /tx/r5
63
+
64
+ tags:
65
+ - name: Server
66
+ description: What the server does, and operations on the server as a whole
67
+ - name: CodeSystem
68
+ description: Code systems, and $lookup, $validate-code and $subsumes
69
+ - name: ValueSet
70
+ description: Value sets, and $expand, $validate-code and $compare
71
+ - name: ConceptMap
72
+ description: Concept maps, and $translate
73
+
74
+ paths:
75
+ /metadata:
76
+ get:
77
+ tags: [Server]
78
+ operationId: metadata
79
+ summary: The server's capabilities
80
+ description: |
81
+ The CapabilityStatement, or with `mode=terminology`, the TerminologyCapabilities:
82
+ the code systems (and versions) the server has, and the expansion parameters it
83
+ understands.
84
+ parameters:
85
+ - name: mode
86
+ in: query
87
+ description: '`terminology` for the TerminologyCapabilities'
88
+ schema: { type: string, enum: [terminology] }
89
+ - $ref: '#/components/parameters/format'
90
+ responses:
91
+ '200':
92
+ description: The CapabilityStatement, or the TerminologyCapabilities
93
+ content:
94
+ application/fhir+json:
95
+ schema:
96
+ anyOf:
97
+ - $ref: '#/components/schemas/CapabilityStatement'
98
+ - $ref: '#/components/schemas/TerminologyCapabilities'
99
+
100
+ /$versions:
101
+ get:
102
+ tags: [Server]
103
+ operationId: versions
104
+ summary: The FHIR versions of this endpoint
105
+ description: |
106
+ The FHIR version this endpoint uses. With `Accept: application/fhir+json` the answer
107
+ is a Parameters resource (`version` and `default`); otherwise, a simple JSON object.
108
+ responses:
109
+ '200':
110
+ description: The versions
111
+ content:
112
+ application/fhir+json:
113
+ schema: { $ref: '#/components/schemas/Parameters' }
114
+ application/json:
115
+ schema:
116
+ type: object
117
+ properties:
118
+ versions: { type: array, items: { type: string }, example: ['5.0'] }
119
+ default: { type: string, example: '5.0' }
120
+ required: [versions, default]
121
+
122
+ components:
123
+ parameters:
124
+ id:
125
+ name: id
126
+ in: path
127
+ required: true
128
+ description: The resource's id
129
+ schema: { type: string }
130
+ format:
131
+ name: _format
132
+ in: query
133
+ description: '`json`, `xml` or `html`, instead of the Accept header'
134
+ schema: { type: string, enum: [json, xml, html] }
135
+ acceptLanguage:
136
+ name: Accept-Language
137
+ in: header
138
+ description: The language(s) for displays and messages
139
+ schema: { type: string }
140
+ example: en
141
+ cacheId:
142
+ name: X-Cache-Id
143
+ in: header
144
+ description: A cache of resources, started with $cache-control
145
+ schema: { type: string }
146
+ responses:
147
+ Outcome:
148
+ description: An error, as an OperationOutcome
149
+ content:
150
+ application/fhir+json:
151
+ schema: { $ref: '#/components/schemas/OperationOutcome' }
@@ -1084,6 +1084,21 @@ class OperationContext {
1084
1084
  this.contexts.push(vurl);
1085
1085
  }
1086
1086
 
1087
+ /**
1088
+ * Stop tracking a context, once processing of that value set is finished. The tracked
1089
+ * contexts are the chain of value sets currently being processed, not every value set
1090
+ * seen in the operation: a value set used twice (imported by two others, or twice by
1091
+ * one) is not a circularity - only one that is reached again while it's being
1092
+ * processed is.
1093
+ * @param {string} vurl - the url passed to seeContext
1094
+ */
1095
+ unseeContext(vurl) {
1096
+ const i = this.contexts.lastIndexOf(vurl);
1097
+ if (i >= 0) {
1098
+ this.contexts.splice(i, 1);
1099
+ }
1100
+ }
1101
+
1087
1102
  /**
1088
1103
  * Clear all tracked contexts
1089
1104
  */
package/tx/params.js CHANGED
@@ -372,11 +372,6 @@ class TxParameters {
372
372
  if (claim('no-cache') && asBool()) this.FUid = crypto.randomUUID();
373
373
  break;
374
374
  }
375
- case '_incomplete':
376
- case 'limitedExpansion': {
377
- if (claim('limitedExpansion')) this.limitedExpansion = asBool();
378
- break;
379
- }
380
375
  case 'includeDesignations': {
381
376
  if (claim('includeDesignations')) this.includeDesignations = asBool();
382
377
  break;
@@ -405,10 +400,6 @@ class TxParameters {
405
400
  if (claim('default-to-latest-version')) this.defaultToLatestVersion = asBool();
406
401
  break;
407
402
  }
408
- case 'incomplete-ok': {
409
- if (claim('incomplete-ok')) this.incompleteOK = asBool();
410
- break;
411
- }
412
403
  case 'diagnostics': {
413
404
  if (claim('diagnostics')) this.diagnostics = asBool();
414
405
  break;
@@ -629,11 +620,11 @@ class TxParameters {
629
620
  s = s + '$' + [...this.supplements].sort().join(',') + '|';
630
621
  }
631
622
  // Further result-affecting parameters that were previously omitted from the
632
- // key: the text filter (changes which codes expand), limited/incomplete
633
- // expansion handling, whether abstract codes are included, and diagnostics.
623
+ // key: the text filter (changes which codes expand), whether abstract codes
624
+ // are included, and diagnostics.
634
625
  // filter is free text, so JSON.stringify it to avoid delimiter collisions.
635
626
  s = s + 'f:' + JSON.stringify(this.filter || '') + '|' +
636
- b(this.limitedExpansion) + b(this.incompleteOK) + b(this.abstractOk) + b(this.diagnostics);
627
+ b(this.abstractOk) + b(this.diagnostics);
637
628
  for (let t of this.FVersionRules) {
638
629
  s = s + t.asString() + '|';
639
630
  }
package/tx/provider.js CHANGED
@@ -9,6 +9,7 @@ const {PackageContentLoader} = require("../library/package-manager");
9
9
  const {PackageValueSetProvider} = require("./vs/vs-package");
10
10
  const ValueSet = require("./library/valueset");
11
11
  const {PackageConceptMapProvider} = require("./cm/cm-package");
12
+ const { applyIdPrefix, CORE_PREFIX } = require("./library/resource-ids");
12
13
 
13
14
  /**
14
15
  * This class holds what information is in context
@@ -153,6 +154,12 @@ class Provider {
153
154
  }
154
155
 
155
156
 
157
+ /**
158
+ * Load the FHIR core package for this endpoint. Its resources are served in the 'core' id
159
+ * space (CodeSystem/core-v3-MaritalStatus): the core packages for different FHIR versions
160
+ * share ids, and so does other content (hl7.terminology), so no endpoint can serve them on
161
+ * their own ids (see tx/library/resource-ids.js)
162
+ */
156
163
  async loadNpm(packageManager, cacheFolder, details, isDefault, mode) {
157
164
  // Parse packageId and version from details (e.g., "hl7.terminology.r4#6.0.2")
158
165
  let packageId = details;
@@ -171,16 +178,39 @@ class Provider {
171
178
  await contentLoader.initialize();
172
179
 
173
180
  const resources = await contentLoader.getResourcesByType("CodeSystem");
181
+ let i = 0;
182
+ // the index has the urls as they are in the package; the version is taken out of the url
183
+ // when the code system is loaded (see normalizeVersionedCanonicals in package-manager.js)
174
184
  for (const resource of resources) {
175
- const cs = new CodeSystem(await contentLoader.loadFile(resource, contentLoader.fhirVersion()));
185
+ let cs;
186
+ try {
187
+ cs = new CodeSystem(await contentLoader.loadFile(resource, contentLoader.fhirVersion()));
188
+ } catch (e) {
189
+ // one unacceptable resource (e.g. contained resources the server doesn't support)
190
+ // must not stop the rest of the package loading
191
+ require('../library/logger').getInstance().child({ module: 'tx' })
192
+ .warn(`Package ${contentLoader.pid()}: skipping CodeSystem ${resource.id || resource.filename || ''}: ${e.message}`);
193
+ continue;
194
+ }
176
195
  cs.sourcePackage = contentLoader.pid();
196
+ if (typeof resource.url === 'string' && resource.url.includes('|')) {
197
+ cs.urlHadVersion = true; // see addCodeSystem
198
+ }
199
+ // these objects belong to this endpoint, so they can be given ids here
200
+ i++;
201
+ if (!cs.id) {
202
+ cs.id = String(i);
203
+ }
204
+ applyIdPrefix(cs, CORE_PREFIX);
177
205
  this.addCodeSystem(cs);
178
206
  }
179
207
  const vs = new PackageValueSetProvider(contentLoader);
180
208
  await vs.initialize();
209
+ vs.assignIds(CORE_PREFIX);
181
210
  this.valueSetProviders.push(vs);
182
211
  const cm = new PackageConceptMapProvider(contentLoader);
183
212
  await cm.initialize();
213
+ cm.assignIds(CORE_PREFIX);
184
214
  this.conceptMapProviders.push(cm);
185
215
  }
186
216
 
@@ -573,27 +603,38 @@ class Provider {
573
603
  return pid != null && pid.startsWith("hl7.terminology");
574
604
  }
575
605
 
606
+ /**
607
+ * Add a code system to the ones this endpoint knows, by url and by url|version.
608
+ *
609
+ * THO precedence, as in CanonicalResourceManager.see() in the Java core: content that
610
+ * moved from the FHIR core packages to terminology.hl7.org has been QA'd there since, and
611
+ * its versions went backwards (coverage-selfpay is 4.0.1 in hl7.fhir.r4.core but 1.0.1 in
612
+ * hl7.terminology), so version precedence can't decide between them. Instead, a code system
613
+ * from an hl7.terminology package replaces every code system with the same url from a FHIR
614
+ * core package - none of the core versions stay available.
615
+ *
616
+ * Except: hl7.fhir.r4.core has the v2 tables 0006, 0360 and 0391 in two versions each,
617
+ * with the version in the url (http://terminology.hl7.org/CodeSystem/v2-0006|2.1 - see
618
+ * urlHadVersion in loadNpm). hl7.terminology doesn't publish those versions, so they stay
619
+ * available by url|version; THO's code system is the default for the url.
620
+ */
576
621
  addCodeSystem(cs) {
577
- // Special case, mirroring CanonicalResourceManager.see() in the Java core:
578
- // when content moved from the FHIR core packages to terminology.hl7.org,
579
- // the versions went backwards (e.g. coverage-selfpay is 4.0.1 in
580
- // hl7.fhir.r4.core (2019) but 1.0.1 in hl7.terminology (2024)), so plain
581
- // version precedence would leave the stale core copy as the default. A
582
- // resource from an hl7.terminology package displaces any same-URL
583
- // resource that came from a FHIR core package, regardless of version.
584
622
  if (Provider.#isTHOPackage(cs.sourcePackage)) {
585
623
  for (const [key, t] of [...this.codeSystems]) {
586
- // only the bare-url (default) entry is displaced; explicitly versioned
587
- // entries (key = url|version) stay addressable, because the core packages
588
- // carry historical versions (e.g. the normalized R4 v2 tables 0006/0360/0391
589
- // at 2.1/2.3.1/2.4/2.6/2.7) that hl7.terminology does not publish at all
590
- if (key === t.url && t.url === cs.url && VersionUtilities.isCorePackage(t.sourcePackage)) {
624
+ if (t.url === cs.url && VersionUtilities.isCorePackage(t.sourcePackage)
625
+ && (key === t.url || !t.urlHadVersion)) {
591
626
  this.codeSystems.delete(key);
592
627
  }
593
628
  }
629
+ } else if (VersionUtilities.isCorePackage(cs.sourcePackage) && !cs.urlHadVersion) {
630
+ // THO's code system is always the default for its url
631
+ const t = this.codeSystems.get(cs.url);
632
+ if (t && Provider.#isTHOPackage(t.sourcePackage)) {
633
+ return;
634
+ }
594
635
  }
595
636
  const existing = this.codeSystems.get(cs.url);
596
- // the reverse guard: a core-package resource never displaces a THO one
637
+ // a core-package resource never displaces a THO one as the default
597
638
  const yieldsToTHO = existing && Provider.#isTHOPackage(existing.sourcePackage)
598
639
  && VersionUtilities.isCorePackage(cs.sourcePackage);
599
640
  if (!existing || (!yieldsToTHO && cs.isMoreRecent(existing))) {
@@ -610,6 +651,41 @@ class Provider {
610
651
  }
611
652
  }
612
653
 
654
+ /**
655
+ * THO precedence for value sets and concept maps, as for code systems (see addCodeSystem):
656
+ * once the library's providers have been added after this endpoint's core package, the core
657
+ * package's value sets and concept maps whose urls an hl7.terminology package also provides
658
+ * are left out. (No core value set or concept map has the version in its url.)
659
+ */
660
+ applyTHOPrecedence() {
661
+ const thoValueSets = new Set();
662
+ for (const vp of this.valueSetProviders) {
663
+ if (vp instanceof PackageValueSetProvider && Provider.#isTHOPackage(vp.sourcePackage())) {
664
+ for (const vs of vp.valueSetMap.values()) {
665
+ thoValueSets.add(vs.url);
666
+ }
667
+ }
668
+ }
669
+ const thoConceptMaps = new Set();
670
+ for (const cmp of this.conceptMapProviders) {
671
+ if (cmp instanceof PackageConceptMapProvider && Provider.#isTHOPackage(cmp.sourcePackage())) {
672
+ for (const cm of cmp.conceptMapMap.values()) {
673
+ thoConceptMaps.add(cm.url);
674
+ }
675
+ }
676
+ }
677
+ for (const vp of this.valueSetProviders) {
678
+ if (vp instanceof PackageValueSetProvider && VersionUtilities.isCorePackage(vp.sourcePackage())) {
679
+ vp.excludeUrls(thoValueSets);
680
+ }
681
+ }
682
+ for (const cmp of this.conceptMapProviders) {
683
+ if (cmp instanceof PackageConceptMapProvider && VersionUtilities.isCorePackage(cmp.sourcePackage())) {
684
+ cmp.excludeUrls(thoConceptMaps);
685
+ }
686
+ }
687
+ }
688
+
613
689
  deleteCodeSystem(cs) {
614
690
  this.codeSystems.delete(cs.vurl);
615
691
  this.codeSystems.delete(cs.url);
package/tx/tx-html.js CHANGED
@@ -21,6 +21,7 @@ const {OperationOutcomeXML} = require("./xml/operationoutcome-xml");
21
21
  const {debugLog} = require("./operation-context");
22
22
  const {InvalidError} = require("./library/errors");
23
23
  const {VALID_FILTER_OPS} = require("./library/renderer");
24
+ const txOpenApi = require("./openapi");
24
25
 
25
26
  const txHtmlLog = Logger.getInstance().child({ module: 'tx-html' });
26
27
 
@@ -262,6 +263,11 @@ class TxHtmlRenderer {
262
263
  ? '<a href="' + escape(endpoint.path) + '/library" style="color: gold">Library</a> &nbsp;|&nbsp;'
263
264
  : ''
264
265
  };
266
+ // the OpenAPI description, on the endpoints it describes (R5)
267
+ if (txOpenApi.describes(endpoint.fhirVersion)) {
268
+ options.apiLink = '<a href="' + escape(endpoint.path) + '/openapi" style="color: gold">API</a> &nbsp;|&nbsp;';
269
+ options.apiHead = '<link rel="service-desc" type="application/json" href="' + escape(endpoint.path) + '/openapi.json"/>';
270
+ }
265
271
 
266
272
  return htmlServer.renderPage('tx', title, content, options);
267
273
  }