Curriculum · Defining terms (defined/1)

Defining Terms: One Word, One Authority

5 lessons · For: Anyone who publishes definitions other people are expected to use, and needs a collision between two of them to be detectable

Publishing definitions is easy and nearly universal — schema.org’s DefinedTerm has existed since 2015. What almost nobody publishes is who *owns* a term, and the cost is that two pages under one roof can define one word two ways for years, with every static check passing the whole time.

`defined/1` is a vocabulary standard for organisations that publish definitions others rely on. It adds an authority, an expiry, a citation edge, and a history to each definition — the first makes a collision detectable, and the rest make it worth detecting.

Five lessons. You will finish able to publish a term somebody else can cite without copying, and to see why a definition with no owner is a collision waiting to happen.

Lessons

Why a glossary is not enough

You should be able to: Name the four things defined/1 adds to a schema.org DefinedTerm and why.

A glossary answers "what does this word mean here." It does not answer who owns the word, when the definition was last stood behind, whether another page is using it or merely repeating it, or how a correction is traced. Those four gaps are exactly where a shared vocabulary quietly breaks.

`defined/1` adds them: an authority (exactly one party answers for a term), an expiry (a definition nobody restates has stopped being current), a citation edge (using someone’s term is a countable, resolvable link), and a history (a correction is appended, so a stale quotation is traceable).

The first of the four is the load-bearing one. Without a named owner, a disagreement between two definitions is invisible — both are valid glossary entries. With one, exactly one of them is authoritative and the other is either citing it or contradicting it, which is a difference a check can see.

Source: FlashyOS — @flashyos/defined (defined/1)

One term, one authority

You should be able to: Explain how naming a single owner makes a definition collision detectable.

In `defined/1`, a fragment speaks for exactly one authority — an `org/`, `person/` or `agent/` — and each term names the authority that answers for it. That is the whole mechanism behind collision detection: if two definitions of one word both claim authority, the conflict is now a fact a validator can find, not a discrepancy buried in prose nobody diffs.

This is the estate’s recurring pattern — a profile identifier has one home, a surface has one owner — applied to vocabulary. The failure it prevents is the one where two pages under one roof define a word two ways for years while every static check passes, because nothing was ever asked to answer "who is right."

So the first question of any term is not its definition but its owner. A term with no authority is not a lightweight glossary entry; it is a definition that cannot be checked against anything, which is the state `defined/1` exists to end.

Source: FlashyOS — a profile identifier has one home

A citation is a link, never a copy

You should be able to: Distinguish corroboration from a copy, and say why byte-identical text is one source counted twice.

When you use another authority’s term, you cite it — a resolvable link to their definition — you do not paste their text into your own fragment. A citation is an edge in a graph, countable and checkable; a paste is a fork that drifts silently the moment they revise and you do not.

The rule has a sharp corollary the estate enforces elsewhere too: two authorities whose definition text is byte-identical are marked `copied`, not corroboration. Corroboration is two parties independently arriving at the same meaning; a copy is one meaning wearing two names. Counting a copy as a second witness is the same double-count the estate refuses in its countersignature figures.

So the honest way to agree with a definition is to cite it and say you agree — which stays true when they revise — rather than to reproduce it, which becomes a stale quotation the day they move and a misattribution the day they change their mind.

Source: FlashyOS — a citation is a link, never a copy

Expiry and history

You should be able to: Explain why a definition expires and how a correction is made.

Every entry carries an `expires` date, and a definition nobody restates past it has stopped being current. This is the same structural decay `directory/1` and `backlog/1` use: a claim that depends on nobody re-affirming it should age out on its own rather than standing forever as an assertion its author may have long abandoned.

A correction is appended, not edited. An entry carries a revision number, and a superseding definition leaves the earlier one traceable — so a quotation someone made against the old revision can still be resolved and understood, rather than silently pointing at text that no longer exists.

Together these make a vocabulary that ages honestly: current definitions are the ones still being restated, corrections are visible as corrections, and a stale citation is detectable as stale rather than passing as current. A definition, like every other claim in the estate, is provisional until re-affirmed.

Source: FlashyOS — a correction is appended, never edited

The fragment a stranger fetches

You should be able to: Describe the served document and how a reader uses it.

A `defined/1` fragment is one file per authority, served at `/.well-known/defined.json`. It carries the authority it speaks for, its entries, and its citations — the links out to terms other authorities own. A stranger fetches it the way they fetch any well-known surface and reasons about the vocabulary without an account or a database.

Because it is served rather than merely committed, it obeys the estate’s oldest rule: a definition in a repository is not a definition at a URL, and only the served fragment is the one other parties resolve citations against. Publishing the vocabulary is the act that makes a citation to it possible.

The result is a vocabulary that is federated but not fragmented: each authority owns and serves its own terms, others cite across the boundary, and the graph of who-defines-what and who-cites-whom is something a machine can walk — which is what a shared language between organisations actually requires.

Source: FlashyOS — committed is not served

Frequently asked

What does defined/1 add that a normal glossary does not?

Four things: an authority (exactly one party answers for a term), an expiry (a definition nobody restates stops being current), a citation edge (using a term is a resolvable link, not a copy), and an appended history. The authority is what makes a collision between two definitions detectable rather than invisible.

Why cite a definition instead of copying its text?

A citation is a countable, resolvable link that stays correct when the owner revises; a copy is a fork that drifts silently and becomes a misattribution the day they change their mind. Two authorities with byte-identical text are marked copied, not corroboration — counting a copy as a second witness is a double-count the estate refuses.

Where does the fragment live?

One file per authority at /.well-known/defined.json, carrying that authority’s entries and its citations out to terms others own. It is served, not just committed — only the served fragment is the one other parties resolve citations against.