structured-data

Structured Data

Fixes the AI Search Signals category of IsAgentReady.com. These checkpoints test if the site gives machine-readable context that AI search products can use and cite.

• Methodology version: 2026-10-22. Methodology: https://isagentready.com/en/methodology
• Scoring (weights and points): https://isagentready.com/api/v2/methodology/2026-10-22/scoring
• Full checkpoint data (stage, evidence type, verify command, rescan command): references/checkpoints.md

The scanner reads the first HTML response. It does not run JavaScript. JSON-LD that only JavaScript adds does not count.

When to Use

• The scan shows failures in AI Search Signals (legacy ids 2.x).
• The user asks to add or fix JSON-LD, structured data or schema markup.
• The site needs Organization, WebSite, Product, Article, FAQPage or author markup.
• The site has no about, contact or privacy page.

When NOT to Use

• Microdata or RDFa: this skill covers JSON-LD only.
• Open Graph or Twitter Card tags: they are for social previews.
• robots.txt, sitemap or AI crawler access: use ai-content-discovery.
• Semantic HTML or headings: use content-semantics.
• Security headers: use security-trust.

Instructions

1. Get the failing checkpoints from the scan. Each result has a legacy id (2.2) and a stable id (ia.organization-schema).
2. Go to the fix workflow with the anchor that is equal to the stable id.
3. Adapt the example to the site. Replace example.com with the domain of the site.
4. Validate with the Schema.org Validator and run the verify command.
5. Rescan with isagentready results <domain> --checkpoint <stable-id> or at isagentready.com.

If $ARGUMENTS is provided, use it as the URL to fix or as the checkpoint to fix.

Checkpoints

Strength is the agentready.org spec level (MUST, SHOULD, MAY). Strength does not change the score.

Legacy	Stable ID	Name	AR IDs	Strength
2.1	ia.json-ld	JSON-LD present	AR-READ-08	SHOULD
2.2	ia.organization-schema	Organization / WebSite schema	AR-READ-08	SHOULD
2.3	ia.high-value-schema	High-value schema types	AR-READ-08	SHOULD
2.4	ia.entity-linking	Entity linking via @id	AR-READ-08	SHOULD
2.6	ia.schema-validation	Schema validation	AR-READ-08	SHOULD
2.7	ia.faq-schema	FAQPage schema	AR-READ-08	SHOULD
2.8	ia.author-attribution	Author attribution	AR-READ-08	SHOULD
2.9	ia.trust-pages	Trust anchor pages	none	SHOULD

Quick Path

For a site without structured data, add one @graph block with Organization, WebSite and the main content type. Give each entity an @id and an author. This block fixes 2.1, 2.2, 2.3, 2.4 and 2.8 together. The full template is in references/json-ld-patterns.md.

Fix Workflows

2.1 JSON-LD present

Passes when the HTML has one or more <script type="application/ld+json"> blocks with valid JSON and a @context of https://schema.org.

1. Add a JSON-LD block to the <head> in the server HTML:

   <script type="application/ld+json">
   { "@context": "https://schema.org", "@type": "Organization",
     "name": "Example Inc", "url": "https://example.com" }
   </script>
   

2. Make sure that the JSON is valid. A trailing comma breaks the block.

Verify: curl -sf https://example.com/ | grep -q 'application/ld+json'

2.2 Organization / WebSite schema

Passes when JSON-LD has Organization or WebSite with name and url. logo, sameAs and contactPoint give more context.

1. Add the Organization entity:

   {
     "@context": "https://schema.org",
     "@type": "Organization",
     "name": "Example Inc",
     "url": "https://example.com",
     "logo": "https://example.com/logo.png",
     "sameAs": ["https://www.linkedin.com/company/example", "https://github.com/example"],
     "contactPoint": { "@type": "ContactPoint", "email": "[email protected]", "contactType": "customer service" }
   }
   

2. Add a WebSite entity with a SearchAction when the site has search. See references/json-ld-patterns.md.

Verify: curl -sf https://example.com/ | grep -qE '"@type": *"(Organization|WebSite)"'

2.3 High-value schema types

Passes when the page has one high-value type with its required properties. The types are Article, NewsArticle, BlogPosting, Product, SoftwareApplication, WebApplication, MobileApplication, LocalBusiness, Service, FAQPage, QAPage, HowTo, Course, JobPosting, VideoObject, Event and Recipe.

