Reuse-first terminology and code-list lookup

Look up a concept or code token for a semantic slot across the four reuse-first rungs of the terminology-coding methodology: (1) the target guide’s l1-scenario-vocabulary/v1; (2) smart-base’s generic personas (DAK.Persona.*), GRADE code-lists/*.json and the guideline-domain SKOS glossary; (3) local WHO/ILO FSH CodeSystems (ISCO08, CDHIv2, CDHIv1, CDSCv2, KGTerminologySystem); (4) a proposed glossary-terms candidate (status: "candidate"), or could-not-determine for business-process.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

classify-and-code-content

Classify and code L1 narrative content (recommendations, implementation practices, remarks, and proposed coverage exclusions) and L2 DAK slots (personas, business processes, guideline domains, conditions, interventions, medicines, and GRADE ratings) using the terminology-coding methodology and the terminology-lookup Tool. Covers the authoring-agent’s four-rung reuse-first lookup, the l1-extraction-reviewer lane that reads and signs proposed L1 coverage exclusions against the printed page, and the terminologist / ontologist lane that adjudicates candidate codings and local glossary candidates.

Source: smart-base/L1/skills/smart-l1/classify-and-code-content.md.

input [1..1]output [1..1]authorityScheme [1..1]matches [0..*]term [0..1]candidateToMint [0..1]classify-and-code-content«skill»classify-and-code-contentinput : ClassifyAndCodeContentInput [1..1]output : ClassifyAndCodeContentOutput [1..1]ClassifyAndCodeContentInput«json-schema»ClassifyAndCodeContentInputslot : "condition" | "intervention" | "persona" | "medic… [1..1]query : string [1..1]vocabulary : string [0..1]generic : string [0..1]scheme : string [0..1]out : string [0..1]ClassifyAndCodeContentOutput«json-schema»ClassifyAndCodeContentOutputslot : string [1..1]query : string [1..1]authorityScheme : ClassifyAndCodeContentOutput.authority… [1..1]bestMatchKind : "exactMatch" | "closeMatch" | "none" [1..1]selectedRung : "rung-1-target-guide" | "rung-2-smart-bas… [1..1]matches : ClassifyAndCodeContentOutput.matches[] [0..*]candidateToMint : ClassifyAndCodeContentOutput.candidate… [0..1]ClassifyAndCodeContentOutput.authorityScheme«json-schema»ClassifyAndCodeContentOutput.authoritySchemeid : string [1..1]title : string [1..1]uri : string [1..1]localSources : string[] [0..*]ClassifyAndCodeContentOutput.matches«json-schema»ClassifyAndCodeContentOutput.matchesrung : "rung-1-target-guide" | "rung-2-smart-base" | "ru… [1..1]scheme : string [1..1]code : string [1..1]label : string [1..1]definition : string [0..1]matchKind : "exactMatch" | "closeMatch" [1..1]uri : string [0..1]sourcePath : string [1..1]ClassifyAndCodeContentOutput.candidateToMint.term«json-schema»ClassifyAndCodeContentOutput.candidateToMint.termid : string [0..1]prefLabel : string [0..1]status : "candidate" [0..1]source : "extracted" [0..1]ClassifyAndCodeContentOutput.candidateToMint«json-schema»ClassifyAndCodeContentOutput.candidateToMintaction : "mint-glossary-candidate" | "could-not-determin… [1..1]status : "candidate" | "could-not-determine" [0..1]term : ClassifyAndCodeContentOutput.candidateToMint.term [0..1]warning : string [1..1]

input — smart-base/L1/schemas/skills/classify-and-code-content/input.schema.json

fieldtyperequireddescription
slotcondition \| intervention \| persona \| medicine \| domain \| business-process \| recommendation-strength \| recommendation-direction \| evidence-certaintyyesThe semantic slot being classified and coded, determining the authoritative scheme and reuse-first ladder.
querystringyesThe concept term, identifier, or code token to look up across the reuse-first precedence rungs.
vocabularystringOptional repository path to the target guide’s personas and business processes (l1-scenario-vocabulary/v1), Rung 1 of reuse.
genericstringOptional repository path to smart-base’s generic personas (l1-scenario-vocabulary/v1), Rung 2 of reuse.
schemestringOptional scheme identifier filter (e.g. guideline-domain, ISCO08, CDHIv2, grade-recommendation-strength).
outstringOptional repository path where the lookup result JSON is written.

output — smart-base/L1/schemas/skills/classify-and-code-content/output.schema.json

fieldtyperequireddescription
slotstringyesThe semantic slot that was queried.
querystringyesThe query token or concept label that was looked up.
authoritySchemeobjectyes
bestMatchKindexactMatch \| closeMatch \| noneyesSKOS mapping precision of the top hit across local and base vocabularies, or none when Rung 4 applies.
selectedRungrung-1-target-guide \| rung-2-smart-base \| rung-3-external-standard \| rung-4-local-candidateyesThe reuse-first precedence rung that settled the lookup.
matchesobject[]yes
candidateToMintobjectPopulated when bestMatchKind is none: either a glossary-terms candidate entry (status: candidate) or could-not-determine for business-process, with its greppable WARNING line.

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inslotSlugyesThe slot to code (condition, intervention, persona, medicine, domain, business-process, recommendation-strength, recommendation-direction, evidence-certainty).string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe
inqueryDocIdyesThe term, identifier or code token to look up.string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$ · A library document id, e.g. WPR-RDO-2020-003-eng
invocabularyRepoPathThe target guide’s personas and business processes (l1-scenario-vocabulary/v1), rung 1.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
ingenericRepoPathsmart-base’s generic personas (l1-scenario-vocabulary/v1), rung 2.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inschemeDocIdRestrict to one scheme (e.g. guideline-domain, ISCO08, CDHIv2, grade-recommendation-strength).string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$ · A library document id, e.g. WPR-RDO-2020-003-eng
inoutRepoPathWhere to write the result JSON.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outresultRepoPathResult JSON conforming to L1/schemas/skills/classify-and-code-content/output.schema.json.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.

Processes and tasks

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
Classify and code contentIdentify slots and proposed exclusionsAuthoring agentclassify-and-code-content
Classify and code contentRun reuse-first lookup and record candidatesAuthoring agentclassify-and-code-content
Classify and code contentCheck exclusions against page and signL1 extraction reviewer (person)classify-and-code-content
Classify and code contentAdjudicate slot codings and glossary candidatesTerminologist / ontologist reviewer (person)classify-and-code-content

How it is deployed and reached

  • Command line. From the repository root: bun run smart-base/scripts/terminology-lookup.ts --slot <slot> --query <query> [--vocabulary <guide.json>] [--generic <generic.json>] [--scheme <scheme>] [--out <out.json>].
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkno
when to choose it
whenCoding L1 narrative statements or L2 DAK slots (personas, processes, domains, interventions, conditions, medicines, GRADE ratings) reuse-first, per terminology-coding.
limitsQueries local code lists, SKOS glossaries, l1-scenario-vocabulary/v1 files and FSH CodeSystems, offline. It ranks lexical exact and close matches only and prepares rung-4 candidate records; semantic fit and exclusion sign-off stay human judgements in classify-and-code-content.bpmn.
costMilliseconds, offline.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, http://smart.who.int/base/tools/terminology-lookup.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "http://smart.who.int/base/smart-base.context.jsonld",
  "@id": "http://smart.who.int/base/tools/terminology-lookup.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "http://smart.who.int/base/smart-base.jsonld",
  "name": "terminology-lookup",
  "title": "Reuse-first terminology and code-list lookup",
  "description": "Look up a concept or code token for a semantic slot across the four reuse-first rungs of the `terminology-coding` methodology: (1) the target guide's `l1-scenario-vocabulary/v1`; (2) smart-base's generic personas (`DAK.Persona.*`), GRADE `code-lists/*.json` and the `guideline-domain` SKOS glossary; (3) local WHO/ILO FSH CodeSystems (`ISCO08`, `CDHIv2`, `CDHIv1`, `CDSCv2`, `KGTerminologySystem`); (4) a proposed `glossary-terms` candidate (`status: \"candidate\"`), or `could-not-determine` for `business-process`.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run smart-base/scripts/terminology-lookup.ts --slot <slot> --query <query> [--vocabulary <guide.json>] [--generic <generic.json>] [--scheme <scheme>] [--out <out.json>]"
  },
  "io": {
    "inputs": [
      {
        "name": "slot",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
        "description": "The slot to code (`condition`, `intervention`, `persona`, `medicine`, `domain`, `business-process`, `recommendation-strength`, `recommendation-direction`, `evidence-certainty`).",
        "required": true
      },
      {
        "name": "query",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/DocId",
        "description": "The term, identifier or code token to look up.",
        "required": true
      },
      {
        "name": "vocabulary",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The target guide's personas and business processes (`l1-scenario-vocabulary/v1`), rung 1.",
        "required": false
      },
      {
        "name": "generic",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "smart-base's generic personas (`l1-scenario-vocabulary/v1`), rung 2.",
        "required": false
      },
      {
        "name": "scheme",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/DocId",
        "description": "Restrict to one scheme (e.g. `guideline-domain`, `ISCO08`, `CDHIv2`, `grade-recommendation-strength`).",
        "required": false
      },
      {
        "name": "out",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Where to write the result JSON.",
        "required": false
      }
    ],
    "outputs": [
      {
        "name": "result",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Result JSON conforming to `L1/schemas/skills/classify-and-code-content/output.schema.json`."
      }
    ]
  },
  "satisfies": [
    "classify-and-code-content"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "Coding L1 narrative statements or L2 DAK slots (personas, processes, domains, interventions, conditions, medicines, GRADE ratings) reuse-first, per `terminology-coding`.",
    "limits": "Queries local code lists, SKOS glossaries, `l1-scenario-vocabulary/v1` files and FSH CodeSystems, offline. It ranks lexical exact and close matches only and prepares rung-4 candidate records; semantic fit and exclusion sign-off stay human judgements in `classify-and-code-content.bpmn`.",
    "cost": "Milliseconds, offline."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev