@opencharts/parameters

Canonical parameter catalog, validator, and built-in FHIR-aligned parameter types.

Overview

@opencharts/parameters provides the parameter type system used by canonical resources. Every value stored on a resource instance must belong to a registered parameter type.

• CanonicalParameterCatalog — register, retrieve, and validate parameter definitions.
• CanonicalParameterValidator — validate individual values and resource parameter maps against the catalog.
• baseParameters / registerBaseParameters — the built-in FHIR-aligned parameter set (Identifier, HumanName, CodeableConcept, Period, …).

Installation

npm install @opencharts/parameters

Usage

Using the base parameter set

import { createCanonicalSystem } from '@opencharts/sdk';

// createCanonicalSystem() seeds base parameters automatically
const { parameters } = createCanonicalSystem();

const def = parameters.get('HumanName'); // latest version
console.log(def.kind);  // 'object'

Manual setup (no SDK)

import { CanonicalParameterCatalog, registerBaseParameters } from '@opencharts/parameters';

const catalog = new CanonicalParameterCatalog();
registerBaseParameters(catalog);

const def = catalog.get('Identifier', 1);

Register a custom parameter type

catalog.register({
  name: 'NPI',
  version: 1,
  kind: 'string',
  validation: { pattern: '^\\d{10}$' },
});

Validate a value

import { CanonicalParameterValidator } from '@opencharts/parameters';

const validator = new CanonicalParameterValidator({ parameterCatalog: catalog });

// Validate a single value
validator.validateValue('AdministrativeGender', 'male');    // ok
validator.validateValue('AdministrativeGender', 'invalid'); // throws InvalidCanonicalParameterError

// Validate a parameter map against a resource definition's parameter spec
const { valid, errors } = validator.validateParameterMap(
  { identifiers: [{ system: 'mrn', value: '12345' }] },
  { identifiers: { parameter: 'IdentifierList', cardinality: '1..*' } },
);

Built-in Parameter Types

Structural types

| Name | Kind | Description | |---|---|---| | Identifier | object | { system, value, type? } | | IdentifierList | array | Array of Identifier | | Coding | object | { system, code, display? } | | CodeableConcept | object | { coding?, text? } | | ResourceReference | reference | { type, id?, key?, system?, protocol? } | | ReferenceList | array | Array of ResourceReference | | Period | object | { start?, end? } | | HumanName | object | { family?, given?, prefix?, suffix?, use? } | | HumanNameList | array | Array of HumanName | | Address | object | { use?, type?, line?, city?, state?, postal_code?, country? } | | AddressList | array | Array of Address | | ContactPoint | object | { system?, value, use?, rank? } | | ContactPointList | array | Array of ContactPoint | | Quantity | object | { value, unit?, system?, code?, comparator? } | | IdentityAssertion | object | { hash, identifiers?, names?, birth_date?, gender? } | | IdentityAssertionList | array | Array of IdentityAssertion |

Primitive types

String, StringList, Boolean, Integer, Decimal, Date, DateTime, URI

Coded types

AdministrativeGender, ClinicalStatus, AppointmentStatus, EncounterStatus, DocumentStatus, ObservationStatus, ConditionVerificationStatus

Choice (polymorphic) types

DateOrDateTimeOrPeriod, ObservationValue

API Reference

CanonicalParameterCatalog

| Method | Description | |---|---| | register(definition) | Register a parameter definition (immutable once published) | | get(name, version?) | Retrieve a definition (latest if no version) | | has(name, version?) | Check existence | | list() | All registered definitions | | validateValue(name, value, version?) | Validate a single value |

CanonicalParameterValidator

| Method | Description | |---|---| | requireRegistered(name, version?) | Throws if not registered | | validateValue(name, value, version?) | Validate a single value | | validateParameterMap(params, allowedParams, options?) | Returns { valid, errors } |

License

MIT