from teleport import t, Undefined

TODO = t({"Struct": {
            "required": {"text": "String"},
            "optional": {"deadline": "DateTime",
                         "tags": {"Array": "String"}}}})

For validation & serialization:

>>> TODO.from_json({
...     'text': 'Return videotapes',
...     'deadline': '2014-10-14T21:17:00Z',
...     'tags': ['movies']
... })
{'deadline': datetime.datetime(2014, 10, 14, 21, 17, tzinfo=<UTC>),
 'tags': [u'movies'],
 'text': u'Return videotapes'}

For API servers:

def add_todo(request):
    try:
        todo = TODO.from_json(request.json)
    except Undefined:
        raise BadRequest("Invalid JSON data")
    Todo.create(**todo)

For API clients:

def add_todo(**todo):
    payload = json.dumps(TODO.to_json(todo))
    requests.post('http://api.example.com/todos', data=payload)

Teleport is a tiny JSON type system. You can use it for:

  • Validating input
  • Building JSON serializers
  • Building API servers and clients
  • Auto-generating API documentation

Principles:

  • Minimalism (< 1000 LOC)
  • Portability and extensibility
  • Language-agnostic specification
  • Enforces existing conventions
  • Open Source (MIT license)

Compatibility

At this stage in development, incrementing the minor version (0.x) signifies a breaking change in the implementation.

Specification Python implementation
draft-02 0.4.0 (docs)
draft-01 0.3.1 (docs)
draft-00 0.3.0 (docs)
1.0 (obsolete) 0.2.1 (docs)

Development

Source code, specification as well as this site are all in a single git repository.

Use the issue tracker to report bugs and offer suggestions. Join the discussion or email the author directly.

Teleport is very new and needs all kinds of help: from reviewing the specification, to suggesting features, to porting it to new programming languages.