rightlag / aptos

:sunny: Avro, Protobuf, Thrift on Swagger

---

aptos (Avro, Protobuf, Thrift on Swagger) is a module that parses JSON Schema documents to validate client-submitted data and convert JSON schema documents to Avro, Protobuf, or Thrift serialization formats.

JSON Schema defines the media type "application/schema+json", a JSON-based format for describing the structure of JSON data.

Usage

aptos supports validating client-submitted data and generating Avro, Protobuf, and Thrift structured messages from a given JSON Schema document.

Data Validation

Given a JSON Schema document, aptos can validate client-submitted data to require that it satisfies a certain number of criteria.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "type": "object",
    "definitions": {
        "geo": {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "description": "A geographical coordinate",
            "type": "object",
            "properties": {
                "latitude": { "type": "number" },
                "longitude": { "type": "number" }
            }
        }
    },
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "number"
        },
        "name": {
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "minItems": 1,
            "uniqueItems": true
        },
        "dimensions": {
            "type": "object",
            "properties": {
                "length": {"type": "number"},
                "width": {"type": "number"},
                "height": {"type": "number"}
            },
            "required": ["length", "width", "height"]
        },
        "warehouseLocation": {
            "description": "Coordinates of the warehouse with the product",
            "$ref": "#/definitions/geo"
        }
    },
    "required": ["id", "name", "price"]
}

Validation keywords such as uniqueItems, required, and minItems can be used in a schema to impose requirements for successful validation of an instance.

import json

from aptos.util import Parser
from aptos.visitors import ValidationVisitor

record = Parser.parse('/path/to/schema')
# Valid client-submitted data (instance)
instance = {
    "id": 2,
    "name": "An ice sculpture",
    "price": 12.50,
    "tags": ["cold", "ice"],
    "dimensions": {
        "length": 7.0,
        "width": 12.0,
        "height": 9.5
    },
    "warehouseLocation": {
        "latitude": -78.75,
        "longitude": 20.4
    }
}
record.accept(ValidationVisitor(instance))

Structured Message Generation

Given a JSON Schema document, aptos can generate structured messages including Avro, Protobuf, and Thrift.

Avro

For brevity, the Product schema is omitted from the example.

import json

from aptos.util import Parser
from aptos.visitors import RecordVisitor

record = Parser.parse('/path/to/schema')
schema = record.accept(RecordVisitor())
print(json.dumps(schema, indent=2))

The preceding code generates the following Avro schema:

{
  "namespace": "aptos.visitors",
  "fields": [
    {
      "type": "long",
      "doc": "The unique identifier for a product",
      "name": "id"
    },
    {
      "type": {
        "items": "string",
        "type": "array"
      },
      "doc": "",
      "name": "tags"
    },
    {
      "type": {
        "namespace": "aptos.visitors",
        "fields": [
          {
            "type": "long",
            "doc": "",
            "name": "latitude"
          },
          {
            "type": "long",
            "doc": "",
            "name": "longitude"
          }
        ],
        "type": "record",
        "doc": "A geographical coordinate",
        "name": ""
      },
      "doc": "A geographical coordinate",
      "name": "warehouseLocation"
    },
    {
      "type": "string",
      "doc": "",
      "name": "name"
    },
    {
      "type": {
        "namespace": "aptos.visitors",
        "fields": [
          {
            "type": "long",
            "doc": "",
            "name": "width"
          },
          {
            "type": "long",
            "doc": "",
            "name": "height"
          },
          {
            "type": "long",
            "doc": "",
            "name": "length"
          }
        ],
        "type": "record",
        "doc": "",
        "name": ""
      },
      "doc": "",
      "name": "dimensions"
    },
    {
      "type": "long",
      "doc": "",
      "name": "price"
    }
  ],
  "type": "record",
  "doc": "",
  "name": "Product"
}