Skip to content

README.md

Latest commit

 

History

History
180 lines (122 loc) · 4.95 KB

README.md

File metadata and controls

180 lines (122 loc) · 4.95 KB

Open Origin JSON (OOJ)

Spec License: CC-BY 4.0 Client License: MIT Spec Version: 0.5.0 Status: Stable

Open Origin JSON (OOJ) is an open, human-readable data specification for describing origin, provenance, and traceability in small and medium-scale supply chains.

It is designed for farms, food producers, processors, co-ops, and local manufacturers who need real traceability without enterprise software, blockchains for the sake of blockchains, or unreadable compliance formats.

OOJ is used in production by VeriBatch, an open traceability platform built by Booth Farm Enterprises Ltd.

This repository contains:

  • 📜 The Open Origin JSON specification (the primary artifact)
  • 🐍 A Python client library (a convenience and reference implementation)

Why Open Origin JSON?

Most traceability standards are built top-down, for regulators or multinational logistics systems. OOJ is built bottom-up, from the perspective of the person actually making the food or product.

OOJ aims to be:

  • Readable: Plain JSON, understandable without special tooling
  • Composable: Small records that link together naturally
  • Practical: Matches how producers actually think about batches and processes
  • Open: No vendor lock-in, no hidden schemas
  • Extensible: Works alongside GTINs, SKUs, certificates, photos, and external systems

It is intentionally not a database schema, a blockchain, or a runtime system. It is a shared language.

📜 Specification

The specification is the heart of this project.

The spec defines a small set of core entities:

  • Actor – who did the work
  • Location – where it happened
  • Item – what exists conceptually
  • Batch – a specific, traceable instance
  • Process – how transformation occurs
  • Event – what actually happened
  • Link – how batches connect across actors

Together, these form a directed provenance graph that can be serialized, exchanged, archived, or verified.

🐍 Python Client (Reference Implementation)

The included Python package provides a convenient, type-safe way to work with OOJ, but it is intentionally optional.

You do not need this client to use the specification.

Installation

pip install open-origin-json
Or from source:

```bash
git clone https://github.com/boothfarm/open-origin-json.git
cd open-origin-json
pip install -e .

Quick Example

from ooj_client import Actor, Item, Batch, Quantity, to_json

actor = Actor(
    id="bfe",
    name="Booth Farm Enterprises Ltd.",
    kind="producer"
)

item = Item(
    id="pickled-garlic",
    actor_id="bfe",
    name="Pickled Garlic (500ml)",
    category="finished_good"
)

batch = Batch(
    id="pg-2025-01",
    actor_id="bfe",
    item_id="pickled-garlic",
    quantity=Quantity(amount=42, unit="jar_500ml"),
    production_date="2025-07-20",
    best_before_date="2027-07-20"
)

print(to_json(batch, indent=2))

Design Philosophy

OOJ follows a small set of non-negotiable principles.

  • Events create truth
    Batches do not magically change, events explain why they change.

  • Links cross organizational boundaries
    Traceability must survive handoffs between independent actors.

  • Loss and disposal are first-class concepts
    Real supply chains leak, spoil, and get thrown out, pretending otherwise produces fiction.

  • Human comprehension matters
    If a farmer cannot read the JSON, the system has already failed.

Relationship to VeriBatch

Open Origin JSON is the underlying data model used by VeriBatch, but the specification itself is vendor-neutral.

Anyone can:

  • Implement OOJ in another language
  • Store OOJ documents in any database or file system
  • Exchange OOJ data without using VeriBatch
  • Build tools that interoperate with VeriBatch

VeriBatch exists to make OOJ useful at scale, not to own it.

🏗️ Development

Tests

pip install -e ".[dev]"
pytest

Formatting and Typing

black ooj_client tests
mypy ooj_client

⚖️ License

This project is intentionally dual-licensed.

  • Specification
    Open Origin JSON is licensed under CC-BY 4.0.
    You may share and adapt the specification with attribution.

  • Python Client
    The reference implementation is licensed under the MIT License.

🤝 Contributing

Contributions are welcome, especially:

  • Specification clarifications and edge cases
  • Real-world examples from producers
  • Client implementations in other languages
  • Documentation improvements

OOJ grows best when it is grounded in reality.

Booth Farm Enterprises Ltd.
Open traceability, built from the ground up.