dtdl-visualisation-tool

A CLI tool for visualising dtdl ontologies.

Prerequisites

node >= 20 Docker

Getting started

The build command should be run first to create the converted ts files.

npm i
npm run build

Start postgres and migrate to latest:

docker compose up -d
npm run db:migrate

To install npm CLI tool. It will be linked to local binaries so can be executed as dtdl-visualiser

npm i -g

using CLI

dtdl-visualiser help

parse

Attempts to parse every DTDL JSON file within the supplied directory and its sub-directories. Files are combined and parsed as a single JSON to ensure resolutions between entities are resolved correctly. If parsing is successful, the server starts.

dtdl-visualiser parse -P <http-server-port> -p <path-to-dtdl-ontology-directory>

For example:

dtdl-visualiser parse -p sample/energygrid

Go to http://localhost:3000

validate

Attempts to validate every DTDL JSON file within the supplied directory and its sub-directories. Files are validated one at a time. The process exits immediately if a file fails validation.

dtdl-visualiser validate -p <path-to-dtdl-ontology-directory>

For example:

dtdl-visualiser validate -p sample/energygrid

By default, validation ignores ResolutionExceptions that occur when parsing a single entity that references another entity. To include Resolution exceptions in validation add -r:

dtdl-visualiser validate -p sample/energygrid -r

Docker Compose

To bring up the postgres database service on port 5432, run

docker compose up

To bring up both the postgres database and the dtdl-visualiser service in docker you may run

docker compose up --scale dtdl-visualiser=1

The service will be available on http://localhost:3000

Docker

The application can be run in Docker. sample/energygrid is automatically parsed at start up.

docker build -t dtdl-visualiser . and run with docker run -p 3000:3000 dtdl-visualiser.

Environment variables

variable name	required	default	description
LOG_LEVEL	n	info	Logging level. Valid values are [ trace , debug , info , warn , error , fatal ]
CACHE_TTL	n	1000 * 60 * 5	Time to live (in seconds) for cached diagrams
CACHE_SIZE	n	100	Maximum number of diagrams to cache
SEARCH_THRESHOLD	n	0.4	Threshold for a fuzzy search match. 0.0 is a perfect match, 1.0 matches anything.
DB_HOST	n	localhost	The database hostname / host
DB_NAME	n	dtdl-visualisation-tool	The database name
DB_USERNAME	n	postgres	The database username
DB_PASSWORD	n	postgres	The database password
DB_PORT	n	5432	The database port number

Database migrations

To migrate up the database started by docker compose, run locally

npm run db:migrate

If you have started both the database and the dtdl-visualiser service with docker compose, the database will will already be migrated

Testing

This repository consists of two test types: [e2e, unit] and we are using a combination of mocha, chai and sinon frameworks.

Unit Testing

Unit tests are per service/module or class, and follow the below pattern. In tests directories collated with the units they test.

# example
├── __tests__
│   ├── example.test.ts
│   ├── __tests__
│   │   ├── index.test.ts
├── __tests__
....

Unit tests are executed by running:

npm run test:unit

End to End Testing

E2E tests use playwright and are described intest/.

Install dependencies for playwright with:

npx playwright install

Then run:

npm run test:e2e

A browser window will pop up where you can run tests and follow their progress. Alternatively run the tests without the ui:

npm run test:playwright

Test results are placed in playwright-report.