fhirsmith 0.18.0 → 0.18.2

package/ips/pipeline.js

@@ -12,10 +12,11 @@
  *   1. translate     translate CodeableConcepts that fail the terminology check to codes that pass it
  *   2. narrative     generate the narrative with the IPS presenter (presenter.js), into the analysed copy
  *   3. validation    validate the (translated) document with the FHIR validator (fhir-validator-wrapper)
- *   4. terminology   check each CodeableConcept against the value sets for international exchange
- *   5. piqi          measure the quality of the document with PIQI                        (not yet)
- *   6. profiles      check the document against each clinical profile (profiles.js)
- *   7. ai            assess the document for consistency and its terminology with an AI service (ai-client.js)
+ *   4. national      validate it against each national profile (the national IGs' profiles on Bundle)
+ *   5. terminology   check each CodeableConcept against the value sets for international exchange
+ *   6. piqi          measure the quality of the document with PIQI                        (not yet)
+ *   7. profiles      check the document against each clinical profile (profiles.js)
+ *   8. ai            assess the document for consistency and its terminology with an AI service (ai-client.js)
  *
  * Each step is { name, run(row, project, module) -> result }. A step keeps what it finds in
  * one of two places: as a result stored against the document (store.saveResult - the
@@ -122,6 +123,66 @@ const validation = {
   }
 };
 
+/**
+ * National profiles: the document is validated against each national profile - the
+ * national IG's package is loaded into the validator first (once), then the document is
+ * validated against the IG's profile on Bundle, as the validation step validates it. For
+ * each profile, the result keeps the OperationOutcome and whether the document passed: no
+ * errors (or fatal issues). A profile whose package can't be loaded, or that the validator
+ * can't validate against, is kept with the reason (pass is then null), and doesn't stop the
+ * pipeline.
+ */
+const national = {
+  name: 'national',
+  async run(row, project, module) {
+    const list = module.store.nationalProfiles();
+    const started = Date.now();
+    if (list.length === 0) {
+      module.store.saveResult(row.id, 'national', { ms: 0, profiles: [] });
+      return 'national profiles: none';
+    }
+    const v = module.validator;
+    if (!v) {
+      throw new Error('The validator is not configured (modules.ips.validator)');
+    }
+    if (!v.isRunning()) {
+      throw new Error('The validator is not running');
+    }
+    const cfg = module.config.validator || {};
+    const checkIpsCodes = cfg.checkIpsCodes !== false;
+    const doc = JSON.stringify(row.analysed || row.bundle);
+    const profiles = [];
+    for (const np of list) {
+      const entry = { id: np.id, jurisdiction: np.jurisdiction, packageId: np.packageId, version: np.version, url: np.url };
+      const t0 = Date.now();
+      try {
+        await module.loadNationalPackage(np.packageId, np.version);
+        const outcome = await v.validate(doc, { profiles: [np.url], checkIpsCodes, timeout: VALIDATE_TIMEOUT_MS });
+        if (!outcome || outcome.resourceType !== 'OperationOutcome') {
+          throw new Error('The validator did not return an OperationOutcome');
+        }
+        entry.counts = issueCounts(outcome);
+        entry.pass = !entry.counts.error && !entry.counts.fatal;
+        entry.outcome = outcome;
+      } catch (e) {
+        entry.pass = null;
+        entry.error = e.message;
+      }
+      entry.ms = Date.now() - t0;
+      profiles.push(entry);
+    }
+    module.store.saveResult(row.id, 'national', {
+      ms: Date.now() - started,
+      validatorVersion: typeof v.jarVersion === 'function' ? v.jarVersion() : null,
+      profiles
+    });
+    const passed = profiles.filter(p => p.pass === true).length;
+    const failed = profiles.filter(p => p.pass === false).length;
+    const unchecked = profiles.length - passed - failed;
+    return `national profiles: ${passed} passed, ${failed} failed` + (unchecked ? `, ${unchecked} not checked` : '');
+  }
+};
+
 // ---- the terminology check ------------------------------------------------------------
 
 /**
@@ -1003,10 +1064,10 @@ const aiStep = {
 };
 
 /** The steps, in order. Only the ones that exist yet. */
-const STEPS = [translate, narrative, validation, terminology, profilesStep, aiStep];
+const STEPS = [translate, narrative, validation, national, terminology, profilesStep, aiStep];
 
 module.exports = {
-  STEPS, translate, narrative, validation, terminology, profiles: profilesStep, ai: aiStep, checkConstraint, valueSetsIn, lookupDisplay, checkConcept, documentForAi, assessmentOf, aiSystemPrompt, AI_SYSTEM_PROMPT, checkOf, addCheck, stripChecks, translateConcept, translationOf,
+  STEPS, translate, narrative, validation, national, terminology, profiles: profilesStep, ai: aiStep, checkConstraint, valueSetsIn, lookupDisplay, checkConcept, documentForAi, assessmentOf, aiSystemPrompt, AI_SYSTEM_PROMPT, checkOf, addCheck, stripChecks, translateConcept, translationOf,
   validateCodeInValueSet, validateCodeInSystem, issueCounts, issueSummary,
   IPS_BUNDLE_PROFILE, CHECK_EXTENSION, TRANSLATION_EXTENSION, MAX_CHECKS_PER_DOCUMENT, MAX_CACHED_ANSWERS
 };

package/ips/profile-editor.js

@@ -14,6 +14,8 @@
  * the rest: a row of the second - type, system, code or value set, the rest), and
  * other rules (FHIRPath). A row's expression is made from it. Saving posts the title and the
  * constraints (key, description, expression); the server checks them, and keeps the keys.
