Schema Validation for AI Agents

// Register SchemaCheck as a tool in any LLM framework
const tools = [
  {
    name: "validate_schema",
    description: `Validate Schema.org JSON-LD structured data on a URL or raw JSON-LD object.
Returns: errors (required properties missing), warnings (recommended missing),
rich_result_eligible (boolean), and a 0-100 health score.
Use this when the user asks about structured data, rich results, or schema markup.`,
    parameters: {
      type: "object",
      properties: {
        url: {
          type: "string",
          description: "The public URL to fetch and validate. Use this if the schema is on a live page.",
        },
        jsonld: {
          type: "object",
          description: "Raw JSON-LD object to validate directly. Use this for inline schema review.",
        },
      },
    },
    execute: async ({ url, jsonld }) => {
      const endpoint = "https://schemacheck.dev/api/v1/validate";
      const apiKey = process.env.SCHEMACHECK_API_KEY;

      if (url) {
        const res = await fetch(`${endpoint}?url=${encodeURIComponent(url)}&access_key=${apiKey}`);
        return res.json();
      }

      const res = await fetch(endpoint, {
        method: "POST",
        headers: { "Content-Type": "application/json", "x-api-key": apiKey },
        body: JSON.stringify({ jsonld }),
      });
      return res.json();
    },
  },
];

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const tools: Anthropic.Tool[] = [
  {
    name: "validate_schema",
    description: "Validate Schema.org structured data on a URL. Returns errors, warnings, rich result eligibility, and a health score.",
    input_schema: {
      type: "object",
      properties: {
        url: { type: "string", description: "Public URL to validate" },
      },
      required: ["url"],
    },
  },
];

async function runSchemaAgent(userMessage: string) {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  while (true) {
    const response = await client.messages.create({
      model: "claude-opus-4-6",
      max_tokens: 4096,
      tools,
      messages,
    });

    if (response.stop_reason === "end_turn") {
      return response.content.find((b) => b.type === "text")?.text;
    }

    // Handle tool use
    const toolUses = response.content.filter((b) => b.type === "tool_use");
    const toolResults: Anthropic.MessageParam = {
      role: "user",
      content: await Promise.all(
        toolUses.map(async (toolUse) => {
          if (toolUse.type !== "tool_use") return null!;
          const { url } = toolUse.input as { url: string };
          const res = await fetch(
            `https://schemacheck.dev/api/v1/validate?url=${encodeURIComponent(url)}&access_key=${process.env.SCHEMACHECK_API_KEY}`
          );
          const data = await res.json();
          return {
            type: "tool_result" as const,
            tool_use_id: toolUse.id,
            content: JSON.stringify(data),
          };
        })
      ),
    };

    messages.push({ role: "assistant", content: response.content }, toolResults);
  }
}

// Example usage
const result = await runSchemaAgent(
  "Audit the structured data on https://stripe.com and tell me what's preventing rich results."
);
console.log(result);

// ~/.cursor/mcp.json  (or Claude Desktop config)
{
  "mcpServers": {
    "schemacheck": {
      "command": "node",
      "args": ["/path/to/schemacheck-mcp/dist/index.js"],
      "env": {
        "SCHEMACHECK_API_KEY": "sc_live_your_key_here"
      }
    }
  }
}

// Once installed, your AI assistant can call it natively:
// User: "Validate the schema on stripe.com"
// Claude: <calls validate_schema tool> → returns full analysis

from langchain.tools import tool
from langchain_anthropic import ChatAnthropic
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate
import requests
import os

@tool
def validate_schema(url: str) -> dict:
    """Validate Schema.org structured data on a URL.
    Returns errors, warnings, rich result eligibility, and a 0-100 score."""
    resp = requests.get(
        "https://schemacheck.dev/api/v1/validate",
        params={"url": url, "access_key": os.environ["SCHEMACHECK_API_KEY"]},
        timeout=30,
    )
    return resp.json()

llm = ChatAnthropic(model="claude-opus-4-6")
tools = [validate_schema]

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are an SEO expert. When asked about structured data, use the validate_schema tool."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

result = executor.invoke({
    "input": "Check if https://shopify.com has valid Product schema markup for Google Shopping."
})
print(result["output"])