Skip to content
Validator micro-service for Open Referral data resources
JavaScript Dockerfile
Branch: master
Clone or download
Latest commit f39fb9d Aug 2, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Updated docs Feb 27, 2019
src bugfix: 400 is returned for all requests that don't pass validation Feb 27, 2019
test Removed Babel completely Jan 17, 2019
.babelrc Initial commit Jan 11, 2019
.dockerignore Initial commit Jan 11, 2019
.eslintignore Initial commit Jan 11, 2019
.eslintrc Initial commit Jan 11, 2019
.gitignore Added documentation Feb 14, 2019 chore(release): 1.0.1 Feb 27, 2019
Dockerfile Major refactoring Jan 14, 2019
LICENSE Initial commit Jan 11, 2019 Update Aug 2, 2019
package.json chore(release): 1.0.1 Feb 27, 2019

Open Referral - Validator microservice

Visit Project Github page.

A micro-service with a RESTful API for validating data packages and resources using the official Human Services Data Specification from Open Referral. Thanks to @spilio for development of this tool.

Running the service

Running as a Docker container

You need to have Docker service installed on your local machine or any other target host.

Pulling the image from Docker Hub

The fastest way to get started is to pull the latest pre-built image from the Docker Hub registry by running:

$ docker pull openreferral/validator

Building the image locally

Otherwise you can build the image on your local machine by running the following command within the project's directory:

$ docker build --tag "openreferral/validator:latest" .

Running the service container

After the Docker image is available you can launch a container by running:

$ docker run -d --network=host --name=openreferral-validator openreferral/validator:latest

You can use any name you want, by replacing the "openreferral-validator" value with one of your choice. The container will bind to localhost:1400 by default. You can change the host and port of the container by setting the HOST and PORT environment variables like so:

$ docker run -d --network=host -e HOST=localhost -e PORT=1300 --name=openreferral-validator openreferral/validator:latest

Once the container is launched, you can stop it and start / restart it on demand like so

$ docker stop openreferral-validator
$ docker restart openreferral-validator

Running locally with NodeJS

In order to run the project locally you need to have the latest NodeJS and npm installed.

Once your environment is all set up, clone the repository, go into the root directory and install all dependencies by running

$ npm install

Once all the dependencies have been downloaded, run the application with

$ npm start

Using the validator service

Once the service has been launched you can verify that the API is up by hitting http://localhost:1400/health. If everything is ok you should get a blank page (or a 200 response).

OpenAPI definition

The micro-service has an OpenAPI 2.x compliant definition that is automatically generated on startup. You can find the OpenAPI (Swagger) definition here http://localhost:1400/swagger. You can parse the OpenAPI definition with any popular API tool like Swagger, Postman, etc and start interacting with the service.

API operations

GET /health


Returns a 200 OK response

GET /validate/datapackage


Validate an HSDS data package. The operation requires the URI of valid datapackage.json file to be provided as a query parameter. The service will parse the contents of the data package and try to validate all enlisted resources.

Query parameters

  • uri: A valid local or remote URI of a datapackage.json descriptor file.
  • relations: (optional) A boolean flag indicating whether to enable data relations check through defined foreign keys - default is false


The operation returns a collection of validation results, one per resource as defined within the data package descriptor.

Example call

Given we have a sample datapackage.json file at that contains a small subset of resources, we can run the following command to validate the contained resources:

$ curl 'http://localhost:1400/validate/datapackage?uri='

If all data resources are valid, the service will return a response like:

  "valid": true,
  "resource": "organization"
}, {
  "valid": true,
  "resource": "program"

In case something is wrong, the response would be something like:

        "valid": true,
        "resource": "organization"
        "valid": false,
        "errors": [
                "row": 3,
                "description": "Foreign key \"organization_id\" violation in row 3"
        "resource": "program"

POST /validate/csv


Validate an HSDS data resource file. The operation validates an uploaded CSV data stream using the definition of a specified resource as found in the standard Open Referral data packagespecification. Clients should send a form payload containg a type field with the name of the HSDS logical resource and a file that contains the CSV data stream.


  • multipart/form-data


  • type: A valid HSDS resource name, e.g. contact
  • file: The CSV file to be validated

Example call

$ curl -F 'type=contact' -F 'file=@/home/chris/contacts.csv' 'http://localhost:1400/validate/csv'

A successful validation would return something like:

    "valid": true,
    "errors": []

Sample data sets

You can test drive the validator using the HSDS sample data sets found in the dedicated Github repository. Clone the repository or download as a ZIP archive and extract them locally.

You can’t perform that action at this time.