+ * With cfg.mode 'rows' it is the profile's own page instead: the rows are the page's tables,
+ * and one at a time is added or edited, in a dialog, and saved by itself.
  */
 (function () {
   'use strict';
@@ -22,6 +24,8 @@
   var LOINC = cfg.sectionSystem;
   var dirty = false;
   var saving = false;
+  // what to draw again when a row's fields change shape: the whole editor, or the row being edited
+  var redraw = function () { draw(); };
 
   function el(tag, attrs, children) {
     var e = document.createElement(tag);
@@ -359,11 +363,13 @@
     url.hidden = select.value !== '*';
     url.addEventListener('input', function () { r.entSystem = url.value.trim(); changed(); onChange(); });
     select.addEventListener('change', function () {
-      var wasVs = r.entSystem === VS;
+      var was = r.entSystem;
+      var wasVs = was === VS;
       r.entSystem = select.value === '*' ? url.value.trim() : select.value;
       if (!select.value) { r.entCode = ''; r.entCard = ''; r.entVs = ''; }
       changed();
-      if (wasVs !== (r.entSystem === VS) || !select.value || select.value === '*') { draw(); } else { onChange(); }
+      // the code (or value set) input comes and goes with the choice
+      if (!was || wasVs !== (r.entSystem === VS) || !select.value || select.value === '*') { redraw(); } else { onChange(); }
     });
     cell.appendChild(el('div', { class: 'ips-pf-pair' }, [select, url]));
     if (r.entSystem === VS) {
@@ -414,7 +420,7 @@
       r.resSystem = select.value === '*' ? url.value.trim() : select.value;
       changed();
       // the code column becomes a value set's, or a code's
-      if (wasVs !== (r.resSystem === VS)) { draw(); } else { onChange(); }
+      if (wasVs !== (r.resSystem === VS)) { redraw(); } else { onChange(); }
     });
     cell.appendChild(select);
     cell.appendChild(url);
@@ -573,6 +579,279 @@
       .catch(function (e) { saving = false; show(['The profile was not saved: ' + e.message]); });
   }
 
+  // ---- the profile's page: a rule at a time, added or edited in a dialog ----
+
+  // what must be true of the resources a rule is about: the rest of the rule, by kind
+  var NAME_RE = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)?$/;
+  var RULE_KINDS = [
+    ['present', 'Must be present somewhere'],
+    ['subject', 'Patient must match the Document'],
+    ['element', 'Must have an element'],
+    ['conforms', 'Conform to a profile'],
+    ['category', 'Has a category'],
+    ['other', 'Something else (FHIRPath)']
+  ];
+  function allOf(body) { return new RegExp('^\\.\\s*(?:' + body + '|all\\s*\\(\\s*' + body + '\\s*\\))$'); }
+  var CONFORMS_RE = allOf('conformsTo\\s*\\(\\s*' + STR + '\\s*\\)');
+  var CATEGORY_RE = allOf('category\\s*\\.\\s*hasCoding\\s*\\(\\s*' + STR + '\\s*,\\s*' + STR + '\\s*(?:,\\s*' + STR + '\\s*)?\\)');
+
+  /** the rule's kind, and its fields, from the rest of a rule about resources */
+  function ruleFields(r) {
+    var rest = (r.resRest || '').trim();
+    var m;
+    r.ruleKind = 'other';
+    r.ruleOther = rest;
+    r.ruleUrl = ''; r.ruleSystem = cfg.categorySystem || ''; r.ruleCode = ''; r.ruleVersion = ''; r.rulePath = ''; r.ruleDisplay = '';
+    r.ruleAll = true;
+    if (/^\.\s*exists\s*\(\s*\)$/.test(rest)) {
+      r.ruleKind = 'present';
+    } else if (/^\.\s*all\s*\(\s*sameSubject\s*\(\s*\)\s*\)$/.test(rest)) {
+      r.ruleKind = 'subject';
+    } else if ((m = CONFORMS_RE.exec(rest))) {
+      r.ruleKind = 'conforms';
+      r.ruleAll = m[1] === undefined;
+      r.ruleUrl = unquote(m[1] !== undefined ? m[1] : m[2]);
+    } else if ((m = CATEGORY_RE.exec(rest))) {
+      r.ruleKind = 'category';
+      r.ruleAll = m[1] === undefined;
+      var g = m[1] !== undefined ? [m[1], m[2], m[3]] : [m[4], m[5], m[6]];
+      r.ruleSystem = unquote(g[0]); r.ruleCode = unquote(g[1]); r.ruleVersion = g[2] !== undefined ? unquote(g[2]) : '';
+    } else if ((m = /^\.\s*([A-Za-z][A-Za-z0-9_]*(?:\s*\.\s*[A-Za-z][A-Za-z0-9_]*)?)\s*\.\s*exists\s*\(\s*\)$/.exec(rest))) {
+      r.ruleKind = 'element';
+      r.rulePath = m[1].replace(/\s+/g, '');
+    }
+  }
+  /** the rest of a rule about resources, from its kind and fields, or null with what is wrong */
+  function ruleRest(r) {
+    var each = function (body) { return r.ruleAll ? '.all(' + body + ')' : '.' + body; };
+    switch (r.ruleKind) {
+      case 'present': return { rest: '.exists()', problems: [] };
+      case 'subject': return { rest: '.all(sameSubject())', problems: [] };
+      case 'element': return NAME_RE.test(r.rulePath.trim()) ? { rest: '.' + r.rulePath.trim() + '.exists()', problems: [] } : { rest: null, problems: ['rulePath'] };
+      case 'conforms': return CANONICAL_RE.test(r.ruleUrl.trim()) ? { rest: each('conformsTo(' + quote(r.ruleUrl.trim()) + ')'), problems: [] } : { rest: null, problems: ['ruleUrl'] };
+      case 'category': {
+        var problems = [];
+        if (!r.ruleSystem.trim()) { problems.push('ruleSystem'); }
+        if (!r.ruleCode.trim()) { problems.push('ruleCode'); }
+        if (problems.length) { return { rest: null, problems: problems }; }
+        return { rest: each('category.hasCoding(' + quote(r.ruleSystem.trim()) + ', ' + quote(r.ruleCode.trim()) + (r.ruleVersion.trim() ? ', ' + quote(r.ruleVersion.trim()) : '') + ')'), problems: [] };
+      }
+      default: {
+        var rest = (r.ruleOther || '').trim();
+        return rest && rest !== '.' ? { rest: rest.charAt(0) === '.' ? rest : '.' + rest, problems: [] } : { rest: null, problems: ['ruleOther'] };
+      }
+    }
+  }
+  /** the expression of a row in the dialog, or null with what is wrong */
+  function dialogExpression(r) {
+    if (r.mode !== 'resource') { return rowExpression(r); }
+    var t = ruleRest(r);
+    r.resRest = t.rest || '';
+    var e = resourceExpression(r);
+    return { expression: t.rest ? e.expression : null, problems: t.problems.concat(e.problems.filter(function (p) { return p !== 'resRest'; })) };
+  }
+
+  function rowsMode() {
+    var MODE = { section: 'section', resource: 'resource', other: 'text' };
+    var TITLES = { section: 'a required section or entry', resource: 'a rule about resources', text: 'a rule' };
+    var byKey = {};
+    (cfg.profile.constraints || []).forEach(function (c) { byKey[c.key] = c; });
+    var dialog = el('dialog', { class: 'ips-pf-dialog', 'aria-labelledby': 'ips-pf-dialog-title' });
+    document.body.appendChild(dialog);
+    var editing = null;
+
+    function showIn(box, problems, kind) {
+      box.innerHTML = '';
+      if (!problems.length) { return; }
+      var alert = el('div', { class: 'alert alert-' + (kind || 'danger'), style: 'margin: 0' });
+      if (problems.length === 1) { alert.textContent = problems[0]; } else {
+        alert.appendChild(el('ul', { style: 'margin: 0' }, problems.map(function (p) { return el('li', { text: p }); })));
+      }
+      box.appendChild(alert);
+    }
+    // a labelled part of the dialog: a label, what goes in it, and a hint
+    function field(label, controls, hint) {
+      return el('div', { class: 'ips-pf-field' }, [el('label', { class: 'ips-pf-label', text: label })].concat(controls).concat(hint ? [el('div', { class: 'ips-pf-hint', text: hint })] : []));
+    }
+    function howMany(r, fieldName, update, fields) {
+      var input = cardInput(r, fieldName, update);
+      fields[fieldName] = input;
+      return el('div', { class: 'ips-pf-pair ips-pf-how' }, [el('span', { text: 'How many' }), input,
+        el('span', { class: 'ips-pf-hint', text: 'blank: at least one; or min..max - 1..1, 0..1, 1..*' })]);
+    }
+    // a code system for the category: one of the named ones, or another by URL
+    function categorySystem(r, update) {
+      var cell = el('div', { class: 'ips-pf-pair' });
+      var select = el('select', { class: 'form-control ips-ed-input' });
+      cfg.systems.forEach(function (s) { select.appendChild(el('option', { value: s.url, text: s.name })); });
+      (cfg.categorySystems || []).forEach(function (s) { select.appendChild(el('option', { value: s.url, text: s.name })); });
+      select.appendChild(el('option', { value: '*', text: 'Another system...' }));
+      var known = Array.prototype.some.call(select.options, function (o) { return o.value === r.ruleSystem; });
+      select.value = known ? r.ruleSystem : '*';
+      var url = el('input', { type: 'text', class: 'form-control ips-ed-input', placeholder: 'code system URL' });
+      url.value = known ? '' : r.ruleSystem;
+      url.hidden = known;
+      url.addEventListener('input', function () { r.ruleSystem = url.value.trim(); changed(); update(); });
+      select.addEventListener('change', function () {
+        url.hidden = select.value !== '*';
+        r.ruleSystem = select.value === '*' ? url.value.trim() : select.value;
+        changed();
+        update();
+      });
+      cell.appendChild(select);
+      cell.appendChild(url);
+      cell.url = url;
+      return cell;
+    }
+
+    /** the dialog's contents, (re)drawn for the row being edited */
+    function drawDialog() {
+      var e = editing;
+      var r = e.r;
+      dialog.innerHTML = '';
+      var fields = {};
+      var exprLine = el('div', { class: 'ips-pf-expr' });
+      var update = function () {
+        var t = dialogExpression(r);
+        exprLine.textContent = r.mode === 'text' ? '' : (t.expression || '(incomplete - the fields in red)');
+        Object.keys(fields).forEach(function (k) { fields[k].classList.toggle('ips-pf-bad', t.problems.indexOf(k) >= 0); });
+      };
+      var body = el('div', { class: 'ips-pf-dialog-body' });
+      var human = el('textarea', { class: 'form-control', rows: 2, placeholder: 'e.g. A problem list, with the patient\'s hypertension' });
+      human.value = r.human;
+      human.addEventListener('input', function () { r.human = human.value; changed(); });
+      body.appendChild(field('Expectation', [human], 'What is expected, as people will read it.'));
+
+      if (r.mode === 'section') {
+        body.appendChild(field('Section', [sectionCell(r, update), howMany(r, 'secCard', update, fields)]));
+        var ent = entryCell(r, update);
+        if (ent.code) { fields.entCode = ent.code.input; }
+        if (ent.vs) { fields.entVs = ent.vs.input; }
+        body.appendChild(field('Entries', [ent].concat(r.entSystem ? [howMany(r, 'entCard', update, fields)] : []),
+          'Optionally, entries the section must have: with a code in a code system, or a code in a value set.'));
+      } else if (r.mode === 'resource') {
+        var type = typeCell(r, update);
+        var system = systemCell(r, update);
+        var byVs = r.resSystem === VS;
+        var code = byVs ? vsInput(r, 'resVs', 'resVsTitle', update) : codeInput(r, 'resCode', 'resDisplay', function () { return r.resSystem; }, update);
+        fields.resType = type.other;
+        fields.resSystem = system.url;
+        fields[byVs ? 'resVs' : 'resCode'] = code.input;
+        body.appendChild(field('Resources', [type], 'The type of resource, or any.'));
+        body.appendChild(field('With a code', [system, code], 'Anywhere in the document, whatever section they are in.'));
+        var kind = el('select', { class: 'form-control ips-ed-input' });
+        RULE_KINDS.forEach(function (k) { kind.appendChild(el('option', { value: k[0], text: k[1] })); });
+        kind.value = r.ruleKind;
+        kind.addEventListener('change', function () { r.ruleKind = kind.value; changed(); drawDialog(); });
+        var more = [];
+        if (r.ruleKind === 'element') {
+          var path = el('input', { type: 'text', class: 'form-control ips-ed-input', placeholder: 'e.g. onset, or code.text' });
+          path.value = r.rulePath;
+          path.addEventListener('input', function () { r.rulePath = path.value; changed(); update(); });
+          fields.rulePath = path;
+          more.push(field('Element', [path], 'An element of the resources, or an element of one of their elements (one dot, no deeper).'));
+        } else if (r.ruleKind === 'conforms') {
+          var url = el('input', { type: 'text', class: 'form-control ips-ed-input', placeholder: 'the profile\'s canonical URL' });
+          url.value = r.ruleUrl;
+          url.addEventListener('input', function () { r.ruleUrl = url.value; changed(); update(); });
+          fields.ruleUrl = url;
+          more.push(field('Profile', [url], 'Each of the resources must conform to it. It can be one of the clinical profiles, or a profile the validator has loaded.'));
+        } else if (r.ruleKind === 'category') {
+          var csys = categorySystem(r, update);
+          var ccode = codeInput(r, 'ruleCode', 'ruleDisplay', function () { return r.ruleSystem; }, update);
+          var version = el('input', { type: 'text', class: 'form-control ips-ed-input', placeholder: 'version (optional)' });
+          version.value = r.ruleVersion;
+          version.addEventListener('input', function () { r.ruleVersion = version.value; changed(); update(); });
+          fields.ruleSystem = csys.url;
+          fields.ruleCode = ccode.input;
+          more.push(field('Category', [csys, ccode, version], 'Each of the resources must have a category with this code.'));
+        } else if (r.ruleKind === 'other') {
+          var other = el('textarea', { class: 'form-control ips-ed-input', rows: 3, placeholder: '.count() = 1', style: 'font-family: monospace' });
+          other.value = r.ruleOther;
+          other.addEventListener('input', function () { r.ruleOther = other.value; changed(); update(); });
+          fields.ruleOther = other;
+          more.push(field('FHIRPath', [other], 'FHIRPath on the resources found, starting with a dot.'));
+        }
+        body.appendChild(field('What must be true', [kind].concat(more)));
+      } else {
+        var text = el('textarea', { class: 'form-control ips-ed-input', rows: 5, placeholder: 'A FHIRPath expression on the document (the Bundle), true when it meets the expectation', style: 'font-family: monospace' });
+        text.value = r.expression;
+        text.addEventListener('input', function () { r.expression = text.value; changed(); });
+        body.appendChild(field('FHIRPath', [text], 'Evaluated on the document (the Bundle): the rule is met when it is true.'));
+      }
+      if (r.mode !== 'text') { body.appendChild(field('As FHIRPath', [exprLine])); }
+      body.appendChild(e.msg);
+
+      var save = el('button', { type: 'button', class: 'btn btn-primary', text: 'Save', onclick: function () { saveRow(); } });
+      var cancel = el('button', { type: 'button', class: 'btn btn-default', text: 'Cancel', onclick: function () { stop(false); } });
+      e.save = save;
+      dialog.appendChild(el('div', { class: 'ips-pf-dialog-head' }, [
+        el('h4', { id: 'ips-pf-dialog-title', text: (r.key ? 'Edit ' : 'Add ') + TITLES[r.mode] }),
+        el('button', { type: 'button', class: 'ips-pf-dialog-x', 'aria-label': 'Close', text: '×', onclick: function () { stop(false); } })
+      ]));
+      dialog.appendChild(body);
+      dialog.appendChild(el('div', { class: 'ips-pf-dialog-foot' }, [cancel, ' ', save]));
+      update();
+      if (!e.focused) { e.focused = true; human.focus(); }
+    }
+
+    function start(r) {
+      if (editing) { return; }
+      if (r.mode === 'resource') { ruleFields(r); }
+      editing = { r: r, msg: el('div', { class: 'ips-pf-messages' }) };
+      dirty = false;
+      drawDialog();
+      dialog.showModal();
+    }
+    // close the dialog: when there are changes, only if the user says so (unless saved)
+    function stop(saved) {
+      if (!editing) { return; }
+      if (!saved && dirty && !window.confirm('Discard your changes to this rule?')) { return; }
+      editing = null;
+      dirty = false;
+      dialog.close();
+    }
+    dialog.addEventListener('cancel', function (ev) { ev.preventDefault(); stop(false); });
+
+    function saveRow() {
+      var e = editing;
+      if (!e || saving) { return; }
+      var t = dialogExpression(e.r);
+      if (!t.expression && e.r.mode !== 'text') { showIn(e.msg, ['The rule is incomplete (the fields in red)']); return; }
+      saving = true;
+      e.save.disabled = true;
+      showIn(e.msg, ['Saving...'], 'info');
+      var url = cfg.urls.constraint + (e.r.key ? '/' + encodeURIComponent(e.r.key) : '');
+      fetch(url, { method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({ human: e.r.human, expression: t.expression || '', _csrf: cfg.csrf }) })
+        .then(function (res) {
+          return res.json().then(function (j) { return { ok: res.ok, j: j }; }, function () { return { ok: false, j: { problems: ['The server answered ' + res.status + (res.status === 403 ? ' (has your session expired? reload the page)' : '')] } }; });
+        })
+        .then(function (a) {
+          saving = false;
+          if (a.ok) { stop(true); location.reload(); return; }
+          e.save.disabled = false;
+          showIn(e.msg, a.j.problems || ['The rule was not saved']);
+        })
+        .catch(function (x) { saving = false; e.save.disabled = false; showIn(e.msg, ['The rule was not saved: ' + x.message]); });
+    }
+
+    redraw = drawDialog;
+    Array.prototype.forEach.call(document.querySelectorAll('.ips-pf-edit'), function (b) {
+      b.addEventListener('click', function () {
+        var c = byKey[b.closest('tr').getAttribute('data-key')];
+        if (c) { start(rowFrom(c)); }
+      });
+    });
+    Array.prototype.forEach.call(document.querySelectorAll('.ips-pf-add'), function (b) {
+      b.addEventListener('click', function () {
+        var r = rowFrom({});
+        r.mode = MODE[b.getAttribute('data-part')];
+        start(r);
+      });
+    });
+  }
+
   window.addEventListener('beforeunload', function (e) { if (dirty) { e.preventDefault(); e.returnValue = ''; } });
