HomeGoods Taxonomy

A hierarchical classification for household and small-business goods, with a physical and handling attribute layer attached to every class.

The model is the Harmonised System — the HS codes used to classify goods for customs. HS answers what duty is payable. This answers a different question: what does this object need from the box it is in, and what should it be stored next to?

30        Electronics & Computing
  3008    Storage Media
    300801  Internal drives
            0.5 kg · 0.65 kg/L · fragile · high value · nothing on top

Every item in an inventory gets one 6-digit code. The attributes come with it.

Why

An inventory row records what you have. It does not record that a box of hardbacks will weigh 24 kg, that bleach must never be packed with drain cleaner, or that the button cells in the drawer are the most dangerous thing in the house for a toddler. Those are properties of the kind of object, not the object — so they only need recording once.

That is the whole design. Record it per class, assign classes automatically, and an existing inventory acquires a data layer it never had.

What it enables

• Store like with like. Cluster by group, by division, or by attribute profile — kitchen + daily cuts across the tree and matches how a house is actually used.
• And unlike apart. co_store_avoid is the only field constraining combinations, and it exists because similarity engines get this actively wrong. Bleach and flour are both kitchen, both monthly, both about a kilogram.
• Box-level roll-ups. "This box is 20% fragile", "this box will weigh 26 kg, do not fill it", "this container holds a hazmat item", "this shelf is within a child's reach and shouldn't be".
• Move planning. Weight limits, exclusion lists, hand-carry sets, unpacking order — see docs/move-planning.md.

Assignment is meant to be automated. No one classifies a thousand items by hand, and the class descriptions are written to be read by a model as much as by a person.

Documentation

docs/id-scheme.md	The coding system — levels, allocation, why codes are never reused
docs/hazmat.md	hazmat vs un_class, the UN classes used, lithium, and what this cannot be used for
docs/special-handling.md	The handling tags — actions with lead times, not fragility
docs/schema.md	Every attribute, its type, its default, and why it exists
docs/use-cases.md	What the taxonomy is for, and what it is not
docs/integration.md	Wiring it into an inventory system — schema, MCP surface, classification pipeline
docs/move-planning.md	The move case in depth, on a six-week timeline

Layout

data/           YAML source of truth — divisions.yaml plus one file per division
dist/           Generated: taxonomy.json (nested) and taxonomy.csv (flat)
scripts/        validate.py, build.py
docs/           The above

Edit data/. Never edit dist/ — it is regenerated.

uv run scripts/validate.py   # structure, enums, consistency rules
uv run scripts/build.py      # regenerate dist/

The validator enforces more than shape. It rejects a child_hazard with no stated reason, a flammable that is not marked mover_restricted, and a deprecated class with no successor; it warns on a density that would overload a standard box without a note explaining it.

Status

v1 — complete and published.

All 27 divisions are populated: 136 groups and 367 classes, every class carrying the full attribute payload. The validator passes with no errors and no warnings.

Depth is set for the stated use cases — organisation and moving — not for completeness. A class exists where it changes how something is stored, packed or carried, which is why "gardening gloves" and "smart plugs" are classes and the distinction between two brands of screwdriver is not. Levelling off there is deliberate: a decorative taxonomy of everything in a home is unbuildable, and past a certain depth it stops changing any decision.

Where to get it

The canonical published dataset is on Hugging Face: danielrosehill/homegoods-taxonomy

This repository is the workspace — the YAML source of truth, the build and validation tooling, and the documentation of why the thing is shaped the way it is. Hugging Face is where the released data lives, because a taxonomy is a dataset and that is the platform built for distributing one.

Edit here, release there. dist/ is regenerated and uploaded on release.

Caveats

All mass and density figures are estimates, accurate to roughly ±30% — enough to keep a box under a weight limit, not enough to bill a shipper on. Where a class spans a wide range, the figure is the middle of the common domestic range.

hazmat and un_class are handling hints, not a shipping declaration. A real declaration needs the specific UN number, proper shipping name, packing group and quantity, determined from the actual product. What these fields do is surface — weeks ahead — which items a remover will refuse, so they can be dealt with on a schedule rather than discovered on the morning. See docs/hazmat.md.

Licence

MIT — see LICENSE.