{"slug": "schema-org-json-ld-the-complete-pattern-reference", "title": "Schema.org + JSON-LD: the complete pattern reference", "summary": "This article serves as a comprehensive reference for implementing Schema.org structured data using JSON-LD, emphasizing its critical role for Google, AI crawlers, and SERP features in 2026. It details the modern \"@id graph pattern\" for cross-referencing entities, explains how AI search engines use schema for entity extraction, and stresses that invalid schema is penalized more harshly than having none. The guide covers implementation across various frameworks, validation tools, and key schema types, positioning structured data as a non-optional foundation for search visibility.", "body_md": "Originally published at thatdevpro.com. Part of ThatDevPro's open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.\nJSON-LD Implementation, the @id Graph Pattern, Per-Page Type Selection, and Validation\nA comprehensive installation and audit reference for structured data — the machine-readable layer that tells Google, AI crawlers, and other consumers what entities a page is about and how they relate. Every meaningful SERP feature, AI citation, and Knowledge Panel claim depends on this layer being correct. Dual-purpose: installation manual and audit document.\nCross-stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see\nframework-cross-stack-implementation.md\n. For pure client-rendered SPAs (no SSR/SSG) seeframework-react.md\n. For Tailwind-specific concerns (purge, dynamic classes, dark-mode CLS, focus accessibility) seeframework-tailwind.md\n.\nThis is the canonical reference for schema.org structured data implementation. Schema is no longer optional in 2026 — it is the foundation that lets Google's Knowledge Graph populate, AI search engines extract claims, and SERP rich results render. A site without proper structured data is invisible to half of modern search.\nSchema in 2026 differs from schema in 2020 in three critical ways. First, the @id\ngraph pattern (cross-referenced nodes within a single @graph\nblock) has overtaken the older \"one schema block per page\" approach because it lets entities reference each other across the site. Second, AI search engines (ChatGPT, Perplexity, Claude, Gemini) rely on schema as a primary signal for entity extraction — accurate schema increases citation likelihood. Third, validation is non-negotiable: invalid schema is worse than no schema, because Google penalizes spam markup.\nsearch.google.com/test/rich-results\n— primary validatorvalidator.schema.org\n— comprehensive validator (accepts more types than Google's tool)webmaster.yandex.com/tools/microtest/\njson-ld.org/playground/\n— for graph experimentationcurl\n+ jq\n— extract and inspect JSON-LD from a URL programmaticallyCovers: schema formats, @id graph pattern, the major schema types every site needs, type-specific implementation per content type, validation methodology, sameAs networks, and common pitfalls. Touches but does not exhaust: Knowledge Graph claiming (own framework: framework-knowledgegraph.md\n), AI citation mechanics (framework-aicitations.md\n), Local SEO schema (framework-localseo.md\n).\nbusiness_type: \"\" # local | ecommerce | publisher | b2b_service | sdvosb\nprimary_entity: \"\" # Organization name\nperson_entity: \"\" # Founder/author Person if relevant\nwebsite_domain: \"\"\nlocal_business_subtype: \"\" # Restaurant | Plumber | Dentist | etc. — only if local\necommerce_product_count: 0\nexisting_schema_present: false\nexisting_schema_format: \"\" # JSON-LD | Microdata | RDFa\nexisting_schema_validated: false\nwikidata_qid_org: \"\" # if claimed\nwikidata_qid_person: \"\" # if claimed\nsameas_targets: [] # LinkedIn, GitHub, Wikidata, Wikipedia, etc.\nknown_schema_errors: []\nThree formats are valid. Pick one and stick with it.\nJSON-LD lives in a <script type=\"application/ld+json\">\nblock in the document head (or anywhere in the body — head is conventional). It does not need to mirror the visible HTML.\nThis is the single most important pattern in modern schema implementation. Older sites declared one schema block per type per page, with no cross-references. The graph pattern declares all entities in one @graph\nblock with cross-referenced @id\nURIs, letting Google reconstruct the entity relationships.\n<script type=\"application/ld+json\">\n{\n\"@context\": \"https://schema.org\",\n\"@graph\": [\n{\n\"@type\": [\"Organization\", \"ProfessionalService\", \"LocalBusiness\"],\n\"@id\": \"https://example.com/#organization\",\n\"name\": \"Example Co\",\n\"url\": \"https://example.com/\",\n\"sameAs\": [\n\"https://www.wikidata.org/wiki/Q12345\",\n\"https://www.linkedin.com/company/example\",\n\"https://github.com/example\"\n],\n\"founder\": { \"@id\": \"https://example.com/#founder\" }\n},\n{\n\"@type\": \"Person\",\n\"@id\": \"https://example.com/#founder\",\n\"name\": \"Joseph W. Anady\",\n\"sameAs\": [\n\"https://www.wikidata.org/wiki/Q139592630\",\n\"https://www.linkedin.com/in/josephanady\"\n],\n\"worksFor\": { \"@id\": \"https://example.com/#organization\" },\n\"knowsAbout\": [\"Technical SEO\", \"AI search optimization\"]\n},\n{\n\"@type\": \"WebSite\",\n\"@id\": \"https://example.com/#website\",\n\"url\": \"https://example.com/\",\n\"name\": \"Example Co\",\n\"publisher\": { \"@id\": \"https://example.com/#organization\" }\n},\n{\n\"@type\": \"WebPage\",\n\"@id\": \"https://example.com/about/#webpage\",\n\"url\": \"https://example.com/about/\",\n\"name\": \"About — Example Co\",\n\"isPartOf\": { \"@id\": \"https://example.com/#website\" },\n\"about\": { \"@id\": \"https://example.com/#organization\" }\n}\n]\n}\n</script>\n@id\nvalues are URIs. Use absolute URLs with a fragment identifier (#\n) to disambiguate entities on the same page:\nhttps://example.com/#organization\n— the Organization entityhttps://example.com/#website\n— the WebSite entityhttps://example.com/#founder\n— the Person entityhttps://example.com/about/#webpage\n— the About page WebPage entityhttps://example.com/blog/post-name/#article\n— an Article entityThe @id\ndoes NOT need to resolve to a real URL. It is just a unique identifier within the graph.\nEvery page on the site declares the same Organization, WebSite, and Person entities (with the same @id\nURIs). Page-specific entities (WebPage, Article, Service, Product) reference back via @id\n:\n{\n\"@type\": \"Article\",\n\"@id\": \"https://example.com/blog/post/#article\",\n\"headline\": \"Post Title\",\n\"author\": { \"@id\": \"https://example.com/#founder\" },\n\"publisher\": { \"@id\": \"https://example.com/#organization\" },\n\"isPartOf\": { \"@id\": \"https://example.com/blog/post/#webpage\" }\n}\nThis cross-referencing is what gives Google's Knowledge Graph the connectivity it needs to attribute Articles to Authors, Authors to Organizations, and Organizations to Knowledge Panel entries.\nEvery meaningful site needs these. Implement them sitewide before any page-specific schema.\nRequired for every site. If the business has a physical location, extend with LocalBusiness; if it serves a profession, extend with ProfessionalService.\n{\n\"@type\": [\"Organization\", \"ProfessionalService\", \"LocalBusiness\"],\n\"@id\": \"https://example.com/#organization\",\n\"name\": \"Example Co\",\n\"alternateName\": [\"example.com\", \"Example\"],\n\"url\": \"https://example.com/\",\n\"logo\": {\n\"@type\": \"ImageObject\",\n\"url\": \"https://example.com/logo.png\",\n\"width\": 600,\n\"height\": 600\n},\n\"image\": \"https://example.com/og-default.png\",\n\"description\": \"Plain-English description matching the site's actual purpose.\",\n\"telephone\": \"+1-505-512-3662\",\n\"email\": \"hello@example.com\",\n\"priceRange\": \"$597-$11997\",\n\"address\": {\n\"@type\": \"PostalAddress\",\n\"streetAddress\": \"123 Main St\",\n\"addressLocality\": \"Cassville\",\n\"addressRegion\": \"MO\",\n\"postalCode\": \"65625\",\n\"addressCountry\": \"US\"\n},\n\"geo\": {\n\"@type\": \"GeoCoordinates\",\n\"latitude\": 36.6811,\n\"longitude\": -93.8702\n},\n\"areaServed\": [\n{ \"@type\": \"AdministrativeArea\", \"name\": \"Northwest Arkansas\" },\n{ \"@type\": \"AdministrativeArea\", \"name\": \"Southwest Missouri\" }\n],\n\"founder\": { \"@id\": \"https://example.com/#founder\" },\n\"foundingDate\": \"2017-01-01\",\n\"sameAs\": [\n\"https://www.wikidata.org/wiki/Q139592631\",\n\"https://www.linkedin.com/company/example\",\n\"https://github.com/example\"\n]\n}\nFor owner-operated businesses, sole-proprietor agencies, and any site with named editorial authors. Critical for E-E-A-T.\n{\n\"@type\": \"Person\",\n\"@id\": \"https://example.com/#founder\",\n\"name\": \"Joseph W. Anady\",\n\"givenName\": \"Joseph\",\n\"additionalName\": \"W.\",\n\"familyName\": \"Anady\",\n\"jobTitle\": \"Founder\",\n\"worksFor\": { \"@id\": \"https://example.com/#organization\" },\n\"image\": \"https://example.com/joseph.jpg\",\n\"url\": \"https://example.com/about/\",\n\"knowsAbout\": [\n\"Technical SEO\", \"Local SEO\", \"AI search optimization\",\n\"Schema markup\", \"SDVOSB digital marketing\"\n],\n\"knowsLanguage\": [\"English\"],\n\"alumniOf\": \"U.S. Army\",\n\"sameAs\": [\n\"https://www.wikidata.org/wiki/Q139592630\",\n\"https://www.linkedin.com/in/josephanady\",\n\"https://github.com/josephanady\"\n]\n}\nCross-reference: framework-eeat.md\nfor Person schema's role in expertise signals; framework-knowledgegraph.md\nfor sameAs network construction.\nDeclares the site itself as an entity. Enables sitelinks search box.\n{\n\"@type\": \"WebSite\",\n\"@id\": \"https://example.com/#website\",\n\"url\": \"https://example.com/\",\n\"name\": \"Example Co\",\n\"publisher\": { \"@id\": \"https://example.com/#organization\" },\n\"inLanguage\": \"en-US\",\n\"potentialAction\": {\n\"@type\": \"SearchAction\",\n\"target\": {\n\"@type\": \"EntryPoint\",\n\"urlTemplate\": \"https://example.com/search?q={search_term_string}\"\n},\n\"query-input\": \"required name=search_term_string\"\n}\n}\nEvery page declares itself as a WebPage. Subtypes when applicable: AboutPage, ContactPage, FAQPage, CollectionPage.\n{\n\"@type\": \"WebPage\",\n\"@id\": \"https://example.com/about/#webpage\",\n\"url\": \"https://example.com/about/\",\n\"name\": \"About — Example Co\",\n\"description\": \"About page meta description.\",\n\"isPartOf\": { \"@id\": \"https://example.com/#website\" },\n\"about\": { \"@id\": \"https://example.com/#organization\" },\n\"primaryImageOfPage\": {\n\"@type\": \"ImageObject\",\n\"url\": \"https://example.com/about-hero.jpg\"\n},\n\"datePublished\": \"2026-01-15\",\n\"dateModified\": \"2026-05-05\",\n\"breadcrumb\": { \"@id\": \"https://example.com/about/#breadcrumb\" }\n}\nFor every non-homepage. Drives breadcrumb display in SERPs.\n{\n\"@type\": \"BreadcrumbList\",\n\"@id\": \"https://example.com/about/#breadcrumb\",\n\"itemListElement\": [\n{\n\"@type\": \"ListItem\",\n\"position\": 1,\n\"name\": \"Home\",\n\"item\": \"https://example.com/\"\n},\n{\n\"@type\": \"ListItem\",\n\"position\": 2,\n\"name\": \"About\",\n\"item\": \"https://example.com/about/\"\n}\n]\n}\nUse Article\n, NewsArticle\n, BlogPosting\n, or TechArticle\ndepending on content. Article\nis the safe default.\n{\n\"@type\": \"Article\",\n\"@id\": \"https://example.com/blog/post-slug/#article\",\n\"headline\": \"Post headline (under 110 characters)\",\n\"description\": \"Meta description.\",\n\"image\": [\n\"https://example.com/post-image-1x1.jpg\",\n\"https://example.com/post-image-4x3.jpg\",\n\"https://example.com/post-image-16x9.jpg\"\n],\n\"author\": { \"@id\": \"https://example.com/#founder\" },\n\"publisher\": { \"@id\": \"https://example.com/#organization\" },\n\"datePublished\": \"2026-04-15T10:00:00-05:00\",\n\"dateModified\": \"2026-05-05T14:30:00-05:00\",\n\"mainEntityOfPage\": { \"@id\": \"https://example.com/blog/post-slug/#webpage\" },\n\"wordCount\": 2500,\n\"articleBody\": \"First 200 characters of body, optional but improves AI extraction.\",\n\"keywords\": [\"technical seo\", \"schema\", \"json-ld\"]\n}\nImage best practice: provide three images at three aspect ratios (1x1, 4x3, 16x9). Google selects the best fit per surface.\nFor service-based businesses describing what they offer.\n{\n\"@type\": \"Service\",\n\"@id\": \"https://example.com/services/local-seo/#service\",\n\"name\": \"Local SEO for Northwest Arkansas\",\n\"description\": \"Description of the service offered.\",\n\"provider\": { \"@id\": \"https://example.com/#organization\" },\n\"serviceType\": \"Local SEO\",\n\"areaServed\": [\n{ \"@type\": \"AdministrativeArea\", \"name\": \"Northwest Arkansas\" }\n],\n\"hasOfferCatalog\": {\n\"@type\": \"OfferCatalog\",\n\"name\": \"Local SEO Services\",\n\"itemListElement\": [\n{\n\"@type\": \"Offer\",\n\"itemOffered\": {\n\"@type\": \"Service\",\n\"name\": \"Google Business Profile setup\"\n},\n\"price\": \"597\",\n\"priceCurrency\": \"USD\"\n}\n]\n}\n}\nCross-reference: framework-ecommerceseo.md\nfor full product schema depth.\n{\n\"@type\": \"Product\",\n\"@id\": \"https://example.com/products/sku-123/#product\",\n\"name\": \"Product Name\",\n\"description\": \"Product description.\",\n\"image\": [\"https://example.com/product.jpg\"],\n\"sku\": \"SKU-123\",\n\"gtin13\": \"1234567890123\",\n\"brand\": { \"@type\": \"Brand\", \"name\": \"Brand Name\" },\n\"offers\": {\n\"@type\": \"Offer\",\n\"url\": \"https://example.com/products/sku-123/\",\n\"pr", "url": "https://wpnews.pro/news/schema-org-json-ld-the-complete-pattern-reference", "canonical_source": "https://dev.to/joseph_anady_214bacedf939/schemaorg-json-ld-the-complete-pattern-reference-143e", "published_at": "2026-05-24 01:03:44+00:00", "updated_at": "2026-05-24 01:32:23.801836+00:00", "lang": "en", "topics": ["developer-tools", "data", "artificial-intelligence", "open-source"], "entities": ["Google", "Schema.org", "JSON-LD", "ThatDevPro", "GitHub", "React", "Vue", "WordPress"], "alternates": {"html": "https://wpnews.pro/news/schema-org-json-ld-the-complete-pattern-reference", "markdown": "https://wpnews.pro/news/schema-org-json-ld-the-complete-pattern-reference.md", "text": "https://wpnews.pro/news/schema-org-json-ld-the-complete-pattern-reference.txt", "jsonld": "https://wpnews.pro/news/schema-org-json-ld-the-complete-pattern-reference.jsonld"}}