Table of Contents

• Introduction
• About
• Licensing
• Basic terminology
• Usage
  • Direct web access
    • GitHub Pages
    • Content Delivery Network (CDN)
  • Installation
    • GitHub download
    • Node.JS and Node Package Manager (NPM)
  • Running in CLI

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.

  Please, analyze the JM2MP Syntax tutorial for information about this format and its library.

• A package JM2MP.JS-CLI to execute transformations (using 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.

  Review the Use in CLI tutorial to know how to use this feature.

• A set of static web pages ./JM2MP.JS-WWW/, part of this documentation, to test interactively in your own web browser how to use JM2MP.

  Consider the Use in WWW tutorial to read how to use this web page for stydy and practice your habilities with JM2MP.

• Examples of Express.js middleware, written with subtle variations for versions 4 and 5 of this specific framework for the development of web applications and services.

  The Use in Express.js tutorial shows how to use such examples.

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/json-mde/jm2mp.js/refs/heads/master/src/index.js instead of usual https://github.com/json-mde/jm2mp.js/blob/master/src/index.js 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.

They offer more efficient ways to directly use complex JavaScript libraries, such as JM2MP.JS, by embedding them in web pages (both static and dynamic), which saves developers from having to download and install the libraries beforehand.

In addition, they optimize content delivery by combining everything into a single download and even compressing the content to speed up the transmission of code over the Wolrd Wide Web.

Next, you can see an extract from file ./jm2mp.js-www/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>

Installation

GitHub download

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

• https://github.com/JSON-MDE/JM2MP.JS

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.

Running in CLI

Using NPX it is even possible to run directly JM2MP.JS through JM2MP.JS-CLI without a previous download.

Please, refer to the Use in CLI tutorial for more information and implications about this option.