---
name: structured-data-testing-tool
description: >
  Validate structured data (JSON-LD) on any URL using the XooCode API.
  Use when user says "test structured data", "validate schema",
  "check JSON-LD", "structured data testing tool", "test markup",
  or provides a URL to check for schema.org issues.
---

# Structured Data Testing Tool

Validate JSON-LD structured data on any URL using the XooCode Structured Data Validation API.

## Setup (first run only)

Before calling the API, check if the user has an API key configured.

Look for the key in this order:
1. Environment variable: `XOOCODE_API_KEY`
2. File: `~/.xoocode/api-key`

If neither exists, guide the user through setup:

1. "You need a XooCode API key. Let me walk you through it."
2. "Sign up at https://xoocode.com/signup and verify your email."
3. "Go to https://xoocode.com/account/api-keys and create a key."
4. "Copy the key (it is shown once) and I will save it for you."
5. Ask the user to paste the key.
6. Save to `~/.xoocode/api-key` (create the directory if needed).
7. Confirm: "API key saved. You are ready to validate structured data."

## Validating a URL

The URL comes from `$ARGUMENTS` or the user's message. If no URL provided, ask for one. Prepend `https://` if no protocol.

Read the API key from the env or file, then call:

```bash
curl -s -X POST https://xoocode.com/api/v1/validate/url/ \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <API_KEY>" \
  -d '{"url": "<URL>"}'
```

The response JSON contains:
- `summary`: total blocks, errors, warnings
- `blocks`: per-block findings with path, value, message, suggestion
- `prompt`: markdown fix instructions ready to use
- `usage`: current API quota

## Presenting results

**No issues:** Report all checks passed, list block types found.

**Issues found:**
1. Summary line: "Found X blocks, Y errors, Z warnings on <URL>"
2. Per block with issues: type, name, each finding with path, value, message, suggestion
3. Offer to fix if in the relevant codebase

## Fixing issues

If in a codebase that generates the tested markup:
- Use the `prompt` field as your fix guide
- Locate source files that generate each schema block
- Apply suggested fixes
- Ask before making changes

## Error handling

- 401: API key missing or invalid. Run setup again.
- 429: Rate limit exceeded. Show usage and reset time.
- NO_BLOCKS: No JSON-LD found on the page.
- FETCH_FAILED: Could not reach the URL.

## Usage

After results, show: "API usage: X / Y requests this [period]."

Free tier: 50 requests/month. Pro (19.99/month): 500/day.
Manage at https://xoocode.com/account/api-keys