Introduction

The JavaScript SDK lets you load Aspect Models in JavaScript and TypeScript applications. It reads Aspect Models written in RDF/Turtle (SAMM 2.0.0, 2.1.0 and 2.2.0) and returns them as typed TypeScript objects. You can traverse these objects, or process them with a visitor, to access the model’s information, such as properties, characteristics, entities, units, descriptions and constraints.

This lets you build generic frontends that adapt to the underlying Aspect Model automatically. For example, when a new property is added to the model, the UI can show the corresponding value together with the property’s name, description and unit without any code changes.

Getting Started

Install from GitHub release repository

npm install https://github.com/eclipse-esmf/esmf-sdk-js-aspect-model-loader/releases/download/v2.3.3/esmf-sdk-js-2.3.3.tgz

The package is named @esmf/sdk-js (formerly @esmf/aspect-model-loader).

The package is published as an ES module only and requires Node.js 24 or newer. CommonJS consumers can load it via require() on Node.js 22.12 or newer.

Usage

import {AspectModelLoader, Aspect} from '@esmf/sdk-js';

This package contains two methods for loading Turtle (.ttl) files (string value of the .ttl files). Each method is available as a Promise-based variant and as an RxJS Observable variant.

Load an aspect model which is self-contained (includes no imports to other ttl file):

const aspect: Aspect = await new AspectModelLoader().loadSelfContainedAspect(ttl);

// or as Observable
new AspectModelLoader().loadSelfContainedModel(ttl).subscribe((aspect: Aspect) => {
...
});

or if the model contains imports to additional ttl files:

const aspect: Aspect = await new AspectModelLoader().loadAspect('<aspect-model-urn>', ttl1, ttl2, ttl3);

// or as Observable
new AspectModelLoader().load('<aspect-model-urn>', ttl1, ttl2, ttl3).subscribe((aspect: Aspect) => {
...
});

Errors are reported as typed error classes (for example UnsupportedVersionError, AspectNotFoundError or MultipleAspectsFoundError), all derived from AspectModelError.

If you are using external .ttl files you may need to parse the contents of these files to strings, to be passed to the methods params.

Load namespaces

To load all model elements of one or more namespaces without selecting a specific aspect, use the NamespaceLoader:

import {NamespaceLoader} from '@esmf/sdk-js';

const namespaces = await new NamespaceLoader().loadNamespaces(ttl1, ttl2);

Error handling

All errors thrown or emitted by the loaders derive from AspectModelError:

Error Cause

UnsupportedVersionError

The model uses a SAMM version that is not supported.

AspectNotFoundError

No aspect with the requested URN was found.

MultipleAspectsFoundError

A self-contained model contains more than one aspect.

EntityInstanceResolutionError

An entity instance could not be resolved.

NotAbstractEntityError

An entity that must be abstract is not abstract.

RdfParseError

The Turtle input could not be parsed.

import {AspectModelError, AspectNotFoundError} from '@esmf/sdk-js';

try {
  await loader.loadAspect(urn, ttl);
} catch (error) {
  if (error instanceof AspectNotFoundError) {
    // handle missing aspect
  } else if (error instanceof AspectModelError) {
    // handle any other loader error
  }
}

Helpful functions

After loading, the loader exposes helper functions to find model elements.

Find a model element by its URN (returns the element or undefined):

const element = loader.findByUrn('urn:samm:org.example:1.0.0#myProperty');

Find model elements by name (returns all matching elements):

const elements = loader.findByName('myProperty');

Filter all loaded model elements with a predicate:

import {DefaultProperty} from '@esmf/sdk-js';

const properties = loader.filterElements(element => element instanceof DefaultProperty);

Visitor

To process a loaded model, extend DefaultAspectModelVisitor and override the methods for the element types you need:

import {DefaultAspectModelVisitor, DefaultProperty} from '@esmf/sdk-js';

class PropertyCounter extends DefaultAspectModelVisitor<void, unknown> {
  count = 0;

  visitProperty(property: DefaultProperty, context: unknown): void {
    this.count++;
    return super.visitProperty(property, context);
  }
}

const counter = new PropertyCounter();
counter.visit(aspect, {});

Development

Requirements: Node.js 24 or newer and pnpm.

pnpm install
pnpm run build   # build the library into dist/
pnpm test        # run the tests
pnpm run all     # build, format, lint, type check, tests with coverage and package checks

See the contribution guideline and the changelog for details.