json-schema-translator

An implementation of schema translation/migration definition for JavaScript.

🆘 Help this project by conttributing to its documentation or developing its roadmap.

Definition

JSON Schema translation was created to map dictionaries of source-target properties, a.k.a. "from-to". It considers that a schema is a collection of "to" properties, where each property has a "from" key.

It adds a translation property to JSON Schema definition, which you can use to set the source from value.

{
  "$id": "my-schema",
  "properties": {
    "targetKey": {
      "type": "string",
      "translation": {
        "from": "sourceKey"
      }
    }
  }
}

Use it in code

1. Define a schema for output object

Define a translation property for each property of your destination schema.

So, if you have a schema like this (where "targetKey" is a property of output object)...

{
  "$id": "my-schema",
  "properties": {
    "targetKey": {
      "type": "string"
    }
  }
}

...you should end up with the following schema:

{
  "$id": "my-schema",
  "properties": {
    "targetKey": {
      "type": "string",
      "translation": {
        "from": "sourceKey"
      }
    }
  }
}

(Where "sourceKey" is a property from input object).

2. Require json-schema-translator library

$ npm install --save json-schema-translator

const JST = require(`json-schema-translator`);

3. Translate an object using your schema with translation options

const JST = require(`json-schema-translator`);
const mySchema = require('./my-schema.json');

const input = {
  sourceKey: 'value'
};

const output = await JST.translateObject(mySchema, input);

// output should be { targetKey: 'value' }

Features

⭐ Dot and array-notation support

You can specify dot-notation key paths and also array-notation key paths in from property, i.e.:

"from": "my.source.key"

"from": "my.source[1].element

⭐ Automatic casting of values

Arrays and objects

[1, 2, 3] → '1,2,3'

{ ob: "ject" } → '{ "ob": "ject" }'

When it finds a property value that is an object or an array, json-schema-translator tries to convert the value to the form specified in: 1) property options; 2) schema options; or 3) global defaults.

The global default array behavior is a join operation using the global array separator "," and the default object behavior is a stringify operation.

Find how to define translation options for schemas and properties in options reference,

Strings

123 → "123"

If the translator finds a property value which its type is explicity defined in target schema as a string, it will apply the toString() method to the source value.

Other types

⚠ Automatic casting of other primitive values (boolean, number, date, etc.) was not developed yet. Help us developing it in our roadmap.

⭐ Custom conversion providers

You can use community-made providers to convert source values from properties.

Just set a conversion property inside the translation property, containing:

A provider property with the name of provider
Other required provider options

An example of a custom conversion provider is AirtableLinkProvider, which produces target values with Airtable Link References, using a specified formula and the own property source value:

const AirtableLinkProvider = require(`airtable-link-provider`);
const mySchema = {
  "properties": {
    "User": {
      "type": "string",
      "translation": {
        "from": "userId",
        "conversion": {
          "provider": "AirtableLink",
          "table": "Users",
          "findFormula": "id=\"$val\"",
          "recordIdField": "recid"
        }
      }
    }
  }
};

const input = {
  User: '123'
};

const AirtableLink = new AirtableLinkProvider(apiKey, apiUrl, baseName);

const output = await JST.translateObject(mySchema, input, { AirtableLink });

// output should be { User: ['rec1x81731018xajq'] }

When using custom community providers, you need to specify the optional providers parameter of translateObject method. Every providers's key must match the name of the providers referenced inside the target schema.

translateObject(targetSchema: object, sourceObject: object, providers: object?)

ℹ You can find community providers in the /providers folder. If you want to write a custom provider and make it avaiable for the community, refer to the Creating custom providers section.