RAMEN Core is a TypeScript library for tools that create, refine, validate and exchange data models. Define which objects, properties and relationships your application supports, then check recorded data against those definitions.
It provides a generic modelling API based on the RAMEN Model Format (RMF) and a RAMEN API for digital scholarly editions. Use @ramen-suite/core in Node.js or browser bundles without a UI framework dependency.
- Model editors that define object types, properties, relationships and constraints.
- Project models that specialise shared definitions through inheritance across model levels.
- Data-entry and publishing tools that validate recorded objects and links against a project model.
- Integrations that exchange models as JSON while retaining declaration identities, dependencies and inheritance.
Core handles model definitions, validation, suggestions and model comparison. Your application supplies the interface, storage and recorded data. Comparing model versions reports changes; it does not migrate records automatically.
RMF defines the generic model structure: nodes, data types, properties, relationships, constraints and imports. Use it to create a modelling language for your own domain.
RAMEN (Reusable Abstraction Model for Editorial Needs) builds on RMF for digital scholarly editions. Its shared Collection, Content, Entity and Annotation types describe editorial structures, source content, scholarly entities and annotations. Project models refine those types and declare the relationships and annotation shapes they need.
See RAMEN Schema for the conceptual background and specification project, starting with What is RAMEN?. The Core guides explain how to use the library APIs.
npm install @ramen-suite/coreThe package provides ESM modules, TypeScript declarations and JSON schemas.
| Import | Use |
|---|---|
@ramen-suite/core |
Access both modelling APIs. |
@ramen-suite/core/model |
Create and validate generic RMF models. |
@ramen-suite/core/ramen |
Create project models based on RAMEN. |
@ramen-suite/core/schemas/* |
Use the packaged JSON schemas. |
Define a Document type with a title property, then export the model:
import { DataTypes, Modeller } from '@ramen-suite/core/model';
import type { ModelFile, Node } from '@ramen-suite/core/model';
const model: Modeller = Modeller.create('Filing');
const document: Node = model.createNode('Document').element;
model.createAttribute(document, { name: 'title', typeId: DataTypes.String });
const file: ModelFile = model.export();file is JSON-serialisable and contains the selected model and its imported predecessors. Restore it with Modeller.import(file). Use model.validate() to inspect model diagnostics and model.validateInstances(data) to check recorded objects and links.
Continue with the RMF guide or the complete Website example.
For a correspondence edition, refine Collection into Letter, Content into Text, and Entity into Person:
import { RAMEN_ELEMENT, RamenModel } from '@ramen-suite/core/ramen';
import type { Node } from '@ramen-suite/core/model';
const edition: RamenModel = RamenModel.create('Edition');
const letter: Node = edition.createNode({ name: 'Letter', refines: RAMEN_ELEMENT.COLLECTION }).element;
const text: Node = edition.createNode({ name: 'Text', refines: RAMEN_ELEMENT.CONTENT }).element;
const person: Node = edition.createNode({ name: 'Person', refines: RAMEN_ELEMENT.ENTITY }).element;
edition.partOf(text, letter);
edition.hasAnnotation(text, RAMEN_ELEMENT.ANNOTATION);
edition.refersTo(RAMEN_ELEMENT.ANNOTATION, person);Letter, Text and Person inherit the properties of their RAMEN base types. The project reuses Annotation without refining it. These relationships permit texts to belong to letters and carry annotations that refer to persons.
Use Annotations shows how to declare annotation shapes such as person or comment, each with its own properties and permitted relationships. The digital edition example develops a complete project model.
Core checks both model definitions and recorded data:
- Model structure, identities, imports, inheritance and refinement rules.
- Recorded nodes, property values and relationships supplied as a
ModelInstanceGraph. - Cardinalities, keys, literals and constraints written with regex, format, JSON Schema or a registered evaluator.
- RAMEN project conformance, including annotation shapes, their permitted properties and relationships, and selector type declarations.
JSON schemas check document structure. Core also resolves model references and applies semantic rules and inherited constraints. Findings include diagnostic codes, severities and paths for your application to display.
Tools translate their data into the instance graph and interpret selector details. See Validate Models and Data and Read Diagnostics.
Browse the guides and API reference online:
- RMF guide, create and refine generic models.
- RAMEN guide, build editorial project models.
- Constraints and JSON schemas, validation languages and packaged formats.
- RAMEN Schema, concepts, examples and the specification project.
For a local preview from a repository checkout:
nvm use
npm ci
npm run docs:serveOpen http://127.0.0.1:5173. For automatic rebuilds, run npm run docs:watch in a second terminal and refresh the browser after changes.
Run npm run verify before handing off a change. It checks types, schemas, lint, formatting, tests, documentation and an independently installed package consumer, including browser bundling.
- Contribution workflow and coding conventions
- Report a bug or suggest an improvement
- Code of Conduct
- Security policy
RAMEN Core is available under the MIT licence.