Snowplow engineering technical test instructions

snowplow-tech-test-go.md

Snowplow engineering technical test instructions - JSON validation service in Go

Using this specification you will need to build a REST-service for validating JSON documents against JSON Schemas. This REST-service should allow users to upload JSON Schemas and store them at unique URI and then validate JSON documents against these URIs. Additionally, this service will "clean" every JSON document before validation: remove keys for which the value is null. Client-side software as well as GUI is out of scope of this specification - user can choose any tool able to communicate via HTTP like curl or write their own.

Required knowledge

This test requires some knowledge of JSON Schemas. You can find the full specification and examples on the official web site. However, a quick look at the tutorial should be enough to familarize yourself with this tool. You will also need a very basic understanding of the RESTful architecture. Knowledge of git and GitHub are also required.

Programming language

To accomplish this task we requet that you write your code in Go.

Other tools

The application should not include an implementation of a JSON schema validator, a 3rd-party library can be used for this purpose. We recommend jsonschema for your Go application. This validator has the necessary features needed in this project. You're free to include any other library or framework that you deem useful.

API Specification

The primary interface of application is REST (JSON over HTTP).

Endpoints

POST    /schema/SCHEMAID        - Upload a JSON Schema with unique `SCHEMAID`
GET     /schema/SCHEMAID        - Download a JSON Schema with unique `SCHEMAID`
POST    /validate/SCHEMAID      - Validate a JSON document against the JSON Schema identified by `SCHEMAID`

Responses

All possible responses should be valid JSON documents.

Valid JSON Schema Upload

This should contain Schema id, action and status.

{
    "action": "uploadSchema",
    "id": "config-schema",
    "status": "success"
}

Invalid JSON Schema Upload

It isn't necessary to check whether the uploaded JSON is a valid JSON Schema v4 (many validation libraries dont allow it), but it is required to check whether the document is valid JSON.

{
    "action": "uploadSchema",
    "id": "config-schema",
    "status": "error",
    "message": "Invalid JSON"
}

JSON document was successfully validated

{
    "action": "validateDocument",
    "id": "config-schema",
    "status": "success"
}

JSON document is invalid against JSON Schema

The returned message should contain a human-readable string or machine-readable JSON document indicating the error encountered. The exact format can be chosen based on the validator library's features.

{
    "action": "validateDocument",
    "id": "config-schema",
    "status": "error",
    "message": "Property '/root/timeout' is required"
}

Use case

Schema validation

The potential user has a configuration JSON file config.json like the following:

{
  "source": "/home/alice/image.iso",
  "destination": "/mnt/storage",
  "timeout": null,
  "chunks": {
    "size": 1024,
    "number": null
  }
}

And expects it conforms to the following JSON Schema config-schema.json:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "source": {
      "type": "string"
    },
    "destination": {
      "type": "string"
    },
    "timeout": {
      "type": "integer",
      "minimum": 0,
      "maximum": 32767
    },
    "chunks": {
      "type": "object",
      "properties": {
        "size": {
          "type": "integer"
        },
        "number": {
          "type": "integer"
        }
      },
      "required": ["size"]
    }
  },
  "required": ["source", "destination"]
}

To check that it really fits the schema:

1. The user should upload the JSON Schema: curl http://localhost/schema/config-schema -X POST -d @config-schema.json
2. The server should respond with: {"action": "uploadSchema", "id": "config-schema", "status": "success"} and status code 201
3. The user should upload the JSON document to validate it curl http://localhost/validate/config-schema -X POST -d @config.json
4. The server should "clean" the uploaded JSON document to remove keys for which the value is null:

   {
     "source": "/home/alice/image.iso",
     "destination": "/mnt/storage",
     "chunks": {
       "size": 1024
     }
   }

5. The server should respond with: {"action": "validateDocument", "id": "config-schema", "status": "success"} and status code 200

Other requirements

• Restarting the application should have no effect regarding the previously uploaded JSON Schemas.
• Exceptional cases should be handled.
• Unexpected requests (such as invalid URIs) should be processed according to the RESTful architecture.

Note on performance

For our purposes, the performance of the application is not a key requirement. An understandable architecture and clean abstractions should be chosen over micro-enhancements in performance. However, performance shouldn't deteriorate because of inappropriate data structures or poor algorithms.

End result

As end result of this test, you should:

• publish the code with the associated commit history to a public repository
• describe in the README the neccessary steps to build and run the service Good luck.