Advanced structured data and schema implementation for headless Wix

Headless Wix removes every limitation the standard platform places on structured data markup. You can implement any Schema.org type with any level of nesting, reference entities across pages using @id identifiers, connect your Organization to your WebSite to your WebPages to your Products and Articles, and build the kind of comprehensive knowledge graph that gives you maximum visibility in rich results, AI-generated search features, and voice search. This lesson covers how to design a sitewide schema graph, generate schema programmatically from Wix API data, implement schema types that are uniquely practical in a headless context, and validate your implementation through a systematic testing workflow.

Building a Sitewide Schema Graph with @graph

Instead of placing isolated, unconnected schema blocks on individual pages, a sitewide schema graph creates a web of @id-linked entities that tell Google exactly how every piece of content on your site relates to every other piece. Your Organization entity lives at https://example.com/#organization. Your WebSite entity at https://example.com/#website links to it via the publisher property. Every WebPage links to the WebSite via isPartOf, and every Article links to the WebPage via mainEntityOfPage. This explicit graph of relationships is precisely what Google uses to build its understanding of your entity — and that entity understanding is the foundation of E-E-A-T signals.

Using the @graph array inside a single JSON-LD script tag, you can include all the entities relevant to a given page in one block. This is cleaner than multiple script tags, makes the inter-entity relationships visually explicit in your code, and is the format recommended in Google's own documentation. In your Next.js layout, place the sitewide entities (Organization, WebSite) in every page's schema graph, then add the page-specific entities (Article, Product, BreadcrumbList) in each page template's schema.

Implementing a connected schema graph with @id entity linking

• Define canonical @id identifiers for your core entities in a constants file: ORGANIZATION_ID = "https://example.com/#organization", WEBSITE_ID = "https://example.com/#website"
• Create a buildOrganizationSchema() function in lib/schema.ts that returns the Organization entity with the @id set to ORGANIZATION_ID, name, url, logo, sameAs (social profiles), and contactPoint properties
• Create a buildWebSiteSchema() function that returns the WebSite entity with @id set to WEBSITE_ID, url, name, publisher referencing the Organization @id, and a potentialAction SearchAction for sitelinks search box
• Create a buildWebPageSchema(page) function that accepts page data and returns a WebPage (or subtype like AboutPage, ContactPage) with isPartOf referencing WEBSITE_ID and breadcrumb referencing your BreadcrumbList @id
• In your root layout.tsx, include Organization and WebSite in a base schema script tag on every page using the @graph pattern
• In each page template, build the page-specific schema entities and merge them with the base entities into a single @graph array before rendering the script tag
• Use @id references instead of duplicating entity data: in your Article schema, set publisher: { "@id": ORGANIZATION_ID } rather than re-declaring the full Organization object
• For blog posts, set mainEntityOfPage: { "@id": "https://example.com/blog/[post-slug]/#webpage" } in the Article schema to link it to the corresponding WebPage entity
• Test the @graph structure using the Google Rich Results Test — verify that Google can resolve the @id references and recognises the entity relationships
• Use the Schema Markup Validator at validator.schema.org to check for syntax errors and missing required properties across the entire @graph structure

Dynamic Schema Generation from Wix API Data

Schema markup is only as accurate as the data that populates it, which means hardcoded schema blocks are always wrong within days of publication as prices change, availability updates, and content is edited. On headless Wix, generate all schema markup dynamically from the live API data you fetch for each page render. Write pure functions in lib/schema.ts that accept typed Wix API response objects and return valid Schema.org JSON-LD — the same data used to render the visible page populates the invisible schema, so they are always perfectly in sync.

