@opencharts/extension

Governed registry for canonical resource parameter extensions.

Overview

@opencharts/extension allows controlled expansion of resource parameters without modifying core resource definitions. Every extension must be registered with a namespace, name, version, owner, and applicable resource types before use.

Unregistered extensions fail validation. Published versions are immutable: re-registering the same namespace+name+version with different content throws.

Installation

npm install @opencharts/extension

Usage

Register an extension

import { CanonicalExtensionRegistry } from '@opencharts/extension';

const extensions = new CanonicalExtensionRegistry();

extensions.register({
  namespace: 'acme',
  name: 'risk_score',
  version: 1,
  owner: 'acme-analytics',
  applicable_resource_types: ['Patient'],
  max_size_bytes: 512,
  validation_schema: {
    score: { type: 'number', min: 0, max: 100 },
    model: { type: 'string' },
  },
});

Retrieve and check

const def = extensions.get('acme', 'risk_score', 1);
const exists = extensions.has('acme', 'risk_score', 1); // true

const allExtensions = extensions.list();

Validate an extension instance

extensions.validateInstance(
  { namespace: 'acme', name: 'risk_score', version: 1, data: { score: 82.5, model: 'v3' } },
  'Patient',   // optional resource type — checked against applicable_resource_types
);
// Throws InvalidCanonicalExtensionError if namespace/name/version not registered,
// resource type not applicable, or data exceeds max_size_bytes.

Extension Definition Fields

| Field | Type | Required | Description | |---|---|---|---| | namespace | string | ✓ | Organizational namespace | | name | string | ✓ | Extension name | | version | integer ≥ 1 | ✓ | Version number | | owner | string | ✓ | Team / system that owns this extension | | validation_schema | object | — | JSON Schema-like validation rules | | max_size_bytes | number | — | Max serialized size (default: 10 240) | | applicable_resource_types | string[] | — | Which resource types may carry this extension |

API Reference

CanonicalExtensionRegistry

| Method | Description | |---|---| | register(definition) | Register an extension definition (immutable once published) | | get(namespace, name, version) | Retrieve; throws if not registered | | has(namespace, name, version) | Returns boolean | | list() | All registered definitions | | validateInstance(extension, resourceType?) | Validate an extension instance |

License

MIT