BDS0.1

Docs

How this vocabulary works

Where the data comes from, and what to do before you add a term.

What this is

What BDS covers, and what it leaves to schema.org.

BDS is a business vocabulary built the way schema.org says an external extension should be built: published under its own governance, at its own namespace (https://bds.local/), with every type a subClassOf a schema.org type, and a handful of schema.org properties widened to reach BDS types.

It describes what a business's operating data means. It does not describe how a database stores it: tenant ids, row-level permissions, created/updated timestamps, soft-delete flags and audit trails have no BDS terms on purpose. Money movement belongs to schema:Invoice and schema:Order; products for sale to schema:Product and schema:Offer.

Order of authority

When two words compete, this ranking decides which one wins.

  1. 1

    schema.org. If the term exists there, use it. Do not mint a BDS twin.

  2. 2

    BDS core. Agreed and stable. Safe to build on.

  3. 3

    Your own extension. Anything the business needs that the two above do not cover, under your own namespace.

A widened schema.org property beats a new BDS property: see the widened list before proposing anything.

Layers

Every term is marked with schema:isPartOf. Release 0.1 is entirely core.

core
Agreed and stable. After 1.0 they only widen; they never break.
pending
Proposed and published for trial. May still change.
attic
Retired. Still resolves, still documented, marked supersededBy when something replaced it. Never deleted.

Where the data comes from

No definition is typed into a page. Every page renders a generated dataset.

source of record            packages/vocabulary/scripts/build-vocabulary.py
      │
      ▼
packages/vocabulary/data/terms.json     ← the only place a definition lives
      │
      ├─► apps/docs            Astro renders every page from it
      └─► packages/search      SQLite index (FTS5, BM25) built from it

Change a definition in the source of record and rerun pnpm vocab; everything downstream follows. Fixing wording by editing a page puts the same definition in two places.

How search works

Full-text search over a single SQLite file. No model, no external service.

Index — FTS5
Every term is indexed by label, definition and body, with accents folded and camelCase split, so “due date” finds bds:dueDate.
Ranking — BM25
Labels weigh ten times the body. Type MetricTarget and you get bds:MetricTarget first.
Matching — all words, then any word
A query first requires every word. When nothing matches, it retries with any word of three letters or more, ignoring short connectors in English and Portuguese.

The vocabulary is written in English, so search in English terms; Portuguese words only match where they appear in a definition.

Adding a term

Four steps, in order. Most proposals die at step one.

  1. Search first. Both here and at schema.org. Most proposals are a word that already exists under another name.
  2. Try to widen instead. An existing property reaching a new type beats a new property.
  3. Write the definition before the name. If the definition needs the word “or”, it is probably two terms.
  4. Land it in pending. It gets published, used for real, and only then promoted to core.

Downloads

Every artifact is generated from the same terms.json. Nothing here is written by hand.

Every file here is derived from data/bds.ttl, the one hand-edited copy of the vocabulary; the release Turtle carries the same triples in normalized order. Read PROVENANCE.md for the source hash and the layers.

State of this release

Release
0.1 (2026-09-03)
Dataset generated
2026-09-10
Source
data/bds.ttl
Source sha-256
3d0ebc9c44b2846c5c6a99aeea31778635c174671650ad7fc8e88aa212f0d4f3
Canonical source present
yes
Terms
24 types · 12 enumerations (69 values) · 81 properties · 12 widened

The dataset is read straight from data/bds.ttl by build-vocabulary.py. Release 0.1 was transcribed from the published HTML reference on 2026-09-10; since then the Turtle is the only source.