-  draw();
+  if (cfg.mode === 'rows') { rowsMode(); } else { draw(); }
 })();

package/ips/readme.md

@@ -37,7 +37,9 @@ network. Without it there are no links and no analysis.
 
 `/ips` lists the projects. The administrator logs in at `/ips/login` and, at
 `/ips/admin/projects` and `/ips/admin/users`, creates and deletes projects and users, and
-says which users manage which projects. A project has a code - 2-32 lower case letters,
+says which users manage which projects. The administrator also looks after the
+[clinical profiles](#clinical-profiles) and the [national profiles](#national-profiles),
+which apply across all projects. A project has a code - 2-32 lower case letters,
 digits and hyphens, fixed once it exists - and lives at `/ips/{code}`. Deleting a project
 deletes its documents.
 
@@ -156,9 +158,9 @@ it (`ips/pipeline.js`), and marks it `processed` with the steps' notes, or `erro
 message of the step that failed. Each step's own state (`waiting`, `running`, `done` or
 `failed`, with its note or error) is kept in its result row as it goes, which is what the
 document page's step line shows; processing again clears every step's result first. The pipeline, in order, will be: **translate** CodeableConcepts
-to the international terminologies; generate the **narrative**; **validate** the document;
-measure its quality with PIQI; check it against the **clinical profiles**; **assess** it with AI. Translation, the narrative,
-validation, the **terminology check**, the clinical profiles check and the AI assessment exist so far (PIQI does not). A step keeps what it finds in one of two places: as a result stored against the
+to the international terminologies; generate the **narrative**; **validate** the document; validate it against the
+**national profiles**; measure its quality with PIQI; check it against the **clinical profiles**; **assess** it with AI. Translation, the narrative,
+validation, the national profiles, the **terminology check**, the clinical profiles check and the AI assessment exist so far (PIQI does not). A step keeps what it finds in one of two places: as a result stored against the
 document in `document_results` (one row per step - the validation outcome), or in the
 **analysed copy** - a second copy of the document (`documents.analysed_json`) that the steps
 adorn with extensions, so that the master document is never changed. The analysed copy is
