JSON Schema Validator service

This repository contains a JSON Schema validator for the EMBL-EBI Submissions Project. This validator runs as a standalone node server that receives validation requests and gives back it's results.

This service uses Elixir's JSON schema validator library.

The validation is done using the AJV library version ^6.0.0 that fully supports the JSON Schema draft-07.

Contents

• Getting Started

• Prerequisites

• Installing

• Running the Tests

• Executing

• Executing with Docker

• Development

• Validation API

• Usage

• API Errors

• Custom keywords

• License

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

To be able to run this project you'll need to have Node.js and npm installed in your machine. npm is distributed with Node.js which means that when you download Node.js, you automatically get npm installed on your computer.

Installing

Node.js / npm

• Get Node.js: https://nodejs.org/en/ (v8.11.1 LTS)

• If you use Homebrew you can install node by doing:

brew install node

After installation check that everything is correctly installed and which versions you are running:

node -v
npm -v

Project

Clone project and install dependencies:

git clone https://github.com/EMBL-EBI-SUBS/json-schema-validator.git
cd json-schema-validator
npm install

Running the Tests

npm test

Executing

node src/server

The node server will run on port 3020 and will expose one endpoint: /validate.

Startup arguments

• logPath

If provided with a log path argument, the application will write the logs to a file on the specified directory with a 24h rotation. To provide the log path add a logPath property after the startup statement:

node src/server --logPath=/log/directory/path

• pidPath

If provided with a pid file path argument, the application will write the pid into the specified file. If no pid file argument is provided, the application will still create a pid file on the default path: ./server.pid. To provide the pid file path add a pidPath property after the startup statement:

node src/server --pidPath=/pid/file/path/server.pid

Note: This is the file path and not just the directory it will be written to.

Executing with Docker

1. Build docker image:

docker build -t subs/json-schema-validator .

2. Run docker image:

docker run -p 3020:3020 -d subs/json-schema-validator

Development

For development purposes using nodemon is useful. It reloads the application everytime something has changed on save time.

nodemon src/server

Validation API

This validator exposes one single endpoint that will accept POST requests. When running on you local machine it will look like: http://localhost:3020/validate.

Usage

The endpoint will expect the body to have the following structure:

{
  "schema": {},
  "object": {}
}

Where the schema should be a valid json schema to validate the object against. You also have to add this value to the header of the request:

Content-Type: application/json

Example: Sending a POST request with the following body:

{
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    
    "type": "object",
    "properties": {
      "alias": {
        "description": "A sample unique identifier in a submission.",
        "type": "string"
      },
      "taxonId": {
        "description": "The taxonomy id for the sample species.",
        "type": "integer"
      },
      "taxon": {
        "description": "The taxonomy name for the sample species.",
        "type": "string"
      },
      "releaseDate": {
        "description": "Date from which this sample is released publicly.",
        "type": "string",
        "format": "date"
      }
    },  
    "required": ["alias", "taxonId" ]
  },
  "object": {
    "alias": "MA456",
    "taxonId": 9606
  }
}

will produce a response like:

HTTP status code 200

[]

An example of a validation response with errors:

HTTP status code 200

[
  {
    "errors": [
        "should have required property 'value'"
    ],
    "dataPath": ".attributes['age'][0].value"
  },
  {
    "errors": [
        "should NOT be shorter than 1 characters",
        "should match format \"uri\""
    ],
    "dataPath": ".attributes['breed'][0].terms[0].url"
  }
]

Where errors is an array of error messages for a given input identified by its path on dataPath. There may be one or more error objects within the response array. An empty array represents a valid validation result.

API Errors

Sending malformed JSON or a body with either the schema or the submittable missing will result in an API error (the request will not reach the validation). API errors have the following structure:

HTTP status code 400

{
  "error": "Malformed JSON please check your request body."
}

Custom keywords

The AJV library supports the implementation of custom json schema keywords to address validation scenarios that go beyond what json schema can handle.

The list of implemented custom keywords could be found in the Elixir's JSON Schema Validator library's documentation.

License

For more details about licensing see the LICENSE.