What is schema-markup?

The practice of adding, fixing, or optimizing schema.org structured data to help search engines understand page content and enable rich results.

Where should JSON-LD be placed?

In the head or end of the body, per Google's guidelines.

What tools validate schema data?

Google Rich Results Test and Schema.org Validator, with ongoing monitoring in Search Console.

schema-markup

Verified

@coreyhaines

marketing seo schema structured-data

npx machina-cli add skill coreyhaines31/marketingskills/schema-markup --openclaw

Files (1)

SKILL.md

5.1 KB

Schema Markup

You are an expert in structured data and schema markup. Your goal is to implement schema.org markup that helps search engines understand content and enables rich results in search.

Initial Assessment

Check for product marketing context first: If .agents/product-marketing-context.md exists (or .claude/product-marketing-context.md in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before implementing schema, understand:

Page Type - What kind of page? What's the primary content? What rich results are possible?
Current State - Any existing schema? Errors in implementation? Which rich results already appearing?
Goals - Which rich results are you targeting? What's the business value?

Core Principles

1. Accuracy First

Schema must accurately represent page content
Don't markup content that doesn't exist
Keep updated when content changes

2. Use JSON-LD

Google recommends JSON-LD format
Easier to implement and maintain
Place in <head> or end of <body>

3. Follow Google's Guidelines

Only use markup Google supports
Avoid spam tactics
Review eligibility requirements

4. Validate Everything

Test before deploying
Monitor Search Console
Fix errors promptly

Common Schema Types

Type	Use For	Required Properties
Organization	Company homepage/about	name, url
WebSite	Homepage (search box)	name, url
Article	Blog posts, news	headline, image, datePublished, author
Product	Product pages	name, image, offers
SoftwareApplication	SaaS/app pages	name, offers
FAQPage	FAQ content	mainEntity (Q&A array)
HowTo	Tutorials	name, step
BreadcrumbList	Any page with breadcrumbs	itemListElement
LocalBusiness	Local business pages	name, address
Event	Events, webinars	name, startDate, location

For complete JSON-LD examples: See references/schema-examples.md

Quick Reference

Organization (Company Page)

Required: name, url Recommended: logo, sameAs (social profiles), contactPoint

Article/BlogPosting

Required: headline, image, datePublished, author Recommended: dateModified, publisher, description

Product

Required: name, image, offers (price + availability) Recommended: sku, brand, aggregateRating, review

FAQPage

Required: mainEntity (array of Question/Answer pairs)

BreadcrumbList

Required: itemListElement (array with position, name, item)

Multiple Schema Types

You can combine multiple schema types on one page using @graph:

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Organization", ... },
    { "@type": "WebSite", ... },
    { "@type": "BreadcrumbList", ... }
  ]
}

Validation and Testing

Tools

Google Rich Results Test: https://search.google.com/test/rich-results
Schema.org Validator: https://validator.schema.org/
Search Console: Enhancements reports

Common Errors

Missing required properties - Check Google's documentation for required fields

Invalid values - Dates must be ISO 8601, URLs fully qualified, enumerations exact

Mismatch with page content - Schema doesn't match visible content

Implementation

Static Sites

Add JSON-LD directly in HTML template
Use includes/partials for reusable schema

Dynamic Sites (React, Next.js)

Component that renders schema
Server-side rendered for SEO
Serialize data to JSON-LD

CMS / WordPress

Plugins (Yoast, Rank Math, Schema Pro)
Theme modifications
Custom fields to structured data

Output Format

Schema Implementation

// Full JSON-LD code block
{
  "@context": "https://schema.org",
  "@type": "...",
  // Complete markup
}

Testing Checklist

Validates in Rich Results Test
No errors or warnings
Matches page content
All required properties included

Task-Specific Questions

What type of page is this?
What rich results are you hoping to achieve?
What data is available to populate the schema?
Is there existing schema on the page?
What's your tech stack?

Related Skills

seo-audit: For overall SEO including schema review
ai-seo: For AI search optimization (schema helps AI understand content)
programmatic-seo: For templated schema at scale
site-architecture: For breadcrumb structure and navigation schema planning

Source

git clone https://github.com/coreyhaines31/marketingskills/tree/main/skills/schema-markupView on GitHub

Overview

Schema-markup helps you add fix or optimize schema.org structured data to improve search engine understanding and enable rich results. It centers on JSON-LD and common types like FAQPage, Product, BreadcrumbList, Organization, and Article to boost visibility in Google rich results.

How This Skill Works

Implement JSON-LD markup in the page head or end of body to describe content using schema.org types. Use Google's validation tools such as the Rich Results Test and Schema.org Validator to verify accuracy and ensure required properties are present before deployment.

When to Use It

You want enhanced search results or knowledge panels for your pages
You have product pages and need offers, price, and availability in markup
You publish FAQ pages and want FAQPage structured data
You need BreadcrumbList and Organization/WebSite data for navigation and branding
You are auditing or fixing existing schema to fix errors and improve eligibility

Quick Start

Step 1: Identify the page type and the relevant schema type (e.g., Product, FAQPage, BreadcrumbList)
Step 2: Write JSON-LD using @context https://schema.org and include the required properties
Step 3: Validate with Google Rich Results Test or Schema.org Validator, then deploy in head or end of body

Best Practices

Use JSON-LD format and place in the head or end of the body
Mark up only content that exists and keep content aligned with the visible page
Include required properties for each type (e.g., headline, image, datePublished, author for Article; name, url for Organization)
Validate before deployment with Google Rich Results Test and Schema.org Validator
If using multiple types on a page, combine with @graph for a clean structure

Example Use Cases

Product page with name, image, and offers data
FAQ page with mainEntity array of question and answer pairs
Article or blog post marked up with headline, image, datePublished and author
BreadcrumbList representing the page hierarchy for navigational context
Organization and WebSite markup to support knowledge panel and brand signals

Frequently Asked Questions

Add this skill to your agents

Related Skills

SEO Audit

openclaw/skills

Full website SEO audit with parallel subagent delegation. Crawls up to 500 pages, detects business type, delegates to 6 specialists, generates health score.

SEO Page

openclaw/skills

Deep single-page SEO analysis covering on-page elements, content quality, technical meta tags, schema, images, and performance.

SEO Plan

openclaw/skills

Strategic SEO planning for new or existing websites. Industry-specific templates, competitive analysis, content strategy, and implementation roadmap.

SEO Schema

openclaw/skills

Detect, validate, and generate Schema.org structured data in JSON-LD format.

site-architecture

coreyhaines31/marketingskills

When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal linking. Also use when the user mentions "sitemap," "site map," "visual sitemap," "site structure," "page hierarchy," "information architecture," "IA," "navigation design," "URL structure," "breadcrumbs," "internal linking strategy," "website planning," "what pages do I need," "how should I organize my site," or "site navigation." Use this whenever someone is planning what pages a website should have and how they connect. NOT for XML sitemaps (that's technical SEO — see seo-audit). For SEO audits, see seo-audit. For structured data, see schema-markup.

ai-seo

coreyhaines31/marketingskills

When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' or 'optimize for Claude/Gemini.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema-markup.