JSON Model-to-Model Projection (JM2MP) Documentation

JSON Model-to-Model Projection (JM2MP) Documentation

Getting Started!

Table of Contents

Introduction

JSON Model-to-Model Projections (JM2MP) is both a JSON-based format to transform algebraically any input JSON document into another output JSON document and the JavaScript library JM2MP.JS to execute such transformations.

JM2MP.JS offers you:

  • A JavaScript EM2024 library to execute JM2MP transformations as part of your applications and services.

  • An script ./cli/main.js to execute transformations (using, for instance, Node.JS) as part of an on-line and interactive command-line interface (CLI), or as part of a batch processing in a shell script.

  • A web page ./web/index.html to test interactively in your own web browser how to use JM2MP.

  • Examples of Express.JS middleware, written with subtle variations for versions 4 and 5 of this specific framework.

About

JM2MP and JM2MP.JS has been design and develop by Luis Maria CAMARA ROSSI as part of his work toward a Doctor in Philosophy (Ph.D.) degree in Doctoral Programme in Engineering of Systems and Control[1][2].

I would like to extend special thanks to my tutor Elena RUIZ LARROCHA and my director José Antonio CERRADA SOMOLINOS for their contributions throughout my doctoral studies, as well as to all other members of the ISSI and rest of Departments in the School of Computer Science.

I would also like to thank María Isabel Cámara and Kulvir Sroy for their invaluable assistance during the translation of this article and other texts I wrote as part of my doctoral studies.

Licensing

Both JM2MP format and JM2MP.JS library are licensed under BSD-3-Clause, so you can get the source code and all its products, and derive it for your own specific needs. But, please, remember the conditions under such license about redistribution, attribution and endorsement.

Basic concepts

Using JM2MP.JS JavaScript library anyone can transforms source (input) JSON documents declared in a projection (transformation) JSON document into resultant (output) JSON documents.

The projection documents use the JM2MP syntax, which is entirely based on JSON, to perform these transformations.

A projection is a composition of command templates, which are the actual operations that you can use to transform JSON values.

Several command templates would be combined into a named template, similar to a (macro) function, that can be invoked several times during a projection.

Complex projections can be divided into separate files called projection modules, which makes it easier to reuse named templates and, at the same time, reduces the complexity that would be involved in working with a single, large projection.

The tutorial JM2MP Syntax discusses all of these topics in greater detail.

Usage

There are several ways to use JM2MP.JS directly from any modern web browser: direct web access (vía GitHub raw user content or CDN) or installation (manually downloading source code or installing it using NPM).

Direct web access

GitHub Pages

Everyone can access specific files from a GitHub repository using https://raw.githubusercontent.com/lmcamara-aldeas/pixel-aid-connect/main/src/assets/hero-image.jpg instead of usual https://github.com/lmcamara-aldeas/pixel-aid-connect/blob/main/src/assets/hero-image.jpg URL.

This way, you can link to specific files of JM2MP.JS library to use them from your own applications and services.

Content Delivery Network (CDN)

Using CDN services like jsDelivr allows the JM2MP.JS library to be used in web applications without the need for prior installation, thanks to the use of WebPack as a code bundler.

Next, you can see an extract from file ./web/jm2mp-cdn.html. You can save it to your hard disk drive and open it with any modern browser to see it working:

<script type="module">
  import JM2MP from 'https://cdn.jsdelivr.net/npm/@json-mde/jm2mp@1.0.0/+esm' ;
</script>

As previuosly mentioned, you can access the full file from (https://raw.githubusercontent.com/lmcamara-aldeas/pixel-aid-connect/main/src/assets/hero-image.jpg) URL.

Installation

GitHub download

Source code of the JM2MP.JS library is published in GitHub:

You can directly download (only but all) source code as one single ZIP compressed file.

An inmutable release tagged as 1.0.0 has also been published; it consists of several files to make it easier to download the desired content: everything, only the source code, or only this documentation.

Node.JS and Node Package Manager (NPM)

You can install JM2MP.JS using Node Package Manager (NPM) for Node.JS (version 22, at least) runtime.

npm install --save @json-mde/jm2mp

This is the way how to use JM2MP.JS library as part of a project that isn't just a simple web page, such as complex applications or services.