A publication does not need a hosted API to offer useful machine-readable content. A static JSON file can describe articles, canonical links, dates, and tags without accepting requests that change data or requiring a reader account. The important distinction is between publishing a representation and operating an application service. Calling every downloadable file an API can create expectations the site cannot meet.
This guide develops a small JSON Feed design for a fictional documentation journal. It focuses on the content contract, stable identity, validation, and practical limits. The API Tags Feed page explains those boundaries, while the Structured Data Tags Feed page places the file alongside other ways of describing published content.
Start with the reader's actual use case
Ask what a consumer needs to do with the data. A feed reader may need article titles and full text. An internal catalog may need identifiers and topic labels. A comparison tool may need stable publication dates. Write those requirements down before adding fields, because a larger record creates more compatibility and maintenance work for every downstream consumer.
For the journal example, the first release supports reading and topic grouping. It does not promise live queries, private content, user-specific filtering, or write operations. A static file can be useful within that scope. Document what the publication includes and what it leaves out so that a developer does not build against an imagined service contract.
Use a defined format before inventing one
A documented format gives consumers a common vocabulary and reduces the number of local decisions you must explain. The JSON Feed 1.1 specification defines feed-level and item-level properties, including item identifiers, content fields, URLs, dates, and tags. It requires at least one of an item's HTML or text content fields and distinguishes an identifier from an article URL.
Treat that specification as the baseline for a conforming export. Keep your editorial requirements separately documented. You might require a title, a canonical URL, a publication date, and at least one reviewed topic even where the interchange format permits a looser record. Internal rules can be stricter without redefining the format's field meanings.
Keep the shared content record format-neutral
Store article information once, then generate the website and each feed representation from it. The record should preserve the distinction between plain title text, article markup, a short summary, canonical location, and persistent identity. Do not make the JSON renderer scrape the finished page if the structured source is already available during the build.
This separation also makes future changes easier to test. A redesigned article layout should not change the item's identifier or publication date. A revised excerpt should appear consistently wherever that excerpt is used. The RSS implementation guide applies the same principle to XML output and explains why a rebuild is not a new publishing event.
Design identifiers for continuity
Choose an identifier policy that survives ordinary editorial changes. A permanent record key is often easier to reason about than a value computed from the current title. Keep the canonical URL separately so that location can change without changing identity. Never reuse a retired identifier for an unrelated article merely because it frees a convenient number.
Test three operations explicitly: renaming an article, moving its path, and correcting its body. Compare the resulting record with the previous snapshot. The fields that change should match your policy. This simple exercise catches accidental coupling between identity and presentation before a consumer stores the data and begins relying on its continuity.
Do not use a content hash as the only identity
A hash can help detect changes in a particular representation, but a corrected paragraph produces a different hash. That is a version signal, not necessarily a new article. Keep the concepts separate in your internal design. Otherwise, a consumer may see every typo correction as a completely new item and lose the ability to track its history.
Make tags portable and intentional
Use a consistent vocabulary for tag values. Decide whether they are readable labels or stable slugs and avoid mixing the two conventions casually. Keep aliases in your editorial taxonomy rather than exporting every spelling variant as another tag. A consumer should not have to guess whether “AI summary” and “AI summaries” represent different subjects.
If you need richer concept information, document a separate vocabulary representation rather than overloading a simple tag string with unrelated data. Keep a topic's identifier, label, description, and relationships distinct. A format designed for straightforward reading should not become an opaque container for every internal classification rule your team has accumulated.
Treat HTML content as an explicit boundary
An HTML-bearing field is still content, not a permission to execute arbitrary scripts. Generate it from a controlled article body and remove elements that do not belong in syndicated reading. A consumer should apply its own rendering policy as well. The publisher's responsibility is to provide clean, understandable content rather than rely on another application to repair it.
Use absolute links and image URLs in the exported body. Check that headings, lists, and code samples remain understandable outside the website's surrounding navigation. A phrase such as “click the button above” may become meaningless in a reader that never displays that button. Write feed content so that it can stand on its own.
Validate the file as data and as a publication
First parse the generated JSON and verify its structure. Then check the editorial contract: unique identifiers, intended item count, nonempty content, valid dates, canonical links, and referenced images. A syntactically valid file can still omit half the collection or repeat the same identifier. Keep these checks separate so failures are easier to diagnose.
Build a set of awkward fixtures. Include a title with quotation marks, a multilingual paragraph, a very long article, and a code block containing braces. Compare the parsed result with the source record after serialization. Also test an empty collection deliberately and decide whether the publisher should emit it or stop the release as an unexpected state.
Explain freshness without implying real-time delivery
A static feed reflects the latest published file available from its host. It is not automatically a live stream, and its consumers may refresh on their own schedules. State the publication's update practice accurately rather than advertising instant delivery. Keep article dates tied to editorial events, not to the moment a client downloads the file.
When deploying a new version, check that the website and data file describe the same release. Uploading the feed before the linked article pages can create a temporary broken reading experience. Use a deployment process that minimizes mismatched files and retain a known-good release for rollback. The right implementation depends on the hosting environment, so verify its behavior rather than assuming it.
Know when a static file stops being enough
A larger collection may need pagination, retention rules, or a separate archive. Private feeds require an access design rather than a hidden filename. User-specific queries and write operations require capabilities beyond a public static export. Define those requirements before presenting a roadmap as an existing feature.
Estimate costs in terms of file size, transfer frequency, build work, and maintenance effort. A static approach removes some application complexity but does not remove editorial obligations or hosting limits. Start with a clear, small contract and expand only when a real consumer needs more. Simplicity is valuable when it preserves meaning rather than merely omitting documentation.
Conclusion: publish a contract you can keep
A good static JSON feed is a dependable representation of published content. It preserves identity, uses a documented vocabulary, validates its own records, and states its limits honestly. It does not need fictional authentication keys or a nonfunctional query console to be useful to developers.
For the operational side of keeping published files available and recoverable, continue with the self-hosted feed archive guide. That article separates a cache from an archive and explains why a recoverable collection needs more than a successful first deployment.
