Setup.json

Setup JSON represents a digital contract of a module. It is a file (or groups of files) and it defines everything critical from the point of view of business or development that can be expressed in declarative language understood by machines. Allows speeding up the development, part of the QA, distribution and finally the configuration by the client.

PROS has chosen to define the schema using the JSON Schema (opens in a new tab) specification, and by doing so provides an open source way of annotating and validating this contract for it's partners and customers.

What is Setup JSON

Setup JSON represents a digital contract of a module. It is a file (or groups of files) and it defines everything critical from the point of view of business or development that can be expressed in declarative language understood by machines.

Allows speeding up the development, part of the QA, distribution and finally the configuration by the client.

The setup.json is closely related to the structure and the data that the module will receive to initialize, called in our ecosystem: Module Payload.

Workflow

TODO: Details about uses in development, QA and production

General structure

All Modules include an setup.json file. Here's the general file structure. The specification of each of the sections is explained in detail later in this document.

{
  "context": {},
  "settings": {
    "schema": {}
  },
  "styles": {},
  "i18n": {},
  "tokens": {
    "em:apiKey": "<value>"
  },
  "services": {},
  "metaData": {}
}

How to create and validate

The setup.json file is defined by a JSON Schema: setup.json schema. (opens in a new tab)

All validations to the setup.json that happens in the Registry Ecosystem, including the Registry Editor Tool, follow this specification.

Backward compatibility

Lorem ipsum lorem

Module Payload

The Module Payload is the initial input that the module receives to render. The data included depends on what is configured in the Setup JSON.

In general, it follows this structure.

{
  "context": {},
  "settings": {},
  "globalSettings": {},
  "styles": {
    "value": {}
  },
  "i18n": {
    "labels": {}
  },
  "tokens": {
    "em:apiKey": "<value>"
  },
  "services": {}
}

Setup JSON Sections

None of the sections (keywords) listed below are required.

By specifying and configuring a section, you are telling the system that the module needs the resource represented by that section and the shape.

Something to keep in mind, although all the sections represent settings or configurations necessary to render the module, the section specifically called Settings is so called because it defines the settings that will be exposed to being configured by the customer.

Context

This defines some valid context used to load the module.

Example:

{
  "context": {
    "airline": {
      "code": "cm"
    },
    "datasource": {
      "step": "airModule"
    },
    "geo": {
      "language": {
        "lang": "en",
        "site_edition": "en"
      }
    },
    "audience": {
      "device_category": "desktop"
    }
  }
}

Module Payload → In the mock environment you will receive that exact context as part of the Module Payload. In the live environment, that context will be replaced with other values ​​and according to where the module is rendered.

Settings

Defines the settings that will be exposed to being configured by the user and is more associated to the point of view of business, behavior or user interface.

{
  "settings": {
    "schema": {
      "properties": {}
    }
  }
}

The setup.json file uses the JSON Schema (opens in a new tab) format to define settings schema. That schema must have default values in all the settings values ​​required by the module. The specification in details is explained on the Settings Schema page.

Module Payload → In the mock environment you will receive in the settings of the Module Payload an object generated with default values ​​specified in the schema. In the live environment, that settings will be replaced by actual values ​​entered by the customer.

Styles

Defines the styles settings for the module.

{
  "styles": {
    "service": "<styles-service-name>",
    "options": {
      "type": "eds",
      "format": "json"
    }
  }
}

Internationalization (i18n)

Configuration related to internationalization

{
  "i18n": {
    "rtl": false,
    "a11y": "WCAG 2.1 AA",
    "language": "*",
    "labels": {
      "label-key-1": "English value for key 1",
      "label-key-2": "English value for key 2"
    }
  }
}

Structure:

Module Payload → In case the module is multi-language: in the simulated environment, the exact configured labels will be received through the Module Payload. In the live environment, the labels defined in the system by the customer will be received.

Tokens

Security tokens.

{
  "tokens": {
    "em:apiKey": "<some-very-very-secret-token>"
  }
}

Services

Specification of all services used by the module. The urls can be obtained from the official documentation of the APIs.

{
  "services": {
    "some-unique-and-well-known-key": {
      "endpoint": "https://services-url/path-to-services"
    },
    "em:sputnik:search": {
      "endpoint": "https://openair-dev.airtrfx.com/airfare-sputnik-service/v3/%%airlineCode%%/fares/search"
    }
  }
}

Available services:

Metadata