JSON-LD structured data correctness is not the same thing as JSON-LD syntactic validity. A script block can pass every check the Google Rich Results Test runs, render without errors in the JSON-LD Playground, and still describe the wrong entity, use the wrong property types, omit properties that Google requires for feature eligibility, or flatly contradict the text a user reads on the page. When any of those conditions exist, the markup is wrong in the only sense that matters for search: it does not accurately represent the real-world entity the page is about, and Google's systems are designed to detect and discount exactly that kind of mismatch. Understanding why requires separating two distinct layers of correctness—the syntactic layer that parsers evaluate and the semantic layer that schema.org vocabulary compliance and Google's structured data guidelines govern.
The difference between syntactic validity and semantic correctness
Syntactic validity and semantic correctness operate at entirely different levels of abstraction, and conflating them is the root cause of most silent structured data failures. When practitioners say their JSON-LD is valid, they almost always mean a tool reported no parsing errors. That is a necessary condition for the markup to be processed at all, but it is nowhere near sufficient for the markup to be useful or trustworthy.
What a JSON parser actually checks
A JSON parser evaluates a document against the JSON specification: brackets and braces are balanced, strings are quoted, commas separate array elements correctly, and no trailing commas appear where the spec forbids them. The JSON-LD processing algorithm adds a second layer—it verifies that @context, @type, @id, and other keywords follow the JSON-LD syntax specification. It confirms that the context can be dereferenced, that @graph is an array if present, and that value objects use recognized keyword forms. Neither of these checks has any opinion about whether the entity described by the markup is the entity the page actually contains. A perfectly formed JSON-LD block declaring a schema:Recipe on a page that sells software licenses will pass both checks without a single warning.
What schema.org compliance additionally requires
Schema.org vocabulary compliance requires that the @type value names a class that exists in the schema.org hierarchy, that each property used is defined for that class or one of its ancestors, that property values conform to the expected range types the vocabulary specifies, and that the combination of type and properties logically describes the subject of the page. The Structured Data Linter and the schema.org validator check some of these constraints, but neither tool has access to the page content, so they cannot detect the most damaging category of error: markup that is internally consistent but externally false. Google's systems, by contrast, compare structured data claims against on-page signals, and when those signals conflict, the markup loses credibility rather than the page content.
How the wrong schema type produces valid but misleading markup
Selecting the wrong @type is one of the most consequential errors in structured data work because every downstream decision—which properties are relevant, which are required, which rich result features are possible—flows from the type declaration. A wrong type produces markup that is internally coherent and syntactically clean while pointing interpreters toward entirely the wrong entity class. Google's documentation explicitly states that the type must match the primary content of the page, and using a parent type when a more specific child type exists is treated as a quality signal failure even when no validation error fires.
Choosing between closely related types such as Organization and LocalBusiness
Schema.org's type hierarchy creates situations where multiple types seem applicable but carry meaningfully different semantics. schema:Organization and schema:LocalBusiness are a canonical example. LocalBusiness is a subtype of Organization, so any property valid for Organization is also valid for LocalBusiness. A business with a physical address marked up as a plain Organization will pass every syntactic check, and most validators will not flag it because Organization is a legitimate type. But the markup omits the location-specific properties—address, openingHours, geo, hasMap—that Google uses to populate local Knowledge Graph entries and local rich results. The error is not that Organization is wrong in an absolute sense; it is that LocalBusiness is more accurate, and using the less specific type suppresses features that depend on the more specific one. The same logic applies to choosing between schema:Person and schema:Organization for an author entity, between schema:Event and schema:SportsEvent, or between schema:Product and schema:Vehicle.
When a generic type silently replaces a more specific one
CMS plugins and structured data generators frequently default to the most generic applicable type because it minimizes the risk of a validation error. A recipe plugin that generates schema:CreativeWork instead of schema:Recipe, or an event plugin that emits schema:Thing with event-like properties, produces markup that is syntactically unimpeachable. The JSON-LD Playground will render it without complaint. The Google Rich Results Test will not show an error for the type itself. But the rich result features tied to schema:Recipe—the cooking time carousel, the ingredient panel, the calorie display—require the specific type. Generic types do not unlock specific features, and no amount of adding the right properties to a wrong type will change that. The type declaration is the entry point into Google's feature eligibility logic, and a generic type is effectively a closed door regardless of how well-formed the properties behind it are.
Property value type constraints and why violations go undetected
Every property in the schema.org vocabulary has a defined range—the set of types or data types its value is expected to be. Some properties expect a Text value, others expect a URL, others expect a Date in ISO 8601 format, and others expect a nested entity of a specific type. Violations of these constraints are among the most common errors in production JSON-LD, and they are almost never caught by standard validation tools because JSON itself has no schema enforcement, and the JSON-LD processing algorithm does not validate value types against schema.org range definitions.
Text versus URL versus Date mismatches
The schema:url property expects a URL value. Providing a plain text string like 'our website' instead of 'https://example.com' is a property value type mismatch that no standard validator will flag as an error. The schema:datePublished property expects an ISO 8601 date string. Providing 'January 2024' instead of '2024-01-15' is technically a Text value where a Date is expected—again, no error fires, but Google's ability to use that value for date-based features is degraded or eliminated. The schema:image property expects an ImageObject or a URL; providing a relative path like '/images/photo.jpg' instead of an absolute URL is a common mistake that passes validation but may not resolve correctly when Google's crawler processes the markup from a cached or redirected URL. These mismatches accumulate silently across a site and collectively reduce the reliability of the structured data signal without ever producing a single validation error.
Numeric range violations that validators accept
Schema.org defines certain properties with implicit numeric constraints. The schema:ratingValue property is expected to fall within the range defined by schema:bestRating and schema:worstRating. Providing a ratingValue of 4.8 with a bestRating of 5 is correct. Providing a ratingValue of 9.6 with a bestRating of 5 is logically inconsistent—the rating exceeds the maximum—but no validator will reject it because JSON has no range constraint enforcement. Google's rich result requirements for AggregateRating explicitly require that ratingValue not exceed bestRating, and markup that violates this constraint is ineligible for the star display in search results even though it passes every automated check. Similarly, a schema:duration value using a non-ISO 8601 duration format like '45 minutes' instead of 'PT45M' will not trigger a validation error but will not be parsed correctly by systems that expect the standard format.
Required and recommended properties that are silently absent
The schema.org vocabulary distinguishes between required properties, recommended properties, and optional properties for each type, but this distinction is not enforced at the vocabulary level—it is enforced at the feature eligibility level by individual consumers like Google. A JSON-LD block that omits every recommended property is still valid schema.org markup. It will pass the Rich Results Test syntax check. But it will not qualify for the rich result features that depend on those properties, and in some cases it will not qualify for any enhanced treatment at all.
How Google's rich result requirements differ from schema.org minimums
Google's structured data documentation defines its own property requirements for each supported rich result type, and these requirements frequently exceed what schema.org marks as required. For schema:Recipe, schema.org requires very little at the vocabulary level, but Google's rich result eligibility requires at minimum a name, an image, and either ingredients or instructions depending on the feature. For schema:JobPosting, Google requires title, description, datePosted, validThrough, hiringOrganization, and jobLocation—properties that schema.org treats as recommended or optional. A JobPosting block that includes only title and description is valid schema.org markup and will pass the JSON-LD Playground without errors, but it will not produce a job rich result in Google Search. The gap between schema.org minimums and Google's feature requirements is where a large proportion of real-world structured data failures live.
Properties that are optional in the spec but mandatory for feature eligibility
Some properties occupy an unusual position: schema.org treats them as optional, Google's documentation lists them as recommended, but in practice their absence prevents the feature from appearing. The schema:author property on schema:Article is a clear example. Schema.org does not require it. Google's article rich result documentation lists it as recommended. But Google's author markup documentation, introduced as part of the E-E-A-T signal infrastructure, makes clear that author information is used to evaluate content credibility, and pages that consistently omit it receive less favorable treatment in contexts where authorship matters. Similarly, schema:aggregateRating on a schema:Product is optional in the vocabulary, recommended by Google, but functionally required if the goal is to display star ratings in product search results. Treating 'recommended' as 'ignorable' is a systematic error that produces markup that is technically valid but commercially ineffective.
Markup that contradicts visible page content
Content-markup agreement is the dimension of structured data correctness that validators are least equipped to evaluate and that Google's quality systems are most actively designed to assess. When the claims made in a JSON-LD block do not match the information a user can read on the page, the markup is not just wrong—it is potentially deceptive, and Google's structured data guidelines treat content-markup disagreement as a policy violation that can result in manual actions, not just feature suppression.
Why content-markup agreement is a quality signal
Google's systems extract information from page content independently of structured data. Natural language processing, entity recognition, and content analysis produce a set of signals about what the page is about, who created it, when it was published, and what entities it describes. Structured data is supposed to confirm and clarify those signals, not contradict them. When the JSON-LD block says a product costs $29 but the visible price on the page is $49, Google's systems detect the discrepancy. When the markup claims a review has 4.8 stars but no review content appears on the page, the claim is unsupported. When the schema:dateModified value is a year old but the page content has clearly been updated, the date signal is unreliable. Each of these contradictions reduces the trustworthiness of the structured data as a whole, and a pattern of contradictions across a site is a strong signal of low-quality or manipulative markup practices.
Common contradictions in price, date, and author fields
Price contradictions are the most commercially damaging category. E-commerce sites that update prices in their database but fail to regenerate structured data end up with JSON-LD Offer blocks showing stale prices. A user who sees a $39 price in a rich result snippet and arrives at a page showing $59 experiences a trust failure that affects both the user and the site's relationship with Google's quality evaluators. Date contradictions are nearly as common: a schema:datePublished value that predates the actual publication, or a schema:dateModified value that never updates when content changes, produces a false temporal signal that affects how Google understands content freshness. Author contradictions occur when a site uses a shared or generic author entity in structured data—'Staff Writer' or the organization name—while the visible byline names a specific person, or vice versa. Each of these patterns is invisible to a validator and visible to a content-aware quality system.
Nested entity relationships that break logical consistency
JSON-LD's ability to nest entity descriptions within a single block is one of its most powerful features and one of its most error-prone. A schema:Article can contain a nested schema:Person as its author, a nested schema:Organization as its publisher, and a nested schema:ImageObject as its primary image. Each nested entity must be internally correct, but the relationships between them must also be logically consistent. Errors in nested entity structure are syntactically invisible and semantically significant.
How incorrectly linked nested objects mislead interpreters
A common error is nesting an entity of the wrong type in a property that expects a specific type. The schema:publisher property on schema:Article expects an Organization or Person, not a plain text string. Providing a string value like 'Acme Corp' instead of a nested schema:Organization object with a name and logo means the publisher entity is not properly structured, and Google's article rich result requirements—which specifically require publisher to be an Organization with a logo—will not be satisfied. Another common error is using a nested entity that is internally valid but contextually wrong: placing a schema:Person object in the schema:author field of an article when the actual author is an organization, or nesting a schema:Place in a property that expects a schema:PostalAddress. These errors do not break the JSON-LD parsing but do break the semantic interpretation.
Verifying that @id references resolve to the intended entity
When JSON-LD uses @id to reference an entity defined elsewhere—either on the same page in a separate block or at an external URL—the reference must resolve to the correct entity. A schema:WebPage block that references an @id for the organization that matches the @id in a separate schema:Organization block creates a linked entity graph. If the @id values do not match exactly—different trailing slashes, HTTP versus HTTPS, or a typo—the link breaks and the entities are treated as unrelated. This is particularly important for Knowledge Graph integration, where consistent @id values across pages signal that the same entity is being described. A site that uses 'https://example.com/#organization' on the homepage and 'https://example.com#organization' on inner pages has broken the entity link at the hash fragment level, and no validator will catch it because both are syntactically valid @id values.
Context declaration errors that alter property meaning
The @context declaration in a JSON-LD block is not decorative—it defines the vocabulary that gives every property and type its meaning. Errors in the @context value do not always prevent parsing, but they can fundamentally alter what the markup means or render it uninterpretable by systems that expect schema.org vocabulary. Context errors are among the least discussed categories of structured data problems and among the most consequential.
What happens when the @context value is non-standard or missing
The correct @context value for schema.org markup is 'https://schema.org' or 'http://schema.org'. Using 'http://schema.org/' with a trailing slash, or 'https://schema.org/v3.9', or a custom URL that happens to redirect to schema.org, introduces ambiguity. Some processors will resolve these variants correctly; others will not. More critically, omitting the @context entirely produces a JSON-LD block where every property and type is treated as a local term with no external definition—the markup is syntactically valid JSON-LD but semantically empty because no vocabulary has been declared. The JSON-LD Playground will process it without errors. The Rich Results Test may still attempt to interpret it using heuristics, but the markup is not conformant schema.org and should not be expected to produce reliable results.
Namespace collisions between schema.org and custom vocabularies
Sites that extend schema.org with custom properties sometimes declare multiple contexts or use a context object that maps prefixes to different vocabularies. When a custom vocabulary defines a property with the same local name as a schema.org property, a namespace collision occurs. The property name 'name' in a custom context might mean something entirely different from schema:name, but if the context declaration is ambiguous, processors may interpret the custom property as the schema.org one or vice versa. This is particularly problematic when Microdata and JSON-LD coexist on the same page with different vocabulary assumptions, or when a CMS injects a context object that partially overrides the schema.org context. The result is markup that appears correct in isolation but behaves unexpectedly when processed by a system that strictly follows the JSON-LD context resolution algorithm.
Duplicate and conflicting JSON-LD blocks on the same page
Modern CMS platforms, theme frameworks, and SEO plugins frequently inject structured data independently of each other, producing pages with multiple JSON-LD script blocks. When those blocks describe the same entity with different or conflicting values, or when they describe different entities that should be linked but are not, the result is a structured data environment that is internally inconsistent. Google's documentation acknowledges that multiple blocks are supported but does not guarantee how conflicts between them are resolved.
How multiple blocks interact in a single document
Google processes all JSON-LD blocks on a page and attempts to merge the information they contain. When two blocks describe the same @type without a shared @id, Google may treat them as two separate entity descriptions or attempt to merge them based on matching property values. When two blocks describe the same entity with the same @id but different property values—one block says the organization's telephone is '+1-800-555-0100' and another says it is '+1-800-555-0199'—the conflict is unresolvable without additional signals. In practice, Google tends to use the most recently processed or most prominently positioned block, but this behavior is not documented and should not be relied upon. The safer assumption is that conflicting blocks produce unreliable output, and the correct approach is to ensure that each entity is described exactly once with a consistent @id.
Resolving conflicts between CMS-generated and manually added markup
The most common source of duplicate blocks is the combination of a CMS plugin that auto-generates structured data and a developer who has manually added a JSON-LD block to the page template. The plugin generates a schema:WebPage and schema:Organization block; the developer adds a schema:WebPage block with additional properties. Both blocks are syntactically valid. Both may even be semantically reasonable in isolation. But together they create a duplicate entity description with potentially conflicting values for name, url, description, and other properties. Resolving this requires either disabling the plugin's output for the affected types, merging the two blocks into one, or using @id references to ensure that both blocks are understood as describing the same entity. Google Search Console's structured data report will sometimes surface warnings about duplicate entities, but it will not always identify which block is the source of the conflict.
How to audit JSON-LD for semantic accuracy beyond the validator
A semantic audit of JSON-LD structured data requires a different methodology than running a URL through the Rich Results Test. The validator answers the question 'can this be parsed?' A semantic audit answers the question 'does this accurately describe the entity on this page, and does it meet the requirements of the features it is intended to support?' These are manual, judgment-intensive questions that require comparing the markup against the page content, the schema.org vocabulary documentation, and Google's feature-specific requirements simultaneously.
Manual review checklist for type and property selection
A practical manual review starts with the @type declaration: open the schema.org page for that type and verify that the type's definition matches the primary subject of the page. Then check whether a more specific subtype exists that would be more accurate. For each property used, verify that the property is listed for that type on schema.org, that the value provided matches the expected range type, and that the value accurately reflects what appears on the page. For each property listed as required or recommended by Google's feature documentation, verify that it is present and correctly valued. Check that all nested entities are of the correct type for the property they appear in. Verify that all @id values are absolute URLs and that they are consistent with @id values used for the same entity on other pages. This review takes ten to twenty minutes per page type and catches the majority of semantic errors that automated tools miss.
Using Google Search Console warnings as a semantic feedback signal
Google Search Console's Enhancements section provides structured data reports broken down by type, showing errors, warnings, and valid items. Warnings are particularly valuable for semantic auditing because they often indicate missing recommended properties rather than syntax errors—they are Google's way of signaling that the markup is parseable but incomplete for feature eligibility. A warning that says 'missing field recommended: image' on a Recipe type is not a syntax error; it is a semantic completeness signal. Tracking warning counts over time and treating them as a quality metric—rather than ignoring them because they are not errors—is one of the most effective ways to maintain structured data quality at scale. The Search Console report also surfaces items that were previously valid and have become invalid, which often indicates a content change that broke content-markup agreement.
Structured data review workflow for ongoing correctness
Structured data correctness is not a one-time audit task—it is an ongoing maintenance requirement. Page content changes, product prices update, events pass their dates, authors change, and organizational details evolve. Each of these changes creates an opportunity for content-markup disagreement to develop. A review workflow that integrates structured data checks into the content publishing process prevents the accumulation of semantic errors that individually seem minor but collectively degrade the reliability of the site's structured data signal.
Integrating markup review into content publishing steps
The most effective integration point is the content review step that precedes publication. For any page that carries structured data, the reviewer should verify that the markup reflects the current state of the content before the page goes live. For e-commerce pages, this means confirming that price, availability, and currency values in the Offer block match the current product data. For event pages, it means confirming that startDate, endDate, and eventStatus reflect the current event state—particularly important for events that may be postponed or cancelled. For article pages, it means confirming that dateModified is updated whenever substantive content changes are made. Building these checks into a publishing checklist, rather than treating them as a separate SEO task, ensures that content and markup stay synchronized without requiring a separate audit cycle.
Documenting entity definitions to prevent future drift
One of the most underused practices in structured data maintenance is maintaining a document that defines the canonical entity descriptions for the site's primary entities: the organization, the website, the primary author entities, and the product or service categories. This document specifies the @type, the @id, the required and recommended properties, and the expected value format for each. When a new page template is created, a new CMS plugin is installed, or a new developer joins the team, this document provides the reference that prevents new markup from diverging from the established entity definitions. Without it, each new implementation makes independent decisions about @id values, type selection, and property inclusion, and the result is the kind of inconsistent, conflicting markup that degrades structured data quality over time. The document also serves as the basis for a structured data review checklist, making the manual audit process faster and more consistent.
Tools that surface semantic issues the Rich Results Test misses
The Google Rich Results Test is the most widely used structured data tool, but it is optimized for a specific purpose: determining whether a URL's markup is eligible for Google's supported rich result types. It is not designed to evaluate general semantic correctness, and it does not check content-markup agreement, type specificity, or property value accuracy beyond the requirements of the specific rich result features it tests for. Other tools fill different parts of the gap.
Structured Data Linter and schema.org validator differences
The Structured Data Linter, maintained as an open-source tool, evaluates markup against schema.org vocabulary definitions more thoroughly than the Rich Results Test. It checks whether properties are defined for the declared type, whether value types match the expected range, and whether the overall structure conforms to schema.org conventions. The schema.org validator at validator.schema.org performs similar checks with a focus on conformance to the vocabulary specification. Neither tool checks content-markup agreement—they have no access to the page content—but both surface property misuse and type errors that the Rich Results Test ignores because those errors do not affect the specific rich result features it evaluates. Using both tools in combination with the Rich Results Test provides broader coverage of the syntactic and vocabulary-level error space.
Manual inspection techniques using JSON-LD Playground
The JSON-LD Playground at json-ld.org provides a processing environment that shows the expanded, compacted, and flattened forms of a JSON-LD document. The expanded form is particularly useful for semantic auditing because it resolves all prefixes and context mappings to their full URIs, making it immediately visible whether a property is being interpreted as a schema.org term or as something else. If a property that should expand to 'https://schema.org/name' instead expands to a local term or a different URI, the context declaration has a problem. The flattened form shows all entities and their properties in a normalized structure, making it easier to identify duplicate entity descriptions and verify that @id references are consistent. These views provide information that the Rich Results Test's visual interface does not expose, and they are essential for diagnosing context declaration errors and namespace collision issues.
Real-world patterns where valid JSON-LD silently fails
Across production sites, certain patterns of valid-but-wrong structured data appear repeatedly. They share a common characteristic: they were correct at the time they were created and became incorrect as the page content or real-world circumstances changed, without any automated system detecting the drift. Understanding these patterns makes it easier to build the monitoring and review processes that catch them before they accumulate into a systemic quality problem.
Event markup with past dates left unchanged
Event pages are the most common source of date-based content-markup disagreement. A conference page is created with a schema:Event block specifying a startDate of a future date. The event occurs. The page is left live as an archive or recap page, but the structured data is never updated. The startDate now refers to a past event, but the eventStatus property still says 'EventScheduled' rather than 'EventPostponed' or the page has been repurposed for the next year's event without updating the date. Google's event rich result requirements explicitly state that events with past dates are not eligible for event rich results, and markup that claims a future date for an event that has already occurred is a content-markup contradiction. Sites with large event catalogs frequently have dozens or hundreds of these stale event blocks, each passing validation, each silently ineligible for the features they were created to support.
Product markup missing offer or availability properties
Product pages are the second most common source of silent structured data failure. A schema:Product block without a nested schema:Offer is valid schema.org markup—Product does not require Offer at the vocabulary level. But Google's product rich result requirements state that a product snippet requires either an Offer or an AggregateOffer to display price information, and without price information, the rich result is significantly less valuable. More critically, product pages where the Offer block exists but the schema:availability property is absent or set to 'InStock' for a product that is actually out of stock create a content-markup contradiction that affects both user experience and Google's trust in the markup. Availability is one of the properties that Google's systems can verify against page content, and a persistent mismatch between the availability claim in structured data and the out-of-stock signal in the page content is a reliable path to having the product markup discounted or suppressed entirely.
