What Is a Stable Identifier for a Public Dataset Record?
From the earlier reference collection. Read the current software blog.
A stable identifier keeps pointing to the same entity across dataset updates, with its scope and reuse rules clearly documented.
Identify the entity, not its current position
A row number is easy to generate but rarely stable. If records are sorted differently or a new row is inserted, row 12 may now describe another station. A client that stored the number as a bookmark can silently attach old data to the wrong entity.
Instead, assign an identifier that belongs to the entity itself. A station code can remain the same when the station’s display name changes. For a measurement record, the identifier should distinguish that observation from other observations, perhaps by using a persistent source key or a defined composite.
Document scope and uniqueness
An identifier needs a clear scope: unique within one file, one provider’s entire catalog, or across multiple publishers. A value like 17 may be unique in a single region but collide when datasets are combined. A namespaced identifier such as agency-x:17 can make ownership explicit.
Say whether identifiers are case-sensitive, whether leading zeroes matter, and whether an identifier can ever be reused after a record is retired. If IDs are reused, historical references become hazardous because the same token can point to different entities over time.
Separate identity from description
Names, addresses, and coordinates are useful attributes, but they can change or be shared. A library branch might move while remaining the same branch, or two locations might have similar names. Keep those descriptive fields separate from the stable ID so clients can notice changes without losing the link to the entity.
If a record is merged or split, explain how identifiers map to the resulting records. Preserving an alias or redirect can help clients migrate, but only if the relationship is explicit and maintained.
Test stability across releases
Compare consecutive dataset releases and inspect a sample of unchanged entities. Their IDs should remain constant even when optional details change or rows move. Also check that deleted entities are retired deliberately rather than having their IDs reassigned casually.
A stable identifier is part of the dataset’s contract. When clients can join records over time using the same key, they can track changes, reconcile local caches, and explain exactly which entity a saved reference denotes.