• Write buildProductSchema(product) that maps Wix eCommerce product fields to Product schema: name from product.name, description from product.description, image from product.media.mainMedia.image.url, offers from product.priceData, brand from product.brand
• Write buildArticleSchema(post, author) that maps Wix Blog post fields to Article schema: headline from post.title (truncated to 110 chars), author from post.author, datePublished from post.firstPublishedDate, dateModified from post.lastPublishedDate
• Write buildLocalBusinessSchema(businessInfo) that maps Wix Business Info fields to LocalBusiness schema: name, address, telephone, openingHours, geo coordinates, and priceRange
• Write buildFAQSchema(faqs) that maps a Wix CMS FAQ collection to FAQPage schema: each item becomes a Question entity with acceptedAnswer containing the answer text
• Write buildBreadcrumbSchema(crumbs) as a pure function accepting an array of { name, url } objects and returning a BreadcrumbList with correctly numbered ListItem entries
• Write buildItemListSchema(items, listName) for category and collection pages that maps a list of post or product previews to an ItemList schema with ListItem entries numbered from 1
• Export all schema builder functions from a single lib/schema.ts file and import only what each page template needs — tree shaking ensures unused schema builders do not increase bundle size
• Add TypeScript interfaces for each schema output type so TypeScript catches missing required properties at compile time rather than at runtime
• Write unit tests for each schema builder function asserting that required properties are always present and correctly typed in the output
• Log schema generation errors to your error monitoring service (Sentry, Datadog) so missing or invalid API data that would produce broken schema is immediately visible

Schema Types Unique to Headless Implementation

Standard Wix sites support a limited set of schema types through the built-in SEO tools. Headless Wix lets you implement every Schema.org type, including several that are particularly valuable for performance-oriented or content-rich sites. The following schema types are either difficult or impossible to implement on the standard Wix platform but straightforward on a headless frontend.

• ItemList schema for category pages with product or post listings — include the @id, url, name, and position for each ListItem so Google can display category items as rich results
• BreadcrumbList schema generated programmatically from your URL path structure — every segment of the URL becomes a ListItem with its name and URL
• VideoObject schema for Wix video content embedded in blog posts — use the Wix Media API to get the video duration, thumbnail URL, upload date, and description
• HowTo schema for tutorial or instructional content authored in the Wix Blog — map numbered steps in your content to HowToStep entities with name, text, and optionally image
• SpeakableSpecification for voice search optimisation — mark up specific sections of your content (headline and first paragraph) as speakable to help Google Assistant read your content aloud
• SoftwareApplication schema for pages describing web application features — useful if your Wix-powered site promotes a SaaS product or app alongside content
• Event schema for Wix Bookings or events content — map the event name, startDate, endDate, location, and organizer to Event schema so events appear in Google's event rich results
• Review and AggregateRating schema for product and service pages using ratings stored in Wix CMS collections — enables star ratings in search results which significantly improve click-through rates

Testing and Validating Complex Schema

Schema validation workflow for headless Wix sites

• Use the Google Rich Results Test (search.google.com/test/rich-results) to test each unique page template — enter the URL of a representative page of each type (home, product, blog post, category, FAQ)
• The Rich Results Test shows which rich result types your schema qualifies for and lists specific errors that prevent eligibility — fix all errors, then recheck
• Validate the raw schema syntax using the Schema Markup Validator at validator.schema.org — paste your JSON-LD directly to catch structural errors that the Rich Results Test may not surface
• Check that @id references resolve correctly by verifying they point to URLs that exist or use the /#identifier fragment pattern consistently across all schema on your site
• In Google Search Console, navigate to Enhancements to see reports for each rich result type (Products, Articles, Breadcrumbs, FAQs) — these reports show real errors Google encountered while crawling your pages
• Set up automated schema testing in your CI/CD pipeline using a custom script that fetches each page type's HTML, extracts the JSON-LD script tag content, and validates it against the Schema.org specification
• Monitor rich result appearance using Google Search Console's Performance report — filter by Search Appearance to see impressions and clicks for each rich result type separately from regular organic results
• Test schema rendering in staging before deploying to production by running your staging URL through the Rich Results Test — some schema errors only appear with production data
• After launching new schema types, wait 2-4 weeks for Google to recrawl and index the structured data before evaluating whether rich results are appearing
• Set up a Google Search Console API integration or use a tool like Ahrefs to alert you when previously valid schema starts returning errors — schema can break when CMS data structure changes