@@ -236,7 +238,12 @@ view shows it.
 `modules.ips.validator` configures a FHIR validator service, exactly as the SHL module's
 does (`fhir-validator-wrapper`: the validator CLI jar in the data folder's `bin` directory,
 run as a service on its own `port`, with `txServer` - tx.fhir.org, by default - and the IPS
-package loaded). It starts in the background when the module does, and the queue waits for
+package loaded). `jar` names a validator jar of its own instead - a validator built locally from
+org.hl7.fhir.core, say: absolute, or relative to the data folder (`bin/local/validator_cli.jar`) - which
+is used as it is, never downloaded or updated. Keep such a jar out of `bin/validator_cli.jar`: the
+wrapper takes that jar's version from the `.version` file it wrote when it downloaded the release
+there, so a different jar in its place is started as if it were that release (and is replaced by
+the next one). It starts in the background when the module does, and the queue waits for
 it. Each document - its analysed copy, so the translations are seen (the validator will
 remark on the translation extension until it is given its definition) - is validated against the IPS Bundle profile
 (`http://hl7.org/fhir/uv/ips/StructureDefinition/Bundle-uv-ips`; set `profiles` to validate
@@ -246,6 +253,23 @@ its `validation` view: the counts, each issue's severity, code, location and mes
 the raw OperationOutcome. Without a configured, running validator the step fails, and the
 document's status is `error`.
 
+### National profile validation
+
+The national step runs after validation. It validates the document (the analysed copy, as validation does) against each
+[national profile](#national-profiles) in turn: the national IG's package is loaded into the validator (once - a package
+that has loaded, or has failed to, is remembered until the national profiles are changed), then the document is
+validated against the IG's profile on Bundle, with the same `checkIpsCodes` setting. For each profile the result keeps
+the OperationOutcome, its counts, and whether the document passed - it passes when the validator reports no errors (or
+fatal issues). A profile whose package can't be loaded, or that the validator can't validate against, is kept with the
+reason and counts as not checked; it doesn't stop the pipeline. With no national profiles there is nothing to do, and no
+validator is needed; with some, the step fails, as validation does, without a configured, running validator.
+
+The document's **National Profiles** view lists the profiles as they were when the document was processed, with the
+outcome (passed, failed, or not checked) and the issue counts for each; a profile's page shows its validation as the
+validation view shows the base validation (`?view=national&np={n}`). The packages loaded for national profiles stay
+loaded in the validator alongside its own (`packages`), so two national IGs that define the same things differently can
+affect each other.
+
 ### Terminology check
 
 After validation, every CodeableConcept the terminology view lists is checked for its
@@ -403,12 +427,31 @@ The editor (`/ips/StructureDefinition/new`, or Edit on a profile) is in three pa
 - **Rules about resources:** the third shape, each a row of a table with four columns (the type, which is optional, the system, the code, and the rest of the rule as FHIRPath starting with a dot).
 - **Other rules:** any other FHIRPath.
 
+The page that shows a profile is the same for everyone. Its first part is a table of three columns: the **Expectation** (the description), the **Section** (an IPS section by its title, or `system|code`) and the **Entry** (`Code is system|code`, or `Code is in` a value set, by its title, or its URL when the title isn't known). A code system is shown by name when it is a known one. A cardinality, `[m..n]`, follows a section or an entry unless it is `1..1` or not given (none means at least one). The second part is also a table of three columns: the **Expectation**, the **Resource Set** (the type, as `MedicationAdministrations where` or `Any resource where`, then the code as in the Entry column) and the **Rule**, which is the rest of the expression in words where it is one of these: `.exists()` is "Must be present somewhere"; `.all(sameSubject())` is "Patient must match the Document"; `.x.exists()` and `.x.y.exists()` are "Must have an x" and "Must have an x.y" (no deeper); `.conformsTo(url)` (or `.all(conformsTo(url))`) is "Conform to" the profile, named by its title when it is one of the clinical profiles or by its jurisdiction and package when it is a national profile; and `.category.hasCoding(system, code [, version])` (or inside `.all()`) is "Has category system|code". Any other rest is shown as FHIRPath, and so are the other rules. On the same page the administrator edits the rules one at a time: each row has Edit and Delete, and each part has an Add button. Add and Edit open a dialog for the one rule - the expectation, then the parts of the rule, each with what it means (for a rule about resources, what must be true of them is a choice: present somewhere, the patient matches the document's, an element, conformance to a profile, a category, or other FHIRPath), and the FHIRPath it makes - and Save stores that one rule by itself (`POST /ips/StructureDefinition/{id}/constraint` to add, `.../constraint/{key}` to change, `.../constraint/{key}/delete` to delete). An edited rule keeps its key. The full editor is still there (Edit all), for the title, or for many changes at once.
+
 A rule moves between the parts when it is switched between table and FHIRPath, and it lands in the part whose shape it fits. A section is one of the IPS sections, or any code in any system. An entry or resource code is a code in a named code system (SNOMED CT, LOINC, ICD-10...) or in any other given by URL, and it is looked up on the terminology server (`GET /ips/lookup?system=&q=`, for the administrator only). Choosing "In a value set..." as the system matches entries or resources by value set instead. The code box becomes a value set search (`GET /ips/lookup-vs?q=`, for the administrator only): this module's own value sets that match the title come first, then the terminology server's (a `ValueSet?title=` search). A suggestion shows its title, with its URL underneath. A canonical can also be typed or pasted in, with `|version` to pin a version. When the editor opens, it looks up the title of each value set by URL (`?url=`). If the terminology server doesn't know a value set, it says so as a warning, not an error: the value set has to be known when documents are checked, not when the profile is saved. A cardinality is blank (no bounds) or `min..max`, where max may be `*`. Before a profile is saved, every expression is parsed and run once against an empty document. That catches unknown functions and wrong numbers of arguments as well as syntax errors.
 
 A profile can be downloaded as JSON (`?download=1`), and a downloaded profile can be uploaded again as a new profile, with a new id, url and keys. An upload must be no more than a profile like this: a profile on Bundle with no snapshot, and one differential element (the root) carrying constraints that have only a key, an `error` severity, a description, an expression and a source. Anything more is rejected, with the reasons. A profile downloaded when clinical profiles were on Composition is accepted and moved onto Bundle, as profiles already stored are when the server starts: `Composition.section(...)` becomes `Bundle.section(...)`, and any other `Composition.x` becomes `Bundle.entry.resource.ofType(Composition).x`.
 
 As FHIR: `GET /ips/StructureDefinition` is a searchset of them all, and `GET /ips/StructureDefinition/{id}` is one of them.
 
+## National profiles
+
+A national profile is the profile a national implementation guide defines for an IPS document. Each has four parts:
+the jurisdiction it is for, the IG's package id (e.g. `hl7.fhir.au.ips`), the package version, and the canonical URL
+of the IG's profile on Bundle. National profiles are shared across all projects (`/ips/national-profiles`). Everyone can see them; only the
+administrator adds, edits and deletes them. There is at most one for a package id and version. Every document is
+validated against each of them by the [national profiles step](#national-profile-validation).
+
+The jurisdiction is a code from `http://hl7.org/fhir/ValueSet/jurisdiction`: a country, by its ISO 3166 two-letter
+code (`AU`; lower case is accepted, and stored in upper case), or a region, by its UN M49 three-digit code (`150` for
+Europe, `053` for Australia and New Zealand). The pages show the country's or region's name with it, from the code
+lists the terminology module holds (`tx/cs/cs-country.js`, `tx/cs/cs-areacode.js`); ISO's user-assigned and 'unknown' codes
+(`XK`, `XX`, `ZZ`...) and countries' M49 numeric codes aren't accepted. National profiles made before the jurisdiction was asked
+for show it as not given, until they are saved with one. The package id must be a FHIR package id (lower case letters, digits, `-` and `_`, in two or more parts separated by
+dots), the version a package version (`1.0.0`, `1.1.0-ballot`), and the profile an http or https URL. `GET
+/ips/national-profiles` with `Accept: application/json` returns them as `[{jurisdiction, packageId, version, url}]`.
+
 ## FHIRPath functions
 
 `ips/fhirpath-ips.js` adds two functions to fhirpath.js, for expressions on IPS documents: