Home

OpenCodeList is a standardised JSON format for the generic representation of code lists.

This is a TypeScript/JavaScript library for parsing and building OpenCodeList documents.

Installation

opencodelist-ts is is available on npm and can be installed via npm:

npm install opencodelist-ts

Using the libraray

Basic imports

ESM / TypeScript (recommended):

import {
  DocumentLoader,
  CodeListDocument,
  CodeListSetDocument,
  CodeListParserError,
} from "opencodelist-ts";

CommonJS (Node):

const {
  DocumentLoader,
  CodeListDocument,
  CodeListSetDocument,
  CodeListParserError,
} = require("opencodelist-ts");

Parse unknown OpenCodeList JSON with DocumentLoader

Use this when input may be either codeList or codeListSet.

import { DocumentLoader, CodeListDocument, CodeListSetDocument } from "opencodelist-ts";

const jsonText = await fs.promises.readFile("input.json", "utf8");
const doc = DocumentLoader.load(jsonText);

if (doc instanceof CodeListDocument) {
  console.log("CodeList rows:", doc.rows.count);
} else if (doc instanceof CodeListSetDocument) {
  console.log("References:", doc.documentRefs.count);
}

Parse known document type directly

If you already know the JSON contains a codeList root:

import { CodeListDocument } from "opencodelist-ts";

const root = JSON.parse(jsonText) as Record<string, unknown>;
const codeList = CodeListDocument.parse(root);

console.log(codeList.identification.shortName);
console.log(codeList.columns.count);
console.log(codeList.rows.count);

For code list sets:

import { CodeListSetDocument } from "opencodelist-ts";

const root = JSON.parse(jsonText) as Record<string, unknown>;
const codeListSet = CodeListSetDocument.parse(root);

console.log(codeListSet.identification.shortName);
console.log(codeListSet.documentRefs.count);

Error handling

Invalid structure/version throws CodeListParserError.

import { DocumentLoader, CodeListParserError } from "opencodelist-ts";

try {
  const doc = DocumentLoader.load(jsonText);
  console.log(doc.metaOnly);
} catch (err) {
  if (err instanceof CodeListParserError) {
    console.error("OpenCodeList parse error:", err.message);
  } else {
    throw err;
  }
}

Serialization examples

Every document supports:

• serialize() (pretty by default)
• serializeMetaOnly()
• formatting options

// pretty default
const pretty = doc.serialize();

// compact
const compact = doc.serialize(false, { pretty: false });

// custom indent
const indented = doc.serialize(false, { pretty: true, indent: 4 });

// metadata only
const meta = doc.serializeMetaOnly();
const metaCompact = doc.serializeMetaOnly({ pretty: false });

Work with rows (CodeListDocument)

const row0 = codeList.rows.getAt(0);

console.log(row0.get("code"));
console.log(row0.get("bool"));

row0.set("bool", true); // type-validated based on column definition

Use model and dictionary subpaths

If you want broad model access, use subpath exports:

import { Row, Description, Identification } from "opencodelist-ts/models";
import { PropertyNames, TypeConsts } from "opencodelist-ts/dictionaries";

Typical Node.js workflow example

import { readFile, writeFile } from "node:fs/promises";
import { DocumentLoader, CodeListDocument } from "opencodelist-ts";

const input = await readFile("./test/assets/codelist.json", "utf8");
const doc = DocumentLoader.load(input);

if (doc instanceof CodeListDocument) {
  const output = doc.serialize(false, { pretty: true, indent: 2 });
  await writeFile("./output.codelist.json", output, "utf8");
}