Crate binary_data_schema[][src]

Binary Data Schema (BDS) is an extension of JSON schema. With this extension it is possible to convert JSON documents into raw bytes and reverse.

The intention is to use BDS in WoT Thing Descriptions in order to allow application/octet-stream as a content type for forms.


Following a list of all types that can be encoded. The list may not be exhaustive. Further explanation can be found in the description of the respective modules.

  • Boolean values (true, false)
  • Integer values:
    • Length 1 to 8 bytes
    • Big and Little Endianness
    • Signed or unsigned
  • Number values:
    • Single and double precision according to IEEE 754
    • Via linear transformation (value / scale - offset) encoding as integer
  • Boolean, integer and numeric values can be encoded as bitfields (cover only a certain number of bits instead of whole bytes)
  • Object and array schemata allow for encoding complex data structures
  • UTF-8 strings
  • Hex-encoded strings (regex: ^[0-9a-f]{2}*$)
  • Variable sized values, i.e. strings and arrays, have different ways to define their length:
    • Fixed size
    • Explicit length → Length of the value is encoded at the beginning of the value
    • End pattern → The end of the value is marked by a sentinel value, like in C with \0
    • Capacity → A fixed space is reserved. Unused space is filled with padding
    • Till end → The value continues until the end of the message


The specific features for each schema are explained in their sub module:

Each feature is explained with an example. The examples follow the same structure as the (commented) default example below.

BDS is by far not feature complete. If you do not find a feature described it is probably safe to assume that it is not yet implemented. If you require a specific feature file an issue, please. PRs are also welcome.


The only feature described on this level is default.

In general binary protocols often have some kind of magic start and end bytes. To simulate those BDS uses the default keyword. When encoding a JSON document fields whose schema has a default value those do not have to be provided.

  • Fields with default are not required for encoding but included when decoded.
  • To keep BDS aligned with JSON schema it is recommended to add "required" to object schemata.


let schema = json!({
    "type": "object",
    "properties": {
        "start": {
            "type": "string",
            "format": "binary",
            "minLength": 2,
            "maxLength": 2,
            "default": "fe",
            "position": 1
        "is_on": {
            "type": "boolean",
            "position": 5
        "end": {
            "type": "string",
            "format": "binary",
            "minLength": 2,
            "maxLength": 2,
            "default": "ef",
            "position": 10
    "required": ["is_on"]
let mut scope = json_schema::Scope::new();
// Valid JSON schema
let j_schema = scope.compile_and_return(schema.clone(), false)?;
// Valid Binary Data schema
let schema = from_value::<DataSchema>(schema)?;

let value = json!({ "is_on": true });
// 'value' is valid for the JSON schema
let mut encoded = Vec::new();
// 'value' is valid for the Binary Data schema
schema.encode(&mut encoded, &value)?;

let mut encoded = std::io::Cursor::new(encoded);
let back = schema.decode(&mut encoded)?;
let expected = json!({
    "start": "fe",
    "is_on": true,
    "end": "ef"
// The retrieved value is valid for the JSON schema
// The retrieved value is as expected
assert_eq!(back, expected);



Implementation of the array schema


Implementation of the boolean schema.


Implementation of the integer schema


Implementation of the number schema


Implementation of the object schema


Implementation of the string schema



The data schema is the typical type users will interact with.



Order of bytes within a field.


Errors from binary serialization.


The inner data schema without special features like "default".


The way the length of a variable length field is specified in an array or string schema.



A schema to de-serialize a value from bytes.


A schema to serialize a value to bytes.

Type Definitions