fhirsmith 0.18.1 → 1.0.0

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.
 
@@ -98,14 +100,42 @@ documentation section with the endpoint's URL, the CapabilityStatement link and
 the requests it answers - and `/ips/{code}/Bundle/{id}` shows the document.
 The document page's header names the patient, the document's date, when and how it was
 received and its size, with links to the FHIR JSON and to download it (`?download=1`, sent
-as an attachment named `ips-{code}-{id}.json`). Below it, each processing step is shown
-with where it is (tick: done, cross: failed, gear: running, moon: waiting - the step's note,
-or for managers the reason it failed, on hover), and managers get "Process again" and
-"Delete" buttons. The views of a document are tabs, chosen with `?view=`: `narrative` (the
-default - the Composition's narrative followed by each section's, with the section titles),
-`translation` (what the translate step did with each concept, below), `generated` (the
-narrative this server generates, below), `validation` (below), `terminology`, `ai` (the AI assessment, below) and `json`
-(pretty-printed, monospaced).
+as an attachment named `ips-{code}-{id}.json`). Below it, the processing pipeline is shown
+as one connected line: Received, then each step in the order it runs, coloured by where it
+is (tick: done, cross: failed, gear: running, moon: waiting - the step's note, or for
+managers the reason it failed, on hover); each step links to the view that shows its work.
+Managers get "Process again" and "Delete" buttons. The views of a document are tabs, chosen
+with `?view=`: `narrative` (the default; a switch, `&narrative=generated`, chooses between
+the narrative as provided - the Composition's narrative followed by each section's, with
+the section titles - and the narrative this server generates, below), `structure` (the
+document's logical structure, below), `analysis` (what the analysis step found, below), `translation` (what
+the translate step did with each concept, below), `terminology`, `validation` (below),
+`national` (below), `profiles` (the clinical profile checks), `ai` (the AI assessment,
+below) and `source` (the JSON, pretty-printed, monospaced). The old view names `generated`
+and `json` still work. The actions (Edit, the Share buttons, and for managers Process again
+and Delete) are on a line of their own below the pipeline.
+`structure` shows the document as a tree table, in the style of the FHIR specification's
+structure tables: columns Path, Type, Id and Details, with the tree drawn in the Path column
+(each node expands and collapses; Expand all and Collapse all buttons; without scripts
+every row shows). It starts at the Composition: first what the Composition refers to other
+than its sections (subject, author, custodian, attesters, ...), then the sections, nested,
+each with what it refers to (its entries, author, focus). Each reference's path is where it
+is (`entry[0]`, `attester[0].party`), and the reference as given is on hover over the Id;
+each resource expands into the references it makes, and so on (sections start open,
+resources closed). A reference resolves as in a Bundle - by fullUrl, absolute or relative
+to the referring entry's - and `#id` is a resource contained in the referring resource (or
+in the resource that contains it). One that doesn't resolve is shown as external (not in
+document). A resource is expanded once, at the shallowest place it is referred to (so one
+the Composition refers to directly expands there, not inside the subject that also refers to
+it); everywhere else it is shown again, greyed, saying where it is expanded, but doesn't
+expand a second time. Details says what the resource is - a name (a person's, an organization's),
+else its code (`code`, the medication - following `medicationReference` -, `vaccineCode`,
+`type`...), with an Observation's value - and when: the first of the clinical dates (onset,
+occurrence, performed, effective, ...), falling back to the record's own (`recorded`,
+`issued`, `date`, `meta.lastUpdated`). Icons, from `static/assets/images`: the document,
+sections, people (Patient, Practitioner, PractitionerRole, RelatedPerson), organizations,
+medications (Medication and the Medication* resources), other clinical resources, Provenance
+and AuditEvent, references outside the document, and anything else.
 `terminology` lists every CodeableConcept in the document (`ips/terminology.js`): the
 Composition's own, then each section's entries in the IPS section order (Patient Story,
 Problems, Allergies, Medications, ... Results; sections not in that list after, in document
@@ -155,10 +185,10 @@ takes submitted documents in turn, marks each `processing`, runs the pipeline's
 it (`ips/pipeline.js`), and marks it `processed` with the steps' notes, or `error` with the
 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
+document page's step line shows; processing again clears every step's result first. The pipeline, in order, will be: determine the document's **nationality**; **analyse** each resource; **translate** CodeableConcepts
+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 analysis, 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
@@ -166,16 +196,85 @@ rebuilt from the master on every run, so a document can always be processed agai
 Anything left `processing` when the server stopped is queued again at startup. Managers can
 queue a document again from its page, though not while it is being processed.
 
+### Nationality
+
+The first step (`ips/nationality.js`) works out which nation the document is from, as far as the document says -
+few national IGs give a way to tell, so this is a short list of signs, to grow as more are found:
+
+- **US**: the Bundle claims the US Patient Summary profile (`http://hl7.org/fhir/us/pcs/StructureDefinition/Bundle-us-pcs`),
+  or a US Core extension (`http://hl7.org/fhir/us/core/StructureDefinition/...`) is used anywhere in the document;
+- **AU**: the Bundle claims the AU Patient Summary profile (`http://hl7.org.au/fhir/ps/StructureDefinition/au-ps-bundle`).
+
+The nation is its ISO 3166 two-letter code, or unknown when nothing points to a nation, or the signs point to more
+than one. It is kept as the step's result (with the reasons) and in `documents.nationality`, for the list: the
+project page has a Nation column (the code, or `??`), the document page shows the nation's flag to the left of the
+banner (a black and white globe when it isn't known, or there is no flag for it yet -
+`static/assets/images/flags/{code}.svg`), and the first bullet on the Composition in the analysis view says what was
+decided, and why.
+
+### Analysis
+
+The first step (`ips/analysis.js`), over the document as submitted. It walks the same tree
+as the structure view (`ips/structure.js`) and, for each resource there (once, where it is
+first met; contained resources too) and for the Composition section by section (the
+Composition itself without its sections), keeps a list of findings, by the node's key
+(`e{n}` for entry n, `e{n}#id` for a contained resource, `s:{path}` for a section):
+
+- every extension, at any depth (a primitive's extensions are at the primitive's path; an
+  extension's own parts are not listed), with its definition when the module can find one
+  - the validator is asked (fhir-validator-wrapper's `lookupCanonical()`, the service's
+  `/canonical`, which answers from the validator's context; with `autoLoadPackages`, on by
+  default, the validator finds, downloads and loads the package that defines an extension it
+  doesn't have, as it does while validating), and the answers are cached - or a note that it
+  couldn't be found;
+  modifier extensions likewise, in maroon; `textLink` extensions are left out;
+- `implicitRules`, in maroon;
+- in navy: `active` = false; a status of `entered-in-error` (and a Condition's or
+  AllergyIntolerance's `verificationStatus` of entered-in-error); a status of `unknown`; or no
+  status where the resource requires one (`lifecycleStatus` for a Goal);
+- in dark green: a `subject` (or `patient`) that isn't the document's - not the same
+  resource in the document, nor the same reference, nor the same identifier - and any `focus`;
+- dates in the future, where one isn't expected. Only elements the (R4) type model says are
+  dates (date, dateTime, instant) are looked at - so not an identifier or a note that looks
+  like a date - and not inside extensions. Some dates are about the future by their nature and
+  are never mentioned: the end of a period (a name's, address's or identifier's validity, a
+  prescription's), expiry dates, due dates, and schedules (Timing). Some resources may have
+  future dates: Appointment, AppointmentResponse, ImmunizationRecommendation, Schedule and
+  Slot always; requests and plans (ServiceRequest, MedicationRequest, DeviceRequest,
+  NutritionOrder, CommunicationRequest, SupplyRequest, VisionPrescription, CarePlan, Task, and
+  a Goal by its lifecycleStatus) until they are over (completed, revoked, cancelled,
+  entered-in-error, stopped, failed or rejected); and events still to come - a Procedure in
+  preparation, a planned Encounter, an intended MedicationStatement or DeviceUseStatement. A
+  date with no time zone is in the future only if it is everywhere;
+- a Patient's `link`s; a Composition whose status isn't `final`;
+- for a section: its `emptyReason`, and an author other than that of what contains it (the
+  Composition, or the containing section - which may have inherited its own);
+- whether there is narrative.
+
+With nothing but the narrative to say, a resource is "All OK". The `analysis` view shows the
+structure as a flat table - each node's row as in the structure view but with its full path
+(`Composition.section[0].entry[0].resolve().subject`) - with a row under each that lists the
+findings; a resource already shown is "Analysed above", and a reference to a resource not
+in the document has no rows at all.
+
 ### Translation
 
-The first step. Every CodeableConcept the terminology view lists is checked as the
+The second step. Every CodeableConcept the terminology view lists is checked as the
 terminology check (below) checks it; one that fails - no coding in the element's value set,
 or, for an element with no value set of its own, no international coding - is sent to the
 terminology server to translate: `ConceptMap/$translate` with `sourceCodeableConcept` (the
 concept as submitted) and `targetScope` (the element's value set, or the fallback), the
-value set and what it draws on as `tx-resource`. The server chooses the concept maps. Every
+value set and what it draws on as `tx-resource`. A SNOMED CT coding with no version is sent as a code of
+the edition of the document's nation: when the [nationality](#nationality) step found one, and a national profile
+for that nation names a SNOMED CT edition, the coding goes with `version` = `http://snomed.info/sct/{edition}`
+(the document is not changed, and the translation view says which edition was used). Which edition a code is
+from decides which maps apply - a national edition's own concepts translate to the International Edition. The
+terminology check does not do this: it takes the codes as they are, so a SNOMED CT code with no version passes if
+it is fine as it is, and one whose version names another edition does not. The server chooses the concept maps. Every
 match that comes back (whatever its relationship) is added to the concept in the analysed
-copy as a Coding, unless the concept already has that system and code, with an extension
+copy as a Coding, unless the concept already has that coding - the same system and code, and the same version
+when both give one (SNOMED CT versions compared by edition: the same code in the International Edition is a
+different coding from the one in a national edition, and is what the translation is for) - with an extension
 saying where it came from:
 `http://healthintersections.com.au/fhirsmith/StructureDefinition/ips-translation`, with
 `server` (the terminology server, as configured), `conceptMap` (the match's `originMap`, when
@@ -236,16 +335,42 @@ 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 (the wrapper reads its version from the jar, so it
+is only given the options it knows). Keep such a jar out of `bin/validator_cli.jar`: the wrapper
+keeps that one up to date, so a different jar in its place is replaced by the next release. `autoLoadPackages` (default true) starts the validator with `-autoLoadPackages`, so
+the analysis step's extension lookups can load the package that defines an extension (validator
+7.0.5 and `fhir-validator-wrapper` 1.7.0 or later; older ones just don't look further). 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
-against something else) with the validator's IPS code checks on (`checkIpsCodes`), and the
-OperationOutcome is stored with the document and shown on
+against something else) - validator 7.0.4 dropped its IPS code checks, so `checkIpsCodes` is no longer
+sent (the validator refuses it) - and the OperationOutcome is stored with the document and shown on
 its `validation` view: the counts, each issue's severity, code, location and message, and
 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. The national profiles' packages are also loaded when the validator
+starts (and when the national profiles are changed), before any document is processed, so that the analysis step -
+which runs first - finds the extensions they define; an extension that couldn't be found is looked up again once a
+package has loaded. 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 +528,36 @@ 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 five parts:
+the jurisdiction it is for, the IG's package id (e.g. `hl7.fhir.au.ips`), the package version, the canonical URL
+of the IG's profile on Bundle, and - optionally, since not every IG uses SNOMED CT - the SNOMED CT edition the IG takes for granted. 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, snomedEdition}]`
+(`snomedEdition` only when there is one).
+
+The SNOMED CT edition is chosen from a list - the editions in `SNOMED_LINKABLE_EDITIONS` (`tx/sct/editions.js`, the
+editions snomed.info can link to), by name - and kept as the edition's module id (`900000000000207008` for the
+International Edition, `32506021000036107` for the Australian), the id in its edition URI `http://snomed.info/sct/{id}`.
+
 ## FHIRPath functions
 
 `ips/fhirpath-ips.js` adds two functions to fhirpath.js, for expressions on IPS documents:
@@ -455,6 +604,7 @@ shared this way. The QR codes are made with `qrcode-generator`, error correction
 ### Validation view
 
 The view shows everything by default; its "Show" selector (`?level=warning` or
-`?level=error`) hides the lesser issues - the summary line still counts them all.
+`?level=error`) hides the lesser issues - the summary line still counts them all. A national profile's
+validation (the `national` view, one profile) shows errors only by default (`?level=information` for everything).
 `fhir-validator-wrapper` 1.5.0 or later is needed: earlier versions sent the profiles in a
 form the validator service refuses.