CEDAR Model TypeScript Library

The CEDAR Model TypeScript Library is a TypeScript implementation of the CEDAR artifact model. It provides typed models, builders, readers, writers, and validators for CEDAR templates, elements, fields, and metadata instances.

The library reads and writes the JSON, JSON-LD, and YAML representations used by CEDAR. Applications can use the same model to construct artifacts, parse existing artifacts, validate metadata instances, and translate between serializations.

For an introduction to the API and examples covering fields, elements, templates, instances, readers, and writers, see the CEDAR Model TypeScript Library documentation.

This README covers installing, building, and testing the library.

Installing the Library

Releases are published to npmjs.org as cedar-model-typescript-library:

npm install cedar-model-typescript-library

The package includes CommonJS and ES module bundles together with TypeScript declarations. Import its public API from the package entry point:

import {
  CedarReaders,
  CedarWriters,
  JsonTemplateReaderResult,
  Template,
} from 'cedar-model-typescript-library';

export function jsonTemplateToYaml(templateJson: string): string {
  const result: JsonTemplateReaderResult = CedarReaders
    .json()
    .getStrict()
    .getTemplateReader()
    .readFromString(templateJson);

  const errorCount = result.parsingResult.getBlueprintComparisonErrorCount();
  if (errorCount > 0) {
    throw new Error(`Template contains ${errorCount} parsing errors`);
  }

  const template: Template = result.template;

  return CedarWriters
    .yaml()
    .getStrict()
    .getTemplateWriter()
    .getAsYamlString(template);
}

Reader results also contain a parsing report. Applications that accept external artifacts should inspect its errors and warnings before using the parsed artifact.

Paragraph length constraints

Use the paragraph builder to set the same minimum and maximum lengths supported by Java's TextAreaField:

import { CedarBuilders, TextArea } from 'cedar-model-typescript-library';

const paragraph: TextArea = CedarBuilders.textAreaBuilder()
  .withSchemaName('Summary')
  .withMinLength(20)
  .withMaxLength(500)
  .build();

Both limits are optional; pass null to clear one. Zero is retained as an explicit limit. JSON, full YAML and compact YAML preserve the limits, including on nested and repeated fields. These describe character lengths, independently of the number of field occurrences. Paragraph builders do not expose a regex constraint.

Canonical schema output

Standalone attribute-value fields use Java's array envelope (type: array, minItems: 0, items: <field definition>), just like deployed groups. The JSON reader also accepts the historical unwrapped definition.

Generated templates permit optional instance _annotations and its optional @nest context mapping. Annotation entries follow the existing CEDAR meta-schema: an IRI object or a literal value object, with no extra properties. These declarations are platform metadata, not child fields. Older templates without the declarations remain readable; writing them adds the declarations.

Finite numeric YAML and schema JSON values use Java 17's decimal digits, expanded without exponent notation. This includes midpoint and subnormal cases where JavaScript's shortest spelling differs. Shared Java-verified fixtures check the output and preservation of the original binary number.

Unicode field identifiers

JSON @id and YAML id field values accept RFC 3987 Unicode IRI characters without normalizing the stored string. This includes U+00A0 in an ontology term. Ordinary ASCII spaces, controls, malformed percent escapes, lone surrogates and noncharacters are rejected. Private-use characters are permitted only in the query component. Raw Unicode and percent-encoded identifiers remain distinct, as RDF identity requires. Artifact and element-occurrence identifiers retain their existing URI rules.

Building

Use Node 24.19.0, which .nvmrc and CI both specify:

nvm use
npm ci
npm run build

The build writes the publishable package to dist/. It contains the CommonJS and ES module bundles, source maps, TypeScript declarations, package manifest, license, and this README.

For local development, rebuild when source files change:

npm run build:watch

To make the built package available to a local consumer through npm linking:

npm run build
npm run link

Then run npm link cedar-model-typescript-library in the consuming project.

Testing

Run the same checks exercised by continuous integration:

npm run lint
npm run typecheck
npm run test:coverage
npm run parity:yaml
npm run parity:json
npm run test:package

npm run test:ci runs all six checks above concurrently within CEDAR_TEST_WORKERS (1–16; by default half the available CPUs, capped at 8). Use CEDAR_TEST_WORKERS=1 npm run test:ci for serial diagnosis. Coverage gets most of the budget; parity runs use private temporary output trees, and only packaging writes dist/. Fixture generation completes before any checks start, since parity and Jest read the same generated case module. Every stage reports its elapsed time, and any failed check fails the gate. Run concurrent gates in separate checkouts, not against the same output tree.

The unit suite covers the model and serialization behavior. The parity gates compare the TypeScript library with the Java CEDAR Artifact Library over the vendored JSON and YAML corpora.

npm run test:package builds the package that would be published, packs and installs it into an isolated consumer, and exercises its CommonJS bundle, ES module bundle, and TypeScript declarations.

Releasing

Release preparation and publication are documented in the CEDAR npmjs Release Runbook, which covers this library and the embeddable editor together. The release command publishes dist/, not the repository root.

License

The CEDAR Model TypeScript Library is released under the BSD 2-Clause License.

Controlled-term ontology constraints preserve a nondefault service address in YAML as sourceUri, separately from the canonical sourceIri. When sourceUri is absent, the reader retains compatibility with existing YAML by deriving the usual BioPortal address from sourceAcronym.