JSON Feed IDs: Stable Identifiers in Version 1.1

JSON Feed expresses syndication in a data model familiar to web and application developers. Its item object has one field that is both required and easy to mishandle: id. The value is a string that uniquely identifies the item over time. It may look like a URL, a UUID, a database key, or a namespaced token, but it should remain stable even when the item’s visible URL or content changes.

Because JSON makes serialization straightforward, teams sometimes generate feeds directly from API responses without defining an identity contract. The result can be IDs tied to array positions, current slugs, or transient database replicas. A reliable feed uses the same discipline as a durable public API: immutable keys, explicit URLs, predictable dates, and migration tests.

The id field is required

Every JSON Feed item must have an id string. The format does not require a specific syntax. A publisher can use the item URL, a UUID, a tag URI, or another value it controls. The key requirements are uniqueness within the feed and stability for as long as the item is represented.

The complete field definitions and publisher guidance are in the JSON Feed 1.1 specification. Reading the specification matters because familiar-looking fields have distinct roles. The ID identifies the item, url provides the page associated with it, and external_url can point to a resource elsewhere that the item discusses.

Do not use array position or fetch order

JSON arrays are ordered, but an item’s index is not an identity. A new item inserted at the front changes every subsequent position. Pagination, filtering, and archive trimming also change positions. Values such as item-0 or a hash of the current array index will create duplicates whenever the feed is rebuilt.

Order should be communicated through dates and the sequence of items in the current representation. Identity needs a value attached to the content record itself. If the publishing system already has an immutable primary key, it can be wrapped in a globally unique namespace and stored as the feed ID.

URL IDs work when URLs are permanent

Using the item’s canonical URL as both id and url is valid when the publisher can preserve that URL. It produces readable data and makes debugging easy. The danger is a router that rebuilds paths from mutable titles, categories, or dates. When a slug changes, a generated ID changes, and readers interpret the same article as a new item.

A publisher can keep the original URL-shaped ID after the page moves. The url field can change to the new canonical page while the ID remains the established identifier. The old URL may redirect, but the ID does not need to resolve; it needs to stay unique and stable.

Opaque IDs offer clean separation

An opaque token such as urn:uuid:... or example.org:article:1842 separates identity from routing. It also makes format conversion easier because the same token can be carried into an RSS GUID or an Atom ID with a documented mapping. The token should be created once and stored.

{
  "id": "urn:uuid:51f84fa3-6b66-4bb0-9b12-2f3d78dcd24e",
  "url": "https://example.org/guides/stable-identifiers/",
  "title": "Stable identifiers for feeds",
  "content_html": "<p>...</p>",
  "date_published": "2025-11-06T15:00:00Z",
  "date_modified": "2025-11-14T18:30:00Z"
}

Do not expose a raw database integer without a namespace if feeds from several systems can be combined. The value 1842 may be unique in one table and ambiguous everywhere else.

Dates support synchronization but do not identify

date_published describes original publication, and date_modified describes a later change. Neither should be used as the item ID. Imports, timezone corrections, and editorial updates can alter dates without creating a new item. Two items can also be published at the same instant.

Readers can use the stable ID to find an existing item and the modification date to decide whether to refresh its stored representation. Publishers should avoid setting every modification date to the build time. Doing so makes every feed request look like a full update and reduces the value of incremental synchronization.

Attachments need their own stable handling

JSON Feed attachments represent audio, video, documents, and other media associated with an item. Their URLs may move to a new CDN or storage provider. That change should not force a new item ID. Preserve the item identity and update the attachment metadata.

When an application needs attachment-level deduplication, it can store a separate media identifier or a verified checksum. Do not overload the item ID to represent a particular file version. One item can legitimately have multiple attachments or replace a broken file while remaining the same editorial item.

Feed-level identity still needs a local model

JSON Feed provides feed_url for the URL of the feed and home_page_url for the associated site. It does not define a required immutable feed ID. Applications that need to track a publication across URL changes should assign their own internal feed identifier, preserve old URLs as aliases, and treat the current feed_url as the canonical locator.

This mirrors the approach on the feed identity model: stable publication ID, canonical URL, aliases, observed metadata, and item IDs. A feed URL can move while JSON item IDs remain continuous.

Version 1.1 discovery and media type

JSON Feed 1.1 uses the more specific media type application/feed+json. An HTML page can advertise the feed with an alternate link element using that type. The feed response should return a matching content type when practical, and the JSON should be valid UTF-8.

Discovery metadata should point to the canonical feed URL. If a site also offers RSS or Atom, give each link a distinct title and media type. Equivalent formats should preserve a consistent item identity mapping so a multi-format reader does not create duplicates merely because a user switches formats.

Converting IDs between formats

A JSON Feed ID can become an RSS opaque GUID or an Atom entry ID when the value meets the target format’s syntax requirements. If it does not, place it inside a stable URI namespace instead of inventing a new random value on each conversion. Store the mapping so future exports reproduce the same result.

When importing from RSS, preserve the GUID rather than replacing it with the current link. When importing from Atom, preserve the entry ID. A conversion pipeline should be idempotent: converting the same source twice should produce the same target IDs.

Validation and testing

Parse the JSON strictly and require an ID for every item. Check that IDs are strings, nonempty, and unique within the logical feed. Compare current IDs with the previous production version. Existing content should retain its ID even when URL, title, summary, content, authors, tags, or attachments change.

Also validate that each item includes at least one appropriate content field, that URLs are absolute where required by the application, and that dates use valid ISO 8601 forms. Fetch the public feed without credentials and confirm the content type and canonical redirect behavior.

Common JSON Feed ID mistakes

• Using the item’s array index as the ID.
• Generating a UUID during every feed request.
• Hashing the complete content, so corrections create new identities.
• Using a mutable slug without preserving the original value.
• Changing IDs when attachment URLs move to another CDN.
• Discarding source GUIDs or Atom IDs during format conversion.
• Treating the feed URL as a permanent publication ID without alias history.

A production-ready pattern

Create an immutable item identity in the publishing database. Expose it as a namespaced string in JSON Feed. Store the public page URL separately and update it when routing changes. Set publication and modification dates from content events, not deployment time. Preserve imported identifiers and document format mappings.

For the publication itself, keep an internal feed ID and a canonical feed URL. Record redirects and aliases. Add automated tests that compare IDs across builds and reject duplicates. This pattern works for a static export, a server-rendered endpoint, or an API that emits JSON Feed as one representation.

Conclusion

JSON Feed makes item identity explicit without prescribing one identifier syntax. That flexibility is valuable when paired with discipline. IDs should be immutable keys; URLs should describe current locations; dates should describe content events; attachments should describe media.

Keeping those roles separate allows a JSON Feed to survive redesigns, API refactors, CDN migrations, and conversions to other syndication formats. The result is predictable synchronization for readers and a clean identity model for publishers.