RAMEN Core
    Preparing search index...

    RAMEN Core

    RAMEN Model Format

    RAMEN Model Format (RMF) describes data models in JSON. You define which types, properties and relationships tools can use to collect data. This page builds a small Filing model and then a Website model based on it. Each step continues the previous one, with links to guides that explain the choices.

    Concept Purpose Example
    Model A versioned set of definitions Filing
    Node An object type Document
    Attribute A typed property title
    Data type Allowed property values String
    Relation A permitted connection FILED_IN
    Import An exact model dependency Use Filing from another model
    Refinement A more specific definition A specialised Document type

    Modeller is the class you use to edit a model. Model, Node, Attribute and Relation are data interfaces. Node objects hold definitions, and Modeller provides the editing methods. The Glossary distinguishes model levels, graphs, records and API results. The RMF Model example shows a complete two-level website model.

    Create Filing and its two node types:

    import { Modeller } from '@ramen-suite/core/model';
    import type { Node } from '@ramen-suite/core/model';

    const model: Modeller = Modeller.create('Filing');
    const document: Node = model.createNode('Document').element;
    const folder: Node = model.createNode('Folder').element;

    Filing is the model. Document and Folder are the types it defines. This defines a schema for documents and folders rather than creating individual records.

    Editing methods return a ModelChange: { element, validation }. Use .element to keep a definition. The API generates IDs and a model URI, with 1.0.0 as the default version. Create Nodes covers creation, editing and deletion of node types.

    Give Document a required string title:

    import { DataTypes } from '@ramen-suite/core/model';

    model.createAttribute(document, {
    name: 'title',
    typeId: DataTypes.String,
    bounds: { lowerBound: 1, upperBound: 1 },
    });

    typeId selects the value type, while bounds requires exactly one value. Add optional Folder properties:

    model.createAttribute(folder, { name: 'description', typeId: DataTypes.String });
    

    The default cardinality is 0..1, and refined nodes inherit these properties. Add Properties explains cardinality and flags such as isKey, isUnique and isOrdered. Add Data Types shows literals and web formats.

    Allow Document → Folder and at most one Folder per Document:

    import type { Relation } from '@ramen-suite/core/model';

    const filedIn: Relation = model.createRelation({
    name: 'FILED_IN',
    from: { node: document },
    to: { node: folder, bounds: { lowerBound: 0, upperBound: 1 } },
    }).element;

    FILED_IN defines a permitted relationship, not a recorded link. Add Relationships explains both cardinalities, endpoint options and relation selection on another level.

    Use validate() to check structure, references and model rules:

    import type { ProjectValidationResult } from '@ramen-suite/core/model';

    const result: ProjectValidationResult = model.validate();
    if (!result.valid) {
    console.log(result.diagnostics);
    }

    Export requires a valid model. See Validate Models and Data, Add Constraints, Constraint Languages and Read Diagnostics.

    Create Website from Filing and refine its imported types:

    const project: Modeller = model.createNextLevel('Website');
    const page: Node = project.createNode({ name: 'Page', refines: document }).element;
    const section: Node = project.createNode({ name: 'Section', refines: folder }).element;

    project.createRelation({ refines: filedIn, from: { node: page }, to: { node: section } });

    Page inherits title, and Section inherits description. Website explicitly applies Filing's relationship. Refine by Inheritance compares inheritance in one model with a new level.

    Models, nodes, relations, properties, data types, literals, constraints and RAMEN annotation shapes accept optional description metadata. It is plain text, may contain line breaks and is limited to 2,000 Unicode code points (DESCRIPTION_MAX_LENGTH). Empty or whitespace-only descriptions are omitted; other text is preserved. Updates retain the description unless explicitly supplied, and an empty string clears it.

    Descriptions stay with their declaring definitions through duplication, inherited-property lookup and model import/export. They do not create captured-data fields or change validation rules; a constraint's description explains the rule, while its message reports a violation. Invalid or oversized descriptions are rejected without truncation. Project-level ProjectMetadata.description remains a separate, unchanged field.

    export() writes Website and Filing into one file. import() restores both levels:

    import type { ModelFile } from '@ramen-suite/core/model';

    const file: ModelFile = project.export();
    const json: string = JSON.stringify(file, null, 2);

    const parsed: unknown = JSON.parse(json);
    const restored: Modeller = Modeller.import(parsed);

    The file follows the RMF file schema. Export and Import explains how one graph preserves each level's ownership.