{
    "slug": "structured_data_jsonld",
    "term": "Structured Data — JSON-LD",
    "category": "frontend",
    "difficulty": "intermediate",
    "short": "Machine-readable schema markup embedded in a <script type='application/ld+json'> block, enabling Google rich results — star ratings, FAQs, breadcrumbs, events, and recipes in search.",
    "long": "Structured data communicates page content meaning to search engines in a formal vocabulary (Schema.org). JSON-LD (JavaScript Object Notation for Linked Data) is Google's preferred format — it lives in a <script> tag in <head> or <body>, separate from visible HTML, making it easy to add and maintain without modifying markup. Common schema types: WebPage (any page), Article (blog posts), Product (e-commerce with price, rating, availability), FAQPage (FAQ sections shown as expandable results), BreadcrumbList (site navigation path), Event (concerts, webinars), LocalBusiness (address, hours, phone). Valid structured data enables rich results in Google Search which typically increase CTR by 20–30%. Google requires the information in structured data to also appear visibly on the page — hidden data is ignored or penalised.",
    "aliases": [
        "JSON-LD",
        "schema markup",
        "structured data",
        "schema.org",
        "rich snippets",
        "rich results",
        "ld+json"
    ],
    "tags": [
        "seo",
        "frontend",
        "html",
        "schema"
    ],
    "misconception": "Structured data directly improves search rankings — it enables rich results (which improve CTR) but is not a direct ranking factor; a page with perfect structured data but poor content will not outrank a page with excellent content.",
    "why_it_matters": "A recipe page with Recipe schema gets star ratings, cook time, and ingredients shown directly in search results — compared to a plain blue link, these rich results consistently achieve higher click-through rates and more qualified traffic.",
    "common_mistakes": [
        "Structured data describing content that doesn't appear on the page — Google requires visible corroboration for all structured data claims.",
        "Invalid JSON syntax in the ld+json block — a single missing comma or unclosed bracket silently breaks the entire schema.",
        "Using Microdata or RDFa instead of JSON-LD — all three formats work, but JSON-LD is easiest to maintain and Google's explicit recommendation.",
        "Applying Product schema without price and availability — incomplete Product schema is not eligible for rich results.",
        "Not testing with Google's Rich Results Test — schema that validates against Schema.org may still be ineligible for rich results due to Google-specific requirements."
    ],
    "when_to_use": [
        "Add structured data to any page type that has a matching Schema.org type with Google rich result support.",
        "Priority order: Product (e-commerce), Recipe, FAQPage, Article, LocalBusiness, Event, BreadcrumbList.",
        "Always test with Google's Rich Results Test before publishing to confirm eligibility."
    ],
    "avoid_when": [
        "Do not add structured data for content that is not visibly present on the page — Google penalises hidden or misleading markup.",
        "Do not use for content that changes frequently without updating the schema — stale structured data (outdated prices, sold-out products marked available) can trigger manual actions."
    ],
    "related": [
        "meta_tags",
        "open_graph",
        "canonical_url",
        "html_meta_seo"
    ],
    "prerequisites": [],
    "refs": [
        "https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data",
        "https://schema.org",
        "https://search.google.com/test/rich-results"
    ],
    "bad_code": "<!-- No structured data — Google generates generic snippet -->\n<head>\n  <title>Chocolate Chip Cookie Recipe</title>\n</head>\n<body>\n  <h1>Best Chocolate Chip Cookies</h1>\n  <p>Rating: 4.8/5 from 243 reviews</p>\n</body>",
    "good_code": "<head>\n  <title>Chocolate Chip Cookie Recipe</title>\n  <script type=\"application/ld+json\">\n  {\n    \"@context\": \"https://schema.org\",\n    \"@type\": \"Recipe\",\n    \"name\": \"Best Chocolate Chip Cookies\",\n    \"aggregateRating\": {\n      \"@type\": \"AggregateRating\",\n      \"ratingValue\": \"4.8\",\n      \"reviewCount\": \"243\"\n    },\n    \"totalTime\": \"PT35M\",\n    \"recipeYield\": \"24 cookies\"\n  }\n  </script>\n</head>",
    "quick_fix": "Add <script type='application/ld+json'> with appropriate Schema.org type to <head>; validate with Google's Rich Results Test",
    "severity": "low",
    "effort": "medium",
    "created": "2026-04-06",
    "updated": "2026-04-06",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/structured_data_jsonld",
        "html_url": "https://codeclaritylab.com/glossary/structured_data_jsonld",
        "json_url": "https://codeclaritylab.com/glossary/structured_data_jsonld.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Structured Data — JSON-LD](https://codeclaritylab.com/glossary/structured_data_jsonld) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/structured_data_jsonld"
            }
        }
    }
}