1. Select the type that matches the page content. For example, a product page:

   {
     "@context": "https://schema.org",
     "@type": "Product",
     "name": "Planner Pro",
     "description": "Project planning software for small teams",
     "offers": { "@type": "Offer", "price": "12.00", "priceCurrency": "USD" }
   }
   

2. Fill all required properties. The templates for each type are in references/schema-types.md.

Verify: curl -sf https://example.com/ | grep -oE '"@type": *"[A-Za-z]+"' | sort -u

2.4 Entity linking via @id

Passes when entities have an @id and refer to each other by @id. An @id without a reference gives partial credit.

1. Give each entity an @id with the pattern <url>#<type>. Refer to it from other entities:

   {
     "@context": "https://schema.org",
     "@graph": [
       { "@type": "Organization", "@id": "https://example.com/#organization", "name": "Example Inc", "url": "https://example.com" },
       { "@type": "WebSite", "@id": "https://example.com/#website", "url": "https://example.com",
         "publisher": { "@id": "https://example.com/#organization" } }
     ]
   }
   

Verify: curl -sf https://example.com/ | grep -c '"@id"' (expect 2 or more)

2.6 Schema validation

Passes when the JSON-LD has no duplicate @type in one block, no missing required properties and no empty required values.

1. Remove a second entity of the same type from one @graph, or merge the two entities.
2. Replace empty values such as "name": "" with real values.
3. Use the PascalCase type name: Organization, not organization.
4. Run the page through the Schema.org Validator.

Verify: no read-only shell check exists. Use the validator and the rescan command.

2.7 FAQPage schema

Applies when the page shows FAQ content or has FAQPage JSON-LD. Passes when each Question has an acceptedAnswer and the questions are also visible on the page.

1. Mark up the visible questions and answers:

   {
     "@context": "https://schema.org",
     "@type": "FAQPage",
     "mainEntity": [{
       "@type": "Question",
       "name": "Can I cancel at any time?",
       "acceptedAnswer": { "@type": "Answer", "text": "Yes. You can cancel in the billing settings." }
     }]
   }
   

2. Do not mark up questions that the page does not show.

Verify: curl -sf https://example.com/ | grep -q '"FAQPage"' (on a page with a visible FAQ)

2.8 Author attribution

Passes when JSON-LD has an author with @type Person or Organization and a name. <meta name="author"> or rel="author" gives partial credit.

1. Add the author to the content entity:

   { "@context": "https://schema.org", "@type": "Article", "headline": "Plan a sprint",
     "author": { "@type": "Person", "name": "Jane Smith", "url": "https://example.com/authors/jane" } }
   

2. For company content, use "@type": "Organization". Do not use a plain string as the author.

Verify: curl -sf https://example.com/ | grep -qE '"author"|name="author"|rel="author"'

2.9 Trust anchor pages

Passes when the about, contact and privacy pages return 2xx with 500 or more characters of visible text. The scanner follows same-origin homepage links, also with local paths such as /over-ons. It then tries /about, /contact and /privacy.

1. Publish the three pages with real content as server HTML.
2. Link them from the homepage, for example in the footer:

   <footer>
     <nav aria-label="Company">
       <a href="/about">About Example Inc</a>
       <a href="/contact">Contact</a>
       <a href="/privacy">Privacy policy</a>
     </nav>
   </footer>
   

Verify: curl -sI https://example.com/about https://example.com/contact https://example.com/privacy | grep -i '^HTTP/'

Key Gotchas

1. JSON without "@context": "https://schema.org" does not count.
2. A trailing comma makes the whole block invalid.
3. Two Organization entities in one @graph cause a validation issue.
4. "author": "Jane Smith" (a string) fails. Use an object with @type and name.
5. FAQPage markup for questions that are not visible on the page gives partial credit.

See references/gotchas.md for correct and incorrect examples.

References

• references/checkpoints.md: generated checkpoint data for each checkpoint
• references/schema-types.md: JSON-LD templates for each Schema.org type
• references/json-ld-patterns.md: @graph, entity linking, SearchAction and combined types
• references/gotchas.md: common errors with correct and incorrect examples