seo-schema

# seo-schema

Lint existing JSON-LD and generate templates. Pure analysis/templating — no network.

## When to use

- The diagnose flow wants structured-data findings + which schema types the page should add.
- The apply/content flow needs a paste-ready JSON-LD snippet for a type.

## When NOT to use

- Coarse "has any structured data?" — `seo-tech-audit` already flags that. This goes deeper (per-node lint, recommendations, generation).
- Writing the JSON-LD into source — the agent does that (with this skill's generated snippet).

## Preconditions

- For `validate`: a `seo-crawl` JSON (uses each page's parsed `structured_data`). Python 3.9+ stdlib only.

## How to call

Validate existing JSON-LD + recommend types:
```
"$ORKAS_NODE" "$ORKAS_PC_DIR/bin/run-skill.cjs" seo-schema schema -- --op validate --input <crawl.json> [--out <schema.json>]
```

Generate a template (for apply/content mode):
```
"$ORKAS_NODE" "$ORKAS_PC_DIR/bin/run-skill.cjs" seo-schema schema -- --op generate --type Organization [--json '{"name":"Orkas","url":"https://orkas.ai"}']
```

## Expected output

`validate`:
```json
{ "ok": true, "data": {
  "schema_score": 96, "present_types": ["Organization"], "recommended_types": ["WebSite"],
  "findings": [ { "id": "schema_recommend", "dimension": "schema", "severity": "low", ... } ],
  "summary": { "total": 1 }, "meta": { "url": "..." } } }
```
Findings use `dimension: "schema"` and feed `seo-report --add`.

`generate`: `{ "ok": true, "data": { "jsonld": { "@context": "https://schema.org", "@type": "Organization", ... } } }`. Emit the `jsonld` object as a `<script type="application/ld+json">` block; **the JSON-LD must match the visible page one-to-one** (esp. FAQ Q&A). Failure: `{"ok": false, "error": "..."}`, non-zero exit.

## Lint coverage

Missing `@type`; missing required fields (Organization/WebSite/SoftwareApplication/Article/FAQPage/BreadcrumbList/Product/HowTo); deprecated rich-result types (FAQPage/HowTo still valid markup but no rich result for most sites); recommended types by page role (home → Organization+WebSite; deep page → BreadcrumbList). `@graph` is expanded.