This is the development branch. See releases for stable distribution files.

Shopify's Standard Product Taxonomy

🌍 Global Standard: Our open-source, standardized product taxonomy establishes a universal language for product classification. Comprehensive and already empowering merchants on Shopify.

👩🏼‍💻 Integration Friendly: With a stable structure and diverse formats our taxonomy is designed for effortless integration into any system.

🚀 Industry Benchmark: Spanning 22 essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces.

Learn more on help.shopify.com

🗂️ Table of Contents

• 🕹️ Interactive explorer
• 📚 Taxonomy overview
• 🧭 Getting started
  • 🧩 How to integrate with the taxonomy
  • 🧑🏼‍🏫 How to make changes to the taxonomy
  • 👩🏼‍💻 How to evolve the system
• 🤿 Diving in
• 🛠️ Setup and dependencies
• 📂 How this is all organized
• 📅 Releases
• 📜 License

🕹️ Interactive explorer

Ready to dive in? Explore our taxonomy interactively to visualize and discover what's published across the many categories, attributes, and values.

📚 Taxonomy overview

Our taxonomy is an open-source comprehensive, global standard for product classification. It's a universal language that empowers merchants to categorize their products. Spanning 22 essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces.

What's next? ⏭️ More attributes and values as we work to make this truly comprehensive.

🧭 Getting started

This repository is the home of Shopify's Standard Product Taxonomy. It houses the source-of-truth data, the distribution files for implementation, and the source code that makes this all sing.

We've structured it to be as user-friendly as possible, whether you're looking to integrate the taxonomy into your system, suggest changes, or delve into how it's developed and maintained.

🧩 How to integrate with the taxonomy

Dive straight into releases branch to find the files you need and integrate this taxonomy into your system.

We're working on a variety of formats to make it easy to integrate with your systems. Today we have txt and json formats, and we're working on more. If you have a specific format you'd like to see, please open an issue and let us know!

🧑🏼‍🏫 How to make changes to the taxonomy

🔵 Note: While we are in preview we are not actively seeking PRs.

Everything comes from the source-of-truth files in data/. This is where you should submit PRs to change the taxonomy itself.

👩🏼‍💻 How to evolve the system

This system is how we manage the taxonomy and generate distributions. This is where the magic happens.

🤿 Diving in

This is a simple ruby app with a few models and serializers. The bulk of the work is parsing data/ into a tree of app/models/category.rb to serialize reliably to /dist/. The app is setup to be rails-like, but is not a rails app, though is using ActiveRecord.

Everything ultimately runs through make (dev simply proxies). Here are the commands you'll use most often:

make [build] # build the dist and documentation files
make clean   # remove sentinels and all generated files
make seed    # parse /data into local db
make test    # run ruby tests and cue schema verification
make server  # http://localhost:4000 interactive view of /dist/

🛠️ Setup and dependencies

For Shopify employees or folks with minidev:

• Run dev up

For everyone else you'll need to:

• Install ruby, version matching .ruby-version
• Install cue, version 0.7.x or higher
• Install make
• Run bundle install

When you edit any cue files, ensure you're running cue fmt. This will format the cue files to the standard format.

📂 How this is all organized

Most folks won't touch most of this, but we see you 👩🏼‍💻.

If you want to add a new serialization target, three simple steps:

1. Add a new serializer to app/serializers
2. Add the file load to application.rb
3. Extend bin/generate_dist to use your new serializer and write files

For your own explorations, here's a map of the land:

./
├── application.rb  # handles file loading "app-wide"
├── Makefile         # primary source of useful commands
├── Rakefile         # only used for testing
├── app/
│   ├── models/          # most models are simple data objects
│   │   ├── category.rb      # node-based tree impl for categories
│   │   └── ...
│   └── serializers/
│       ├── data/        # object-centric, to read/write source-data files
|       ├── data/        # object-centric, for docs site
│       └── dist/        # file-type-centric, for dist files
│           ├── json.rb
│           └── text.rb
├── bin/
│   ├── generate_dist    # file IO for /data → /dist
│   └── generate_docs    # file IO for /dist → /docs
├── db/
│   ├── schema.rb        # defines in-memory tables for models
│   └── seed.rb          # seed the db by parsing data shaped from /data
└── test/

📅 Releases

You can always find the current published version in VERSION. The changelog is available in CHANGELOG.md.

While this is UNSTABLE, we're using SemVer, but when this goes stable it will transition to CalVer, in sync with Shopify's API release schedule.

That means a stable release every 3 months at most, at the beginning of the quarter. Version names are date-based to be meaningful and semantically unambiguous (for example, 2024-01).

📜 License

Shopify's Product Taxonomy is released under the MIT License. So go ahead, explore, play, and build something awesome!