Why Vazen TOML?

Reading your own plans takes a licence

Product and transaction data have long had open standards. Shelf data has none. How products are arranged on fixtures lives in planning software with proprietary file formats, and reading your own planograms requires a licence for the software that wrote them.

Every analytics pipeline, model or agent that needs shelf data pays that cost again: another licensed seat, a specialist integration or someone exporting by hand. The format becomes a recurring cost, and the software vendor decides who else can use your data.

A published, open format gives the data a life beyond the application that created it. Retailers and brands choose how to analyse it, which partners see it and which tools to build around it.

Every new tool rebuilds the shelf

Reading the file is only the first step. Every analytics pipeline, simulation and agent also needs a model of products, equipment and placements. Each team invents its own, with its own quirks and limits.

AI makes this even more acute. Every time an agent is asked to read or write a plan, another representation is born. Agents can generate parsers quickly, but those parsers still have to agree on what the data means if you want systems that work together.

A shared format makes these tools interoperable and additive: a standard language for your agent to talk to my agent about the shelf. Each application remains free to decide what it does with the plan.

A product is not its barcode

Pack designs and products without a GTIN

Space-planning software has keyed products on a unique code since the 1980s, when master data was one row per code and a planogram existed to be executed in a store that would scan it. In the context of a single retailer, that made total sense.

The same tools are now asked questions they were never designed to answer. A brand tests four pack designs on one shelf. A retailer builds plans with a product before it’s given an ID. The general perils of copy paste. By GS1’s own rules a new pack design needs no new GTIN, so four designs legitimately carry one code.

When the code is the key, every one of these forces the same workaround:

500000000001
500000000001_new1
500000000001_new2

Vazen TOML does not rely on unique ids and is much better for it.

Any fixture, any field

A chiller holds shelves above baskets. A pegboard sits inside a bay and carries hooks. A display unit stands inside another fixture. The file is written as the fixture is built: a fixture holds equipment, equipment holds equipment or sites, and the tree goes as deep as the physical object does. In a layout every element carries its position and dimensions in the fixture’s frame, so one recursive walk renders a two-shelf end or a forty-bay aisle.

Equipment types are open. The specification fixes the data and deliberately leaves behaviour to the software that reads it.

Your existing product data already fits

Your master data drops straight in: the same GTINs, millimetres and six product faces. No re-keying, no translation, no competing version of the facts. Your own fields travel under their own names, and a tool’s data travels under its namespace.

Product images are URLs, so a plan stays one self-contained text file that renders anywhere its images can be reached.

Why the format works this way

Readable text and a published contract

TOML is readable as text and has parsers in many languages. The Vazen specification supplies what TOML cannot: the meanings, units, references and rules of a planogram. A TOML parser checks the syntax; a Vazen implementation also checks that contract.

Planning intent and resolved geometry

A vazen/spec document can leave placement decisions open. A vazen/layout document records resolved geometry. Tools can exchange either planning requirements or a finished arrangement.

Round trips that keep what you added

Extensions carry information beyond the shared core. A consumer that writes a file back must preserve every key it does not understand, and that rule is what makes round trips to and from other formats work. A converter must still declare the source formats it supports and what it preserves.

Importing a plan, checking its geometry and repairing it are separate operations. Moving a product to fix an overlap changes the plan, so that decision must be explicit.

Read the specification or explore PSA conversion and round-trip limits.

Get involved

Read the example shelf and tell us what your team needs to do with shelf data. We want to hear from retailers, brands, engineers and researchers working on real planning problems. We can help you get started, share sample files and talk through your use case.

The specification is free to use, with no fee. Vazen maintains the project, and the current specification is 0.3.0. The stated aim is neutral, independent governance as the format matures.

The JavaScript/TypeScript package is on npm. It reads and writes Vazen TOML, JSON and PSA files. An independent Python implementation and a web converter and visualiser are planned. The software is licensed under Apache 2.0 and the specification under CC BY 4.0; see the licensing terms↗ (opens in a new tab).

It’s time to rescue the shelf data.

Contribute your ideas or follow on GitHub↗ (opens in a new tab).