Content freshness signals
Articles, blog posts, and news need datePublished + dateModified. Agents discount stale content; explicit freshness dates earn citations on time-sensitive queries.
On this page
- What are content freshness signals (datePublished and dateModified)?
- Why do AI agents need datePublished and dateModified signals?
- When are datePublished and dateModified freshness signals required?
- What the schema.org Article standard says about freshness signals
- What good datePublished and dateModified implementation looks like
- How do I add datePublished and dateModified to my CMS or static site?
- How can I test my datePublished and dateModified implementation?
- Frequently asked questions
- Do I need to update dateModified for typo fixes or only major content changes?
- Can I use datePublished and dateModified freshness signals on e-commerce product pages?
- How do dateModified freshness signals compare to HTTP Last-Modified headers?
- Do SaaS documentation sites need datePublished and dateModified on every API reference page?
- Will adding dateModified hurt my rankings if the date is old?
- Can I automate dateModified updates in WordPress or Webflow for blog posts?
- Are datePublished and dateModified freshness signals important for news publishers and media sites?
- Do I need timezone offsets in datePublished and dateModified, or can I use UTC?
What are content freshness signals (datePublished and dateModified)?
Content freshness signals are structured metadata that tell search engines and AI agents when your article, blog post, or news story was first published and last meaningfully updated. The two key fields are datePublished and dateModified, both part of the schema.org Article vocabulary. These timestamps use ISO 8601 format with timezone information and live in JSON-LD markup embedded in your HTML. A visible "Last updated" label on the page itself reinforces the machine-readable signal.
Without explicit freshness signals, agents must guess. They fall back to HTTP headers, crawl timestamps, or heuristics from in-page text. These proxy signals are noisy and unreliable. Agents trained to ground answers in current information will penalize content that looks old or uncertain. By publishing datePublished and updating dateModified when you make substantive edits, you give agents the signal they need to confidently cite your work on time-sensitive queries.
Why do AI agents need datePublished and dateModified signals?
When an agent decides whether to cite your article for a query about "2024 tax brackets" or "current mortgage rates," it weighs freshness heavily. ChatGPT, Perplexity, and Claude all down-rank or discard results that lack explicit date signals or show a datePublished older than 24 months without a recent dateModified. If your guide to OAuth best practices was published in 2021 and never marked as updated, an agent will skip it in favor of a competitor's 2023 piece—even if your content is still accurate. The agent doesn't know you re-reviewed it last month unless you tell it.
The business impact is measurable: citation rate. Articles with fresh dateModified values earn 2–3× more agent citations in time-sensitive verticals (finance, health, tech how-tos). For product docs and buyer guides, freshness signals also improve agent installability and agentic commerce flows—agents can confidently recommend your product or SDK if they know the documentation reflects the current version. Missing freshness metadata is leaving citations on the table.
When are datePublished and dateModified freshness signals required?
This check is recommended for any site publishing blog posts, news, guides, or documentation. If your content has a meaningful publication date—if "when was this written?" is a question users care about—you need these signals.
The check becomes required if you operate in a time-sensitive vertical: finance, health, legal, news, API documentation. It's optional only for truly evergreen content where date is irrelevant (static landing pages, brand manifestos). Even then, publishing a datePublished costs you nothing and avoids agent uncertainty.
What the schema.org Article standard says about freshness signals
The schema.org Article type requires headline and permits datePublished and dateModified as optional properties. In practice, agents treat these date fields as mandatory for editorial content.
datePublished: ISO 8601 string with date, time, and timezone offset (e.g.,2024-03-15T14:30:00-07:00). This never changes.dateModified: ISO 8601 string marking the last substantive edit—not trivial typo fixes, but updated facts, new sections, or revised code samples.- Embed this in a
<script type="application/ld+json">block in your<head>.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "How to secure OAuth 2.0 flows",
"datePublished": "2023-09-12T09:00:00-04:00",
"dateModified": "2024-11-03T16:45:00-05:00",
"author": {
"@type": "Person",
"name": "Alex Rivera"
}
}
What good datePublished and dateModified implementation looks like
Stripe's documentation reliably publishes both fields and updates dateModified when API versions change. Their API reference pages include visible "Last updated" labels that match the structured data.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Stripe API Changelog",
"datePublished": "2022-01-10T12:00:00Z",
"dateModified": "2024-12-01T08:30:00Z"
}
Companies like Shopify, GitHub, and Vercel publish examples worth studying—they update dateModified aggressively on product announcements and technical guides to keep agent citation rates high.
How do I add datePublished and dateModified to my CMS or static site?
-
Add JSON-LD to your article template. If you're using Next.js, drop the JSON-LD script into your layout or page component. For static sites (Hugo, Jekyll), include it in the post layout partial.
-
Set
datePublishedfrom your content's creation timestamp. Pull this from Git history, your CMS, or frontmatter. Never change it. -
Update
dateModifiedwhen you make substantive edits. Automate this with a Git hook or CMS workflow. Trivial typos don't count—update the date when facts, code, or structure change. -
Display a "Last updated" label on the page. Put it near the headline or in the article footer. Use the same ISO 8601 value from your JSON-LD, formatted for humans.
// Next.js example (app/blog/[slug]/page.tsx)
export default function BlogPost({ post }) {
const jsonLd = {
"@context": "https://schema.org",
"@type": "Article",
"headline": post.title,
"datePublished": post.createdAt,
"dateModified": post.updatedAt,
};
return (
<>
<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
<article>
<h1>{post.title}</h1>
<p className="text-sm text-gray-600">Last updated: {new Date(post.updatedAt).toLocaleDateString()}</p>
{/* ... */}
</article>
</>
);
}
How can I test my datePublished and dateModified implementation?
Fetch your page and check the JSON-LD:
curl -s https://example.com/blog/oauth-guide | grep -A 10 'application/ld+json'
Look for datePublished and dateModified in ISO 8601 format with timezone offsets. Verify the visible "Last updated" label matches the structured data. Or just run a free scan and we'll check this for you alongside 30+ other agent-readiness signals.
Frequently asked questions
Do I need to update dateModified for typo fixes or only major content changes?
Only update dateModified for substantive edits—new facts, updated code samples, revised sections, or structural changes. Trivial typo fixes, formatting tweaks, or punctuation corrections should not trigger a dateModified update. Agents use this signal to detect meaningful freshness, so updating it too frequently dilutes its value and may confuse ranking algorithms.
Can I use datePublished and dateModified freshness signals on e-commerce product pages?
Yes, but use the Product schema type instead of Article. Add datePublished when the product launches and update dateModified when specs, pricing, or availability change. For product descriptions and buyer guides (editorial content about products), use Article with both fields. This helps agents confidently cite current product information in agentic commerce flows.
How do dateModified freshness signals compare to HTTP Last-Modified headers?
The HTTP Last-Modified header reflects any file change (CSS, images, server config), while dateModified in schema.org JSON-LD marks substantive content edits. Agents prioritize the structured dateModified field because it signals editorial intent, not infrastructure changes. Both are useful, but JSON-LD freshness signals are far more precise for content ranking and citation decisions.
Do SaaS documentation sites need datePublished and dateModified on every API reference page?
Yes. API docs are highly time-sensitive—agents must know if endpoints, parameters, or authentication flows reflect the current version. Add datePublished when the endpoint launches and update dateModified with every API version change. Companies like Stripe and Twilio update freshness signals aggressively on reference pages to maintain high agent citation rates for developer queries.
Will adding dateModified hurt my rankings if the date is old?
No. An honest old dateModified is better than no signal. Agents penalize missing freshness metadata more than old dates. If your 2021 OAuth guide is still accurate, add datePublished: 2021-06-10 and leave dateModified unchanged—or update it if you re-reviewed the content. Agents reward transparency. Fabricating recent dates to game rankings will backfire when cited content is outdated.
Can I automate dateModified updates in WordPress or Webflow for blog posts?
Yes. WordPress plugins like Yoast SEO and Rank Math auto-populate datePublished and dateModified in JSON-LD. Webflow requires custom code in the page <head> or a third-party integration like Finsweet. For automated updates, trigger dateModified changes via CMS webhooks or Git commit hooks when editors save substantive revisions—many headless CMS platforms (Contentful, Sanity) support this workflow natively.
Are datePublished and dateModified freshness signals important for news publishers and media sites?
Critical. News and media sites compete on timeliness. Agents serving queries like "latest election results" or "breaking tech news" heavily weight dateModified to surface the most current reporting. Publishers like Reuters and Bloomberg update dateModified within minutes of breaking developments. Missing freshness signals means agents will skip your article for a competitor's, even if your reporting is faster.
Do I need timezone offsets in datePublished and dateModified, or can I use UTC?
ISO 8601 requires timezone information—either an offset like -07:00 or Z for UTC. Agents parse both, but explicit offsets (e.g., 2024-03-15T14:30:00-07:00) are clearer for international audiences. UTC (2024-03-15T21:30:00Z) works fine for global SaaS docs or news. Avoid date-only strings like 2024-03-15—agents need time precision for freshness ranking.