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 25+ 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
• 🧑‍💻 Contributing
• 📅 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 25+ essential verticals, our taxonomy encompasses categories, attributes, and values, all thoughtfully integrated within Shopify and numerous marketplaces.

🧭 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 dist 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

Everything else 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 set up to be rails-like including 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/dist/
2. Extend bin/generate_dist to use your new serializer and write files

For your 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/
│       ├── source_data/ # object-centric, to read/write source-data files
│       ├── docs/        # object-centric, for docs site
│       └── dist/        # file-type-centric, one file per distribution type
├── bin/
│   ├── generate_dist    # primary entrypoint for generating dist/
│   └── generate_docs    # primary entrypoint for generating docs/
├── db/
│   ├── schema.rb        # defines tables for models
│   └── seed.rb          # seed the db by parsing data shaped from data/
├── data/
│   ├── integrations/    # integrations and mappings between taxonomies
│   ├── localizations/   # localizations for categories, attributes, and values
│   ├── categories/      # source-of-truth for categories
│   ├── attributes.yml   # source-of-truth for attributes
│   └── values.yml       # source-of-truth for values
└── test/

🧑‍💻 Contributing

We welcome contributions! Before we can merge any changes you submit, you'll need to sign the Shopify CLA (a friendly robot will help when you open your first PR 🤖).

📅 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-07).

Formal releases are published as Github releases and available on the interactive docs site.

📜 License

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