Home

Introduction

A .NET library for parsing and building OpenCodeList documents.

• Supports .NET 10, .NET 9 and .NET 8
• Includes document class for code list documents
• Includes document class for code list set documents
• Includes synchronous and asynchronous methods
• Parsing and building based on System.Text.Json.

Installation

OpenCodeList.NET is available on NuGet and can be installed via .NET CLI:

dotnet add package OpenCodeList.Net

Supported Versions

OpenCodeList.NET exposes version information through two static methods:

GetImplementedVersion()

Returns the OpenCodeList specification version implemented by the library.

SemanticVersion version = Document.GetImplementedVersion();

Use this method to determine which OpenCodeList version the library was built against and generates when creating new documents.

GetMinimumCompatibleVersion()

Returns the minimum OpenCodeList specification version supported by the library.

SemanticVersion version = Document.GetMinimumCompatibleVersion();

Use this method to determine the oldest OpenCodeList document version that can be processed by the library.

Loading Documents

Use DocumentLoader when you want to load either a code list or a code list set without knowing the type in advance.

using OpenCodeList;

Document document = await DocumentLoader.LoadAsync("codelist.json");

if (document is CodeListDocument codeList)
{
    Console.WriteLine(codeList.Identification.ShortName);
}
else if (document is CodeListSetDocument codeListSet)
{
    Console.WriteLine(codeListSet.Identification.ShortName);
}

You can also load a specific document type directly.

CodeListDocument codeList =
    await CodeListDocument.LoadAsync("codelist.json");

CodeListSetDocument codeListSet =
    await CodeListSetDocument.LoadAsync("codelistset.json");

Synchronous loading is also available:

var document = CodeListDocument.Load("codelist.json");

Creating a Code List

Let's create a code list programmatically.

using OpenCodeList;

var document = new CodeListDocument();

document.Identification.ShortName = "ExampleCodeList";
document.Identification.CanonicalUri = new Uri("https://example.com/codelist");
document.Identification.CanonicalVersionUri = new Uri("https://example.com/codelist/1.0.0");

var codeColumn = document.Columns.Add<StringColumn>();
codeColumn.Id = "code";
codeColumn.Name = "Code";

var sortOrderColumn = document.Columns.Add<IntegerColumn>();
sortOrderColumn.Id = "sortOrder";
sortOrderColumn.Name = "Sort Order";

var key = document.Keys.Add();
key.Id = "codeKey";
key.Name = "Code Key";
key.Columns.Add<StringColumn>().Id = "code";

document.DefaultKey = key;

var row = document.Rows.Add();
row["code"] = "A";
row["sortOrder"] = 1;

await document.SaveAsync("codelist.json");

Saving Documents

Documents can be saved to a file or stream.

await document.SaveAsync("codelist.json");

To customize JSON output, pass JsonWriterOptions.

await document.SaveAsync(
    "codelist.json",
    new JsonWriterOptions
    {
        Indented = true
    });

Synchronous saving is also available:

document.Save("codelist.json");

Saving Metadata Only

A code list can be saved without its data rows.

await document.SaveAsMetaOnlyAsync("codelist.meta.json");

This keeps metadata, annotations, columns, keys, default key, and foreign keys, but omits the dataset rows.