# 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.

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

1
2
3
4
5
6
7
8
9
10

# 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.

# download and build the airnode monorepo
git clone git@github.com:api3dao/airnode.git
cd airnode
yarn run bootstrap
yarn run build
cd packages/airnode-validator
# execute the validator
yarn run cli:validator --template="config" --specs="exampleSpecs/config.json"
# validator output
{
  "valid": true,
  "messages": []
}

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

# 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 when the template does not contain a specific version (i.e., --template="config"). If a specific version is needed it can be appended to template argument (i.e., --template="config@0.3").

# 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 fields within the config.json and must be in separate files to be validated.

# Validates a completed config.json file.
npx @api3/airnode-validator --template="config" --specs="myProject/config/config.json"
# Here (optionally) the OIS object from config.json is in a separate file.
npx @api3/airnode-validator --template="OIS" --specs="myProject/config/OIS-spec.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 field that has been placed in a file separate from its config.json file. The ois field contains the mapping between an API and Airnode endpoints. (interpolation with an env file is supported)

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

# apiSpecifications

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

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

# endpoints

The following code example validates an ois.endpoints field that has been placed in a file separate from its config.json file. The ois.endpoints field are Airnode endpoints that map to the ois.apiSpecifications field in config.json. (interpolation with an env file is supported)

npx @api3/airnode-validator --template="apiSpecifications" --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 →