# Vazen TOML

> Vazen TOML is an open file format for planogram data: the products, fixtures, equipment and product placements of a retail shelf, written as plain TOML 1.0 with the extension `.vazen.toml`.

Any standard TOML parser reads a Vazen TOML file. A file declares one of two stages of a plan in its `schema` field: `vazen/layout`, where every physical element has a position and dimensions, or `vazen/spec`, where they may be left for a layout engine to fill in. Vazen maintains the format. The specification is licensed under CC BY 4.0 and the software under Apache 2.0.

The JavaScript/TypeScript package, `@vazen/toml`, is on npm. It reads and writes Vazen TOML files as TOML or JSON. It also reads and writes ProSpace PSA planogram files from JDA and Blue Yonder Space Planning, which start with the line `PROSPACE SCHEMATIC FILE`. A Python implementation and a web converter and visualiser are planned.

## Specification

- [Vazen TOML Specification 0.3.0](/spec/0.3.0): the current version. Structure, fields, product selectors, attributes, packaging levels, units and coordinates, ordering, orientation, a worked example and versioning.

## Documentation

- [Using Vazen TOML](/docs): the example shelf, installing `@vazen/toml`, reading and writing TOML and JSON files, the Effect schemas, the API overview, validation, and versions and compatibility.
- [Read and convert ProSpace PSA planogram files](/psa): convert a `.psa` file to JSON or Vazen TOML with `@vazen/toml`, write it back as PSA, and what a conversion keeps. Includes a made-up PSA file to try.
- [Example shelf](/examples/example-shelf.vazen.toml): a complete Vazen TOML file.

## Background

- [Why Vazen TOML?](/why): why retail needs an open planogram format, and why the format works the way it does.

## Optional

- [Source and licensing](https://github.com/vazen/toml): the specification, package source and licence texts on GitHub.
- [@vazen/toml on npm](https://www.npmjs.com/package/@vazen/toml): the JavaScript/TypeScript package.
- [Vazen](https://www.vazen.com/llms.txt): the company that maintains the format.
- Feedback and contributions: toml@vazen.com.