ICD-11 Validation in Node.js — WHO MMS Diagnosis Codes

1. What is ICD-11?

ICD-11 is the 11th revision of the International Classification of Diseases, adopted by the World Health Assembly in 2019 and in official use since 1 January 2022. Unlike ICD-10, ICD-11 was designed as a digital-native classification — a web-based ontology called the Foundation Component from which multiple linearizations are derived.

The most commonly used linearization is MMS — Mortality and Morbidity Statistics — which serves the role that ICD-10 filled: a flat list of stem codes for reporting, billing, and statistical analysis. MMS has about 17,000 categories, organised into 28 chapters, including entirely new chapters for traditional medicine (Chapter 26) and extension codes (Chapter X).

Adoption is gradual — as of 2026 most member states are still in the transition period. Some systems produce both ICD-10 and ICD-11 codes in parallel, and many jurisdictions have set target dates between 2025 and 2030 for full ICD-11 implementation.

2. MMS stem code structure

An ICD-11 MMS stem code looks like this:

The first character is a digit 1–9 identifying the chapter (or V for extension codes). It is followed by alphanumeric characters — with letters I and O excluded to avoid visual confusion with digits 1 and 0. An optional decimal point followed by one or two characters specifies sub-categories.

Some examples:

3. ICD-10 vs ICD-11

4. Why ICD-11 validation matters

5. The right solution

The IsValid ICD-11 API validates format with a strict regex and performs dictionary lookup against a locally-maintained mirror of the current WHO ICD-11 MMS linearization (refreshed monthly from the WHO ICD-API).

Full parameter reference: ICD-11 Validation API docs →

6. Node.js code example

import { createClient } from '@isvalid-dev/sdk';

const iv = createClient({ apiKey: process.env.ISVALID_API_KEY });

// ── Validate an ICD-11 MMS code ─────────────────────────────────────────────

const result = await iv.icd11('1A00');

if (!result.found) {
  console.log('Code is not in the WHO ICD-11 MMS dictionary');
} else {
  console.log('Title:', result.title);                 // → 'Cholera'
  console.log('Chapter:', result.chapter);             // → '01'
  console.log('Foundation URI:', result.foundationUri); // → WHO foundation link
  console.log('Version:', result.version);
}

// ICD-10 starts with a LETTER, ICD-11 starts with a DIGIT.
// Delegate validation to the right endpoint.

async function validateDiagnosis(code) {
  const first = code.trim().charAt(0);
  const isDigit = first >= '0' && first <= '9';

  if (isDigit) {
    return { revision: 'ICD-11', ...(await validateIcd11(code)) };
  }
  return { revision: 'ICD-10', ...(await validateIcd10(code)) };
}

// Usage
console.log(await validateDiagnosis('J45.0')); // → ICD-10
console.log(await validateDiagnosis('CA23'));   // → ICD-11

7. cURL example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/icd11?value=1A00"

Validate a circulatory code:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/icd11?value=BA00"

8. Understanding the response

Known code:

{
  "valid": true,
  "found": true,
  "icd11": "1A00",
  "title": "Cholera",
  "chapter": "01",
  "parent": null,
  "isLeaf": false,
  "foundationUri": "http://id.who.int/icd/entity/257068234",
  "blockId": null,
  "version": "ICD-11 for Mortality and Morbidity Statistics"
}

Valid format but unknown code:

{
  "valid": true,
  "found": false,
  "icd11": "9ZZ9",
  "title": null,
  "chapter": null,
  "parent": null,
  "isLeaf": null,
  "foundationUri": null,
  "blockId": null,
  "version": null
}

Invalid format:

{
  "valid": false
}

9. Edge cases

Node.js integration notes

In a TypeScript project, model ICD-10 and ICD-11 as distinct branded types (Icd10, Icd11) so the compiler prevents accidental cross-revision comparison. A discriminated union type DiagCode = { rev: 10; code: Icd10 } | { rev: 11; code: Icd11 } is useful when storing mixed data during migration periods.

Because the first character unambiguously distinguishes the two revisions, a cheap local dispatch check can route codes to the right endpoint without an extra network call. Use this for high-throughput pipelines.

For services that accept both revisions via the same API, normalise to an internal representation: { revision: 10 | 11, code: string, title: string }. This pattern keeps ICD-related business logic cleanly decoupled from the revision of the incoming code.