# Validator

Table of Contents

The airnode-validator (opens new window) package, known as the validator, is used by the Docker Images to validate the configuration files you provide when deploying an Airnode. You can also use the validator to check the configuration files for correct formatting and other issues while creating them.

# Usage

The validator's commands can be run using npx (opens new window), installing a global npm package, the validator SDK or by manually building the validator package. Using npx is the simplest method to interact with the validator.

# Using npx

The validator package can be run as an npm package using npx. This allows you to run validator commands without installing the validator npm package or having to manually build the validator package yourself.

npx @api3/airnode-validator api3-validator --template="config" --specs="config.json"

# Global Package

The validator package can be installed globally with yarn or npm. If installed using yarn make sure yarn bin is added to PATH.

yarn global add @api3/airnode-validator
# OR
npm install @api3/airnode-validator -g
# Executing the validator.
api3-validator --template="config" --specs="config.json"

1
2
3
4
5
6

# Use the SDK

The validator package exports useful functions for validation. In the output valid is set to true when there are no errors, however there could be warnings in the messages. The validator uses the latest template unless a template version is applied.

const validator = require('@api3/airnode-validator');
// Using the latest template.
console.log(
  validator.validateWithTemplate('exampleSpecs/config.specs.json', 'config')
);
// Using a versioned template.
console.log(
  validator.validateWithTemplate('exampleSpecs/config.specs.json', 'config@0.5')
);
# Outputs json
{
  valid: boolean,
  messages: { level: "error" | "warning", message: string }[]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Build Manually

You can clone and build the Airnode monorepo then run the validator as a yarn script from inside the packages/airnode-validator directory. The instructions to do so are in the monorepo validator package README (opens new window).

# Examples

The validator is based on two primary arguments to function. The --template argument describes the content type to validate. Secondly the --specs argument which requires a file containing the content to validate.

npx @api3/airnode-validator --help
Options:
      --help                    Show help                              [boolean]
      --version                 Show version number                    [boolean]
  -t, --template                Path to validator template file or name of
                                airnode specification format           [string] [required]
  -s, --specification, --specs  Path to specification file that will be
                                validated                              [string] [required]
  -i, --secrets                 Path to .env file that will be interpolated with
                                specification                          [string]

1
2
3
4
5
6
7
8
9
10
11

For the --template argument use one of the following values which are case-insensitive.

The validator will automatically validate the latest available version of a template (i.e., --template="config") when the template does not contain a specific version . If a specific version is needed it can be appended to the template argument (i.e., --template="config@0.3"). You can see the different template versions (opens new window) in the validator package of the Airnode monorepo.

# config

The following code example validates a config.json file. This is the most common validation use case. The other templates (apiSpecifications, endpoints, OIS) support objects within the config.json and must be in separate files to be validated.

# Validates a completed config.json file using the latest template version.
npx @api3/airnode-validator --template="config" --specs="myProject/config/config.json"
# Uses the 0.5 template version.
npx @api3/airnode-validator --template="config@0.5" --specs="myProject/config/config.json"

1
2
3
4
5

You will most likely keep secrets in a file separate from the config.json file. Using interpolation with an env file is supported using the --secrets argument.

npx @api3/airnode-validator --template="config" --secrets="secrets.env" --specs="myProject/config/config.json"

# OIS

The following code example validates an OIS object that has been placed in a file separate from a config.json file. The OIS object contains the mapping between an API and Airnode endpoints. Interpolation with an env file is supported.

# Validates an OIS object from an ois-spec.json file.
npx @api3/airnode-validator --template="OIS" --specs="myProject/config/ois-spec.json"

1
2

# apiSpecifications

The following code example validates an ois.apiSpecifications object that has been placed in a file separate from a config.json file and its parent object ois. The ois.apiSpecifications object defines/specifies the API Airnode will call. Interpolation with an env file is supported.

npx @api3/airnode-validator --template="apiSpecifications" --specs="myProject/config/apiSpecifications.json"

# endpoints

The following code example validates an ois.endpoints object that has been placed in a file separate from a config.json file and its parent object ois. The ois.endpoints object contains Airnode endpoints that map to the ois.apiSpecifications object. Interpolation with an env file is supported.

npx @api3/airnode-validator --template="endpoints" --specs="myProject/config/endpoints.json"

# Output

The validator provides the following output.

// Default output
{
  "valid": boolean,
  "messages": [
    {
      "level": "error" | "warning",
      "message": string
    }
  ],
  "output": object
}

1
2
3
4
5
6
7
8
9
10
11

← Deployer Airnode Contract Addresses →