Barcodes

The JSON payloads encoded into physical barcodes

A barcode carries a JSON payload that describes what it represents. Each payload is versioned and validated against a fixed schema — a barcode that does not match is rejected. This page documents each barcode contract, its schema, and how to encode it.

Box barcode

A box barcode records the contents of a physical box — the products and quantities being put away. Every box barcode is a boxContents payload.

type must be exactly boxContents, or the barcode is rejected. The match is strict: any surrounding whitespace such as {"type":" boxContents",…} is also rejected.
version must be specified. Only version 1 is currently supported.
lpn (License Plate Number) is optional — an identifier for the physical container.

General schema

Box barcode — general schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "type",
    "version",
    "items"
  ],
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "description": "Must be 'boxContents'"
    },
    "version": {
      "type": "integer"
    },
    "items": {
      "type": "array",
      "minItems": 1
    },
    "lpn": {
      "type": "string",
      "description": "License Plate Number — optional identifier for the physical container"
    }
  }
}

Item schema (version 1)

Item schema — v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "s",
    "q"
  ],
  "additionalProperties": false,
  "properties": {
    "s": {
      "type": "string",
      "minLength": 1,
      "description": "Product SKU"
    },
    "q": {
      "type": "integer",
      "minimum": 1,
      "description": "Quantity of this product being put away"
    }
  }
}

Full schema (version 1)

Box barcode — v1 combined schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "type",
    "version",
    "items"
  ],
  "additionalProperties": false,
  "properties": {
    "type": {
      "const": "boxContents"
    },
    "version": {
      "const": 1
    },
    "lpn": {
      "type": "string",
      "description": "License Plate Number — optional identifier for the physical container"
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "s",
          "q"
        ],
        "additionalProperties": false,
        "properties": {
          "s": {
            "type": "string",
            "minLength": 1,
            "description": "Product SKU"
          },
          "q": {
            "type": "integer",
            "minimum": 1,
            "description": "Quantity of this product being put away"
          }
        }
      }
    }
  }
}

Example

Box barcode example

{
  "type": "boxContents",
  "version": 1,
  "items": [
    {
      "s": "OI-Ergonomic-936567",
      "q": 1
    },
    {
      "s": "OI-Detachable-828344",
      "q": 2
    }
  ]
}

Encoding

When encoding the JSON for printing, emit no whitespace to maximize the barcode's capacity:

Compact encoding (no whitespace)

{
  "type": "boxContents",
  "version": 1,
  "items": [
    {
      "s": "OI-Ergonomic-936567",
      "q": 1
    },
    {
      "s": "OI-Detachable-828344",
      "q": 1
    }
  ]
}

The barcode can be printed as a DataMatrix, PDF417, or QR Code.