Guide

JSON-LD structured data for articles: a publisher's guide

Search engines read your HTML, but they also look for explicit machine-readable hints about what a page is. JSON-LD is the most common way publishers declare that a URL is an article, who wrote it, when it was published, and what it is about. Done correctly, structured data unlocks rich results in Google Search, helps news aggregators classify your content, and gives ad platforms a cleaner signal about page type. This guide walks through Article and NewsArticle schema, the properties that matter, how to test your markup, and mistakes that waste crawl budget without earning anything back.

What structured data does for publishers

Structured data is a vocabulary — usually schema.org — embedded in your page so crawlers do not have to guess. For a news site or guide library, the payoff is practical:

Rich result eligibility — article rich results, top stories carousels (where applicable), and clearer indexing signals for timely news.
Consistent metadata — one JSON block mirrors your <title>, meta description, and Open Graph tags instead of letting each system drift.
Discoverability in tools — Google Search Console's enhancement reports surface missing or invalid fields before they silently fail in production.
Future-proofing — AI crawlers and answer engines increasingly prefer pages with explicit entity markup over bare paragraphs alone.

Structured data is not a substitute for good content or fast pages. It sits alongside technical SEO basics like canonical URLs, semantic headings, and Core Web Vitals. Google has stated structured data alone is not a direct ranking factor, but invalid or spammy markup can trigger manual actions — treat it as accurate metadata, not keyword stuffing.

JSON-LD vs other formats

Schema can be expressed three ways: JSON-LD (a <script type="application/ld+json"> block in <head> or body), Microdata (attributes on HTML elements), or RDFa. Google supports all three but recommends JSON-LD because it keeps presentation HTML separate from metadata and is easy to generate in static site templates.

For static publishers shipping hand-authored or templated HTML, JSON-LD wins on maintainability: copy one head snippet per article type, swap headline and dates, validate once, deploy. Microdata sprinkled through article body tags is harder to audit at scale and breaks more often when designers refactor markup.

Article vs NewsArticle: which type to use

Both inherit from CreativeWork. Pick based on editorial intent, not URL folder names:

Type	Use when	Examples on this site
`Article`	Evergreen guides, explainers, tutorials, reference docs	Wallet setup guides, developer how-tos
`NewsArticle`	Time-sensitive reporting tied to a specific event or date	Breaking tech news, market moves, product launches

Using NewsArticle on a five-year-old tutorial misleads crawlers. Using Article on same-day reporting is acceptable but may miss news-specific signals. When in doubt, Article is the safer default for educational content; reserve NewsArticle for pages where the publish date is part of the story's value.

Properties Google actually checks

Required for rich results (Article)

headline — matches your visible H1; keep under ~110 characters.
image — array of absolute URLs to images at least 1200 px wide for large previews; use your OG image if you have one.
datePublished — ISO 8601 date (YYYY-MM-DD or full timestamp).
author — Person or Organization with a name; use a real byline or publisher brand.

Strongly recommended

dateModified — update when you materially revise content; stale dates erode trust in news contexts.
description — aligns with meta description; not a duplicate keyword list.
mainEntityOfPage — canonical URL of the article.
publisher — organization with name and ideally logo (ImageObject with width/height).

Optional but useful

articleSection — category such as "Guides" or "Markets".
wordCount — honest integer; do not inflate.
speakable — for voice assistant summaries on news pages.

Minimal working example

Place this in <head> alongside your canonical and Open Graph tags. Replace the placeholder values; every URL must be absolute ( https://).

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Your article title — matches H1",
  "description": "One-sentence summary aligned with meta description.",
  "author": {
    "@type": "Organization",
    "name": "Your Site Name",
    "url": "https://example.com/"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Your Site Name",
    "url": "https://example.com/",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png",
      "width": 600,
      "height": 60
    }
  },
  "image": ["https://example.com/og/article-card.png"],
  "mainEntityOfPage": "https://example.com/guides/your-slug/",
  "datePublished": "2026-06-07",
  "dateModified": "2026-06-07"
}
</script>

For breaking news, change @type to NewsArticle and add dateModified whenever you correct facts. Keep the JSON valid: no trailing commas, escape quotes inside strings, one root object per script tag (or use @graph for multiple entities on one page).

Align JSON-LD with visible page content

Google's guidelines require structured data to reflect what users see. That means:

Headline = H1 — not a longer SEO variant hidden from readers.
Dates match bylines — if you show "Updated June 7, 2026" in the article, dateModified must agree.
Images must exist — do not point image at broken URLs or generic stock photos unrelated to the article topic.
Author must be credible — "Admin" or fake personas on mass-produced pages are a scaled-content abuse signal.

The same alignment applies to Open Graph and Twitter cards: title, description, image, and URL should tell one coherent story across HTML meta tags, JSON-LD, and visible copy. Divergence confuses crawlers and looks like cloaking when the gaps are large.

Common mistakes that block rich results

Relative URLs — "/og/card.png" fails; use full https:// paths.
Missing image — the most frequent Article error in Search Console enhancement reports.
Wrong @type — WebPage alone does not declare article semantics; nest or use Article directly.
Duplicate conflicting blocks — two JSON-LD scripts with different headlines on one URL.
Markup on non-article pages — do not slap Article schema on category hubs, tool pages, or login screens.
Keyword-stuffed headlines in JSON only — a manual-action risk on ad-monetized sites.

How to test before and after deploy

Google Rich Results Test — paste URL or raw HTML; confirms Article/NewsArticle detection and lists warnings.
Schema Markup Validator (schema.org) — syntax and vocabulary checks independent of Google.
Search Console → Enhancements — after indexation, monitor "Articles" or "Review snippets" reports for sitewide regressions.
View source on production — CDN or deploy pipelines sometimes strip <script> tags; verify live HTML, not just local files.

Run the Rich Results Test every time you change a head template. A single bad deploy across hundreds of guides pollutes Search Console faster than you can fix URLs one by one.

Structured data in a static-site workflow

Teams shipping static HTML — no CMS — usually template the head once per content type (guide, news, product). A sensible pipeline:

Define one JSON-LD partial per @type with placeholders for headline, dates, canonical, and image.
Generate sitemap.xml entries in the same build step so every article URL is discoverable.
Add internal links in the body (two to four related pages) — structured data does not replace a healthy link graph.
After deploy, spot-check three URLs: new article, oldest article, hub page (hub should use CollectionPage or WebPage, not Article).

Our Garden Dice build log documents similar head-template discipline for a product page — the same pattern scales to content libraries. Pair markup with performance work from our Core Web Vitals guide so rich results lead to pages that actually load.

Publisher checklist

One JSON-LD block per article URL; @type matches content intent.
headline, description, and H1/meta description aligned.
Absolute image URL, ideally 1200×630 OG asset.
datePublished and dateModified in ISO 8601.
author and publisher as Organization or real Person.
mainEntityOfPage equals link rel="canonical".
Validated in Rich Results Test on production URL.
Hub and index pages use appropriate types — not Article on every template.