Stable Identifiers for Reference Data: Slugs, IDs, and Canonical URLs

A reference dataset is a contract. The identifier you assign to it is the strongest part of that contract, because consumers will store it, cite it, and cache by it.

Slugs over IDs

YJTOON datasets use slugs: http-status-codes-complete, sql-join-types. Slugs are human-readable, stable across database resets, and safe in URLs. A numeric ID changes meaning the moment a row is deleted and re-inserted; a slug does not.

Canonical URLs as identifiers

The canonical URL https://yjtoon.com/static-data/dataset/{slug}.json is the identifier agents should store. It is unique, addressable, and versionable. Caching by canonical URL means two agents can share a cache and agree on what they fetched.

What agents should do

• Store the canonical URL, not the data, when possible — reference data is cheap to re-fetch and expensive to store wrong.
• Record the format alongside the URL (.json, .yaml, .toon) — the same data in another format is a different resource.
• When citing, link the canonical URL so a human can verify.

Stability is a policy, not an accident

YJTOON treats renames as breaking changes and documents them. If a slug must change, the old URL should redirect or at least return a clear 404 with the new location in the error body.