jsonbp

jsonbp (JSON BluePrint) is a library for serializing and deserializing JSON to and from Python based on schemas. While json-schema and its implementations offer a more mature and widely used technique, a different approach was desired, which led to the development of this library.

jsonbp's main design goals were:

• schema reuse through import / type system
• custom user definable primitive types
• built in numeric fixed precision type which deserializes into Python's Decimal
• built in datetime type which deserializes into Python's datetime
• error reporting with support for localization
• support for enums
• easy to integrate and use

Brief Introduction

• Schema definition
• Usage
• Requirements and Dependencies
• Installation
• Documentation

Schema definition

jsonbp uses its own (very simple) domain language to define a schema. Here's a simple example:

root {
  x: Float (min=0.0),
  y: Float (min=0.0, max=1.0),

  optional Color: {
    RED,
    GOLD,
    GREEN
  }
} [minLength=2]

This defines a schema that represents an array of minimum length 2 whose elements contain the fields 'x' and 'y', where both 'x' and 'y' are not allowed to be negative and further 'y' is not allowed to be greater than 1.0. An optional field 'color' can also exist, and if present it needs to be either "RED", "GOLD" or "GREEN". A JSON instance that obeys this schema is thus:

[
  {
    "x": 2.0,
    "y", 0.004,
    "color": "RED"
  },

  {
    "x": 3.0,
    "y", 0.009
  },

  {
    "x": 4.0,
    "y", 0.016,
    "color": "GREEN"
  }
]

jsonbp offers the following directives to organize a schema:

• "root" -> defines which type will correspond to some JSON
• "type" -> defines specialized (restricted) simple types
• "object" -> specifies the contents of compound types (Objects)
• "enum" -> defines a list of allowed values for a given field
• "import" -> reuses directives from existing blueprints

These structures can be employed to simplify and make the schema more modular. In the above example, one could split the definitions and get something more reusable, like the following:

type NonNegative : Float (min=0.0)
type Normalized : NonNegative (max=1.0)

object Coordinates {
  x: NonNegative,
  y: Normalized
}

include "color.jbp"
object ColoredCoordinates extends Coordinates {
  optional color: Color
}

root ColoredCoordinates[minLength=2]

where the contents of file "color.jbp" would be:

enum Color {
  RED,
  GOLD,
  GREEN
}

NOTE: For full documentation, see Documentation

Usage overview

Schema parsing

• jsonbp.load_file(blueprint_path: str) => JsonBlueprint
• jsonbp.load_string(blueprint_string: str) => JsonBlueprint

JSON deserialization

• JsonBlueprint.deserialize(contents: str) => (success: bool, outcome: object)
• JsonBlueprint.serialize(payload: object) => str

Example

import jsonbp

blueprint = jsonbp.load_string('''
root {
  success: {
    YES,
    NO
  }
}
''')

jsonInstance = '{ "success": "YES" }'
success, outcome = blueprint.deserialize(jsonInstance)
print(f'Success: {success}')
print(f'Outcome: {outcome}')

Output:

Success: true
Outcome: {"success":"YES"}

NOTE: For full documentation, see Documentation

Requirements and Dependencies

jsonbp requires Python 3.11+, that's it. Under the hood, jsonbp uses PLY for its schema parsing. PLY comes included with jsonbp already, there's no need to download it separately.

Installation

jsonbp is available at PyPI: https://pypi.org/project/jsonbp/

To install through pip:

pip install jsonbp

Documentation

• Full documentation
• Sample of using jsonbp in Flask