JSON-LD vs Microdata: Keep One Consistent Article Identity

Compare the representation of the same facts

JSON-LD and Microdata can describe the same article using different markup structures. JSON-LD usually places a serialized data object in a separate script element. Microdata annotates HTML elements with attributes that identify an item, its type and its properties. The choice changes how a template is maintained; it should not change the facts about the article.

The JSON-LD recommendation defines JSON-LD, and the HTML Microdata specification defines the HTML attributes. Pick the representation your publishing system can keep accurate through normal editing and rendering.

Describe an article and its author in JSON-LD

This fictional example has an article identifier, a headline and a nested author. The author has a different identity from the article. A real site should use the actual visible headline and credited author rather than copying these example facts.

{
  "@context": "https://schema.org",
  "@type": "Article",
  "@id": "https://example.com/guides/map-labels/#article",
  "headline": "Make map labels easier to read",
  "author": {
    "@type": "Person",
    "@id": "https://example.com/about#editor",
    "name": "Example Author"
  }
}

The visible page still needs to contain its headline and author credit. Because the JSON-LD object is separate from the displayed elements, a template should derive both from the same content record where possible. Maintaining two manually typed copies invites drift.

Represent the same relationship with HTML attributes

<article itemscope itemtype="https://schema.org/Article"
         itemid="https://example.com/guides/map-labels/#article">
  <h1 itemprop="headline">Make map labels easier to read</h1>
  <p itemprop="author" itemscope itemtype="https://schema.org/Person"
     itemid="https://example.com/about#editor">
    By <span itemprop="name">Example Author</span>
  </p>
</article>

The author element starts a nested Person item, while itemprop connects that person to the article's author property. The name inside that nested scope belongs to the person. Moving the name property outside the author scope can change the data relationship even when the page looks almost identical.

Use an extractor or a test that understands the item scopes to verify the result. Searching the source for the word author is not sufficient: the correct relationship depends on the surrounding attributes and nesting.

Choose a maintainable template boundary

Microdata can keep a property close to its visible value, which is useful when a template already owns that element. However, a layout refactor that moves elements between scopes can change the extracted data. Include structured-data checks when changing those template boundaries.

JSON-LD can express a graph without interleaving attributes through the visible layout, but it still needs safe serialization and factual synchronization. A plugin that emits yesterday's author name does not become accurate because its JSON parses successfully.

For either approach, avoid hardcoded example URLs, invented authors and automatic date changes on every build. Identify the article and author consistently across pages, and keep modification dates tied to actual editorial changes.

Migrate without publishing contradictions

Inventory the current markup first, including anything a CMS theme or plugin inserts. For one representative page, extract the article type, identifier, headline and author from the existing representation. Produce the new representation from the same content data and compare those values.

If both representations appear temporarily, verify that they agree. Do not treat adding JSON-LD as permission to leave an obsolete Microdata author or a conflicting article identifier in the rendered page. Remove or update the obsolete source through the owning template once the migration is verified.

The local JSON-LD Generator can create a basic JSON-LD starting object; it does not rewrite existing Microdata or merge entities for you. Test the rendered HTML from the real template after integrating the chosen representation.

When search appearance is the goal, consult the search engine's current feature documentation as an additional check. A valid vocabulary representation does not guarantee an enhanced result, and neither serialization is a substitute for a useful, accessible article.

Related guides

WordPress JSON-LD: Inspect and Maintain the Rendered Markup

Find the JSON-LD WordPress already emits, choose one publishing owner, serialize content safely, and verify changes on rendered article pages.

JSON-LD Markup: Describe One Page with Consistent Entities

Build a small JSON-LD article object, choose stable entity identifiers, embed JSON safely, and compare the markup with the visible page.

FAQ JSON-LD: Model Questions Without Obsolete Search Claims

Create FAQPage JSON-LD from visible question-and-answer pairs, check pairing and escaping, and understand the retired Google FAQ search feature.