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.
| Tool | terminology-lookup |
| IRI | http://smart.who.int/base/tools/terminology-lookup.jsonld |
| part of | http://smart.who.int/base/smart-base.jsonld |
| type | https://litlfred.github.io/cat-harness/v0/ns/Tool |
| declared by | smart-base |
| invoked | shell |
| qa | qa-reports |
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 — smart-base/L1/schemas/skills/classify-and-code-content/input.schema.json
| field | type | required | description |
|---|---|---|---|
slot | condition \| intervention \| persona \| medicine \| domain \| business-process \| recommendation-strength \| recommendation-direction \| evidence-certainty | yes | The semantic slot being classified and coded, determining the authoritative scheme and reuse-first ladder. |
query | string | yes | The concept term, identifier, or code token to look up across the reuse-first precedence rungs. |
vocabulary | string | Optional repository path to the target guide’s personas and business processes (l1-scenario-vocabulary/v1), Rung 1 of reuse. | |
generic | string | Optional repository path to smart-base’s generic personas (l1-scenario-vocabulary/v1), Rung 2 of reuse. | |
scheme | string | Optional scheme identifier filter (e.g. guideline-domain, ISCO08, CDHIv2, grade-recommendation-strength). | |
out | string | Optional repository path where the lookup result JSON is written. |
output — smart-base/L1/schemas/skills/classify-and-code-content/output.schema.json
| field | type | required | description |
|---|---|---|---|
slot | string | yes | The semantic slot that was queried. |
query | string | yes | The query token or concept label that was looked up. |
authorityScheme | object | yes | |
bestMatchKind | exactMatch \| closeMatch \| none | yes | SKOS mapping precision of the top hit across local and base vocabularies, or none when Rung 4 applies. |
selectedRung | rung-1-target-guide \| rung-2-smart-base \| rung-3-external-standard \| rung-4-local-candidate | yes | The reuse-first precedence rung that settled the lookup. |
matches | object[] | yes | |
candidateToMint | object | Populated 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.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | slot | Slug | yes | The 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 |
| in | query | DocId | yes | The 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 |
| in | vocabulary | RepoPath | The 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. | |
| in | generic | RepoPath | smart-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. | |
| in | scheme | DocId | Restrict 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 | |
| in | out | RepoPath | Where to write the result JSON. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| out | result | RepoPath | Result 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:
| process | step | lane | via skill |
|---|---|---|---|
| Classify and code content | Identify slots and proposed exclusions | Authoring agent | classify-and-code-content |
| Classify and code content | Run reuse-first lookup and record candidates | Authoring agent | classify-and-code-content |
| Classify and code content | Check exclusions against page and sign | L1 extraction reviewer (person) | classify-and-code-content |
| Classify and code content | Adjudicate slot codings and glossary candidates | Terminologist / 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.
| install | none |
| runtime | bun |
| network | no |
| when to choose it | |
|---|---|
| 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. |
What it is made of
| role | file | |
|---|---|---|
| script | smart-base/scripts/terminology-lookup.ts |
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."
}
}