stapel-vocabularies

Reference vocabularies too large to inline into a category's feature schema — 14 962 phone models, 107 049 car modifications — stored as levels, terms and parent/child edges rather than as paths, so one 'black' is shared by every model that comes in black and can be translated once and faceted on. Ships the public typeahead and cascade reads a listing composer needs (ETag'd on a revision, anonymous, no cookie), the two VocabularyResolver implementations stapel-attributes' ref_select / ref_hierarchical_select types validate values through (in-process and over comm), a batched transactional loader for reviewed fixtures that spends one revision and one event per file, and Django-free converters that turn a vendor's nested XML or CSV catalogue into such a fixture without loading the document into memory.

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-vocabularies

At a glance

Documentation

OpenAPI · capabilities.json · llms.txt (for agents)

What this is

Some option lists are too big to be options. A phone catalogue has 14 962 models; a car catalogue has 107 049 modifications. Inlining those into a category's feature schema is not a tuning question — the schema is fetched on every form render, and it would be megabytes.

stapel-vocabularies is where they live instead.

• Levels, terms and edges — not paths. Vendor → Model → MemorySize → Color is 56 921 distinct paths in a real phone catalogue and only 15 844 distinct terms. Storing the terms and the parent/child edges between them means one Color=chernyy shared by every model that comes in black: 17 colours to translate instead of 56 921 path nodes, and a facet on a colour code that is answerable at all.
• A read surface built for a typeahead. terms/?level=Model&parent=apple&q=pro answers a page with total and has_children, prefix matches ranked first. Anonymous, ETag'd on the vocabulary's revision, Cache-Control: public, and no Set-Cookie — so the shared cache in front of it works and a crawler does not start a session per request.
• Two resolvers, one protocol. ref_select / ref_hierarchical_select in stapel-attributes validate values through a VocabularyResolver. OrmResolver answers from these tables and is registered at startup; CommResolver answers the same questions over the bus, for a service that validates listings but holds no catalogues. Both cache describe by revision, so a re-imported catalogue stops validating against the levels it used to have the moment the import commits.
• Loading is data plumbing, not an admin screen. manage.py load_vocabulary phones.json is one transaction, one revision increment and one vocabulary.changed event for the whole file, whatever its size. The real phone catalogue — 15 844 terms, 39 749 edges — loads in ~1.2 s.
• Converters that do not read the file into memory. A vendor's nested XML or a one-path-per-row CSV becomes a reviewable fixture, streamed through iterparse, with codes assigned deterministically (Cyrillic transliterated, collisions numbered in label sort order) so re-converting an unchanged catalogue produces an unchanged diff.

Alpha. See MODULE.md for the agent-facing map of seams.

Quick start

pip install stapel-vocabularies

# settings.py
INSTALLED_APPS = [..., "stapel_vocabularies"]

# urls.py
path("vocabularies/", include("stapel_vocabularies.urls"))   # -> /vocabularies/api/v1/...

python manage.py convert_vocabulary phone_catalog.xml \
    --slug phone-models --name "Phone models" --out fixtures/phone-models.json
python manage.py load_vocabulary fixtures/phone-models.json --replace

A feature then points at it instead of carrying options:

{"type": "ref_select", "optionsRef": {"vocabulary": "phone-models",
                                      "level": "Model",
                                      "parentFeature": "vendor"}}

API

Accept-Language selects a translated label where the term carries one; the response Varys on it and the ETag covers it.

The fixture format

One file per vocabulary, byte-stable, reviewed as code (schema):

{ "slug": "phone-models", "name": "Phone models", "source": "https://…/phone_catalog.xml",
  "levels": [{"name": "Vendor"}, {"name": "Model", "parent": "Vendor"}],
  "terms": [["Vendor", "apple", "Apple", null], ["Model", "iphone-10", "iPhone 10", null]],
  "edges": [["Vendor", "apple", "Model", "iphone-10"]] }

A level's parent must be declared before it. That single rule is the whole acyclicity argument: a level can only point backwards, so no chain of parents can return to where it started.

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}