@daihum/record-formats

Product-neutral TypeScript adapters for scholarly, archival, library, and cultural record formats.

The package is intentionally modular and tree-shakeable. Consumers import only the format family they need:

import { parseXml } from '@daihum/record-formats/xml';
import { parseEad3Xml } from '@daihum/record-formats/ead3';
import { parseArchiveDescriptionJson } from '@daihum/record-formats/archive-description';
import { parseCollectionJson } from '@daihum/record-formats/collection';

Initial scope

• Common result and issue contracts for parse, serialize, and validation workflows.
• XML parse/build helpers backed by fast-xml-parser.
• EAD3 finding-aid projection helpers adapted from Carrel's initial XML/EAD starter.
• archive-description.v1, the canonical recursive Archive record, with JSON Schema, DACS profile validation, and explicit EAD3 projection diagnostics.

Future modules can add TEI, MARC/MARCXML, MODS, Dublin Core, EAC-CPF, and crosswalk helpers under explicit subpaths without forcing consumers to import the whole surface.

EAD3 Profile

@daihum/record-formats/ead3 exposes EAD3_ADAPTER_PROFILE and result-level adapterProfile metadata. The current profile is daihum.record-formats.ead3.projection.v0:

• formatId: ead3
• formatGeneration: EAD3
• namespace: http://ead3.archivists.org/schema/
• schemaVersion / schemaRevision: 1.1.1
• tagLibraryVersion: 1.1.2
• validationLevel: projection
• officialSchemaValidation: false

This means the adapter validates DAIHUM's common finding-aid projection fields and parser/serializer invariants. It does not run official EAD3 RNG, XSD, DTD, or Schematron schema validation yet. Consumers should surface the adapter profile when exporting or importing EAD XML so users can distinguish projection output from full schema validation.

Archive Description

@daihum/record-formats/archive-description owns the canonical Archive-domain record. One archive-description.v1 record represents one finding aid. Its stable node ids and recursive subItems tree keep hierarchy and description in one versioned truth while opaque target refs connect nodes to external material, page, representation, or annotation records.

EAD3 is a bidirectional projection of that record, not the canonical store. Projection results include structured warnings whenever a canonical fact cannot be represented. DACS checks are a separate conformance profile; they do not change the structural parser. The JSON Schema id and revision are exported for storage envelopes and exchange validation.

Cross-tree node-id uniqueness is enforced by the package runtime validator. JSON Schema validates the recursive shape and collection root but cannot express that global uniqueness invariant.

Collection

@daihum/record-formats/collection owns the product-neutral collection.v1 interchange record. It is one identity-bearing snapshot with canonical @daihum/work-metadata titles, identifiers, and provenance plus an ordered array of open typed member references.

import {
  COLLECTION_SCHEMA,
  computeCollectionContentHash,
  parseCollectionJson,
} from '@daihum/record-formats/collection';

Member array order is authoritative. orderKey is optional metadata and is not a uniqueness constraint. Collection nesting uses a member target with kind: 'collection'; the format has no embedded recursive collection and no parent pointer. Target kinds are open strings, with work, collection, material.object, representation, and uri as the documented common values.

The JSON Schema is the portable shape truth. The runtime adds the cross-member invariant that each (target.kind, target.id) pair is unique and, when a contentHash is present, verifies it against the canonical snapshot excluding that self-referential field.

Boundaries

This package owns format adapters and reusable record mappings. Product storage, authority, migration, UI, CLI, import jobs, copy, and downstream persistence remain in Carrel, ONTAL, or other consuming apps.