Open specification · v0.1.0 draft

One thing.
One name.
Computed by anyone.

An Intuition ID is an identifier you compute rather than request. Same facts, same procedure, same string — for anyone, anywhere, with no registry to ask and no coordination. It is how atoms in the world's knowledge graph get deterministic identity.

anatomy of an intuition id
int:isbn:9780684832722
int — the namespace, always isbn — the scheme: which kind of identifier the value — canonical, byte-exact

A specific edition of a specific book — unique because the International ISBN Agency guarantees it.

26schemes 36entity types 170verified test vectors 1deterministic namespace

The problem

The same thing, named a thousand ways

Let four people add the band Radiohead to a shared knowledge base and you will get four entries: Radiohead, RADIOHEAD, one with a trailing space nobody can see, one from a database export. Every fact anyone contributes attaches to one of the four at random. Ratings split, followers split, and the knowledge base ends up knowing less than any single contributor did.

This is the default outcome of letting independent parties describe the same world — and it compounds with every new source. Central ID registries fix it by making everyone ask permission, which a decentralized protocol cannot do. Name matching merges the four Nirvanas into one. Fuzzy matching is a guess, and guesses aren't reproducible.

The Intuition Identifier takes a different route: derive the name from the thing. Take the facts you have, run them through a published, exactly-specified procedure, and out comes a string. Anyone with the same facts gets the same string. Where the facts are too thin to tell two things apart, the identifier is honest about it instead of pretending precision — because hashing does not create identity; it preserves exactly as much uniqueness as its input had.

Identity classes

Three strengths of identifier — and the spec says which is which

Not all identifiers are equally trustworthy, and a specification that treated them as equal would be lying by omission. Every scheme belongs to exactly one class, and the class is visible in the identifier itself.

Class A · Registry

A registry already did the work

An external authority — the ISBN agency, GLEIF, ORCID — guarantees uniqueness. We borrow that authority. Within Class A, open registries rank above proprietary ones.

int:isbn:9780684832722
Class B · Natural key

The thing carries its own identity

An Ethereum address is the account. A URL is the page's address. A content hash is the file. Natural keys — nothing to revoke, no issuer to disappear.

int:caip10:eip155:1:0xd8da…6045
Class C · Derived

We hash what little we know — and say so

No authority, no natural key: hash a few chosen facts. Genuinely useful, honestly weak. Two bands named Nirvana will collide, and that is correct behaviour.

int:gen1:music-group:r4:8f3c…

Identity ladders

Always mint from the best facts you have

Each entity type declares an ordered list of identifier options, strongest first — its identity ladder. You climb as high as your facts allow. The ladder for a film:

1A·T2wdWikidata — open, CC0
2A·T2tmdbcommunity registry, open exports
3A·T3imdbworks, but closed & proprietary
4Cgen1{name, yearPublished}derived — weak, and visibly so
5Cgen1{name}weakest — a title alone

Rung 2 sits above rung 3 deliberately: when two identifiers are equally correct, the more open one wins. An identifier only one company can verify is a weaker foundation for a public knowledge graph than one anyone can check.

Try it · Derivation

Derive an identifier, right here

This is the gen1 algorithm running in your browser: NORM-1 normalization, canonical preimage, keccak-256, first 16 bytes. Change a fact and watch the identifier change. Give it the same facts in sloppier formatting — extra spaces, curly quotes, capitals — and watch it not change.

gen1 · movie · live derivation
NORM-1
Preimage
keccak-256 ×16 B

Try it · Validation

Inspect any Intuition ID

Paste an IID — or a raw value like a hyphenated ISBN — and this will parse it, check the scheme against the registry, verify canonical form (check digits included), and tell you exactly how strong the identifier is. Validation is the spec's three steps: shape, registered scheme, canonical value.

iid inspector · 26 schemes loaded

The registry

26 schemes, 36 entity types, one governed namespace

The scheme registry is closed on purpose: an unregistered scheme means an unregistered canonicalization, and an uncanonicalized value is exactly the ambiguous string this spec exists to eliminate. Adding a scheme is a reviewed, governed change — and once ratified, its rules are frozen forever.

SchemeClassIdentifiesGuaranteed by

Every scheme has a normative document with its grammar, canonicalization algorithm, and executable test vectors in the scheme registry; every entity type's ladder lives in the entity-type registry. A machine-readable export is published as registry.json.

The honest boundary

Identifiers don't finish the job — claims do

One real entity legitimately carries many identifiers: a band has an ISNI and a MusicBrainz ID. No deterministic function maps one to the other — that is a judgement, and judgements are claims. In Intuition, "these two are the same thing" is itself content: attestable, disputable, stakeable, and reversible.

So the layers split along the line of what is mechanical and what is not. Identifiers are deterministic and free, and collapse the overwhelming bulk of duplicates automatically. The equivalence layer handles the judgement calls in public, where they can be argued with. An IID is a claim of identity, not a certificate — correctness is established the way every other truth is established in Intuition: by people putting something behind it.

Separation of concerns

Identity is fixed. Interpretation is yours.

This spec governs which string names a thing — and stops there. What your backend makes of an atom is a different job: which vocabulary it maps into, which type semantics apply, how it's contextualized, rendered, and ranked. Mint an atom from an ISBN and one system may interpret it through schema.org, another through a library-science ontology, a third through a schema it invented — all three converge on the same atom and interoperate at the identity layer, because identity and interpretation are separate layers.

That modularity is a core value of the approach: Intuition is deliberately unopinionated about interpretation while providing the deterministic building blocks for decentralized coordination. The identifier layer stays strict, minimal, and frozen precisely so that interpretation engines above it can stay opinionated, swappable, and yours to choose.

Contribute

This is a commons. Help build it.

The identifier space is only as useful as the world it covers, and no one team covers the world. The specification is openly licensed (MIT), governed in public, and designed so that contribution is safe: everything additive is open, and nothing you build on can be changed out from under you.

Propose a scheme

Know an identifier system with stable IDs, open licensing, and offline validation? There's a template and a governed admission process.

Scheme template →

Improve a ladder

Ladders aren't frozen — new rungs and reorderings are welcome. Several documented gaps are waiting for an owner.

Open proposals →

Implement the spec

Every test vector is executable. Build a validator or canonicalizer in your language, and report every ambiguity you hit — those are spec defects, and we want them.

Contributing guide →
The freeze rule. Once ratified, a scheme's canonicalization never changes — not even to fix a bug. Improvements ship as new schemes and new versions, bridged by equivalence. Your identifiers mean the same thing forever.