Schema Markup skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Schema Markup"
  short_description: "JSON-LD that matches the page and passes Google"
  default_prompt: "$schema-markup Add Product and Breadcrumb structured data to our product page template"

#!/usr/bin/env python3
"""Extract and lint JSON-LD from HTML files or URLs. Standard library only.

  python3 scripts/check_jsonld.py page.html [more.html ...]
  python3 scripts/check_jsonld.py https://www.example.com/product/1   # needs network
  python3 scripts/check_jsonld.py out/**/*.html --summary              # many build files

Checks: JSON syntax, @context, @graph flattening, Google-required properties for common
rich result types, absolute URLs, ISO 8601 dates, retired rich result types, and whether
key strings (name/headline/price) appear in the page's visible text.
This is a fast pre-check; confirm eligibility with Google's Rich Results Test.
Exit codes: 0 no errors, 1 errors found, 2 nothing could be read.
"""
from __future__ import annotations

import argparse
import html
import json
import re
import sys
import urllib.request
from html.parser import HTMLParser

# Required properties (all must be present). "a|b" means at least one of a or b.
REQUIRED = {
    "Article": [], "NewsArticle": [], "BlogPosting": [],
    "Product": ["name", "offers|review|aggregateRating"],
    "Offer": ["price|priceSpecification"],
    "BreadcrumbList": ["itemListElement"],
    "ListItem": ["position"],
    "Event": ["name", "startDate", "location"],
    "Recipe": ["name", "image"],
    "JobPosting": ["title", "description", "datePosted", "hiringOrganization"],
    "VideoObject": ["name", "thumbnailUrl", "uploadDate"],
    "LocalBusiness": ["name", "address"],
    "Organization": [],
    "SoftwareApplication": ["name", "offers"],
    "AggregateRating": ["ratingValue", "ratingCount|reviewCount"],
    "Review": ["author", "reviewRating"],
    "ProfilePage": ["mainEntity"],
    "DiscussionForumPosting": ["author", "datePublished", "text|image|video"],
    "Dataset": ["name", "description"],
}
RECOMMENDED = {
    "Article": ["headline", "image", "datePublished", "author"],
    "NewsArticle": ["headline", "image", "datePublished", "author"],
    "BlogPosting": ["headline", "image", "datePublished", "author"],
    "Product": ["image", "description"],
    "Offer": ["priceCurrency", "availability"],
    "Organization": ["name", "url", "logo"],
    "LocalBusiness": ["telephone", "openingHoursSpecification", "geo", "url"],
    "Event": ["image", "description", "endDate", "eventStatus", "offers", "organizer"],
    "JobPosting": ["jobLocation|applicantLocationRequirements", "validThrough", "baseSalary"],
}
LOCAL_SUBTYPES = ("Restaurant", "Store", "Dentist", "MedicalBusiness", "AutoRepair",
                  "LegalService", "HomeAndConstructionBusiness", "FoodEstablishment")
RETIRED = {
    "FAQPage": "FAQ rich results were retired in 2026; markup is harmless but earns no rich result",
    "HowTo": "HowTo rich results were removed in 2023",
}
URL_KEYS = {"url", "image", "logo", "thumbnailUrl", "contentUrl", "embedUrl", "item", "sameAs", "@id"}
DATE_KEYS = {"datePublished", "dateModified", "uploadDate", "startDate", "endDate", "datePosted",
             "validThrough", "priceValidUntil"}
ISO = re.compile(r"^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$")


class Extract(HTMLParser):
    def __init__(self):
        super().__init__(convert_charrefs=True)
        self.blocks: list[str] = []
        self.text: list[str] = []
        self._ld = False
        self._skip = 0

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag == "script" and (a.get("type") or "").lower().strip() == "application/ld+json":
            self._ld = True
            self.blocks.append("")
        elif tag in ("script", "style", "noscript", "template"):
            self._skip += 1

    def handle_endtag(self, tag):
        if tag == "script" and self._ld:
            self._ld = False
        elif tag in ("script", "style", "noscript", "template") and self._skip:
            self._skip -= 1

    def handle_data(self, data):
        if self._ld:
            self.blocks[-1] += data
        elif not self._skip:
            self.text.append(data)


def load(src: str) -> str:
    if re.match(r"^https?://", src):
        req = urllib.request.Request(src, headers={"User-Agent": "jsonld-check/1.0"})
        with urllib.request.urlopen(req, timeout=30) as r:
            return r.read().decode(r.headers.get_content_charset() or "utf-8", "replace")
    with open(src, encoding="utf-8", errors="replace") as fh:
        return fh.read()


def types_of(node: dict) -> list[str]:
    t = node.get("@type", [])
    return [x.split("/")[-1] for x in (t if isinstance(t, list) else [t]) if isinstance(x, str)]


def walk(node, path="$"):
    """Yield (path, dict) for every typed object, descending into nested values."""
    if isinstance(node, list):
        for i, item in enumerate(node):
            yield from walk(item, f"{path}[{i}]")
    elif isinstance(node, dict):
        if "@type" in node:
            yield path, node
        for k, v in node.items():
            if isinstance(v, (dict, list)):
                yield from walk(v, f"{path}.{k}")


def has(node: dict, spec: str) -> bool:
    return any(node.get(k) not in (None, "", []) for k in spec.split("|"))


def check_values(node: dict, path: str, errors: list, warns: list) -> None:
    for k, v in node.items():
        vals = v if isinstance(v, list) else [v]
        for val in vals:
            if k in URL_KEYS and isinstance(val, str) and k != "@id":
                if not re.match(r"^https?://", val):
                    warns.append(f"{path}.{k} is not an absolute URL: {val!r}")
            if k in DATE_KEYS and isinstance(val, str) and not ISO.match(val.strip()):
                errors.append(f"{path}.{k} is not ISO 8601: {val!r}")
    if "price" in node and isinstance(node["price"], str) and re.search(r"[^\d.]", node["price"]):
        errors.append(f"{path}.price must be a number without currency symbols or commas: {node['price']!r}")


def audit(src: str, raw: str) -> tuple[list[str], list[str], list[str]]:
    p = Extract()
    p.feed(raw)
    visible = html.unescape(" ".join(" ".join(p.text).split())).lower()
    errors, warns, found = [], [], []
    if not p.blocks:
        warns.append("no application/ld+json blocks found (microdata/RDFa not checked)")
    for i, block in enumerate(p.blocks):
        try:
            data = json.loads(block)
        except json.JSONDecodeError as exc:
            errors.append(f"block {i}: invalid JSON ({exc.msg} at line {exc.lineno} col {exc.colno})")
            continue
        roots = data if isinstance(data, list) else [data]
        for r in roots:
            if isinstance(r, dict) and "schema.org" not in str(r.get("@context", "")):
                warns.append(f"block {i}: missing or unexpected @context {r.get('@context')!r}")
        for path, node in walk(data, f"block{i}"):
            for t in types_of(node):
                found.append(t)
                key = "LocalBusiness" if t in LOCAL_SUBTYPES else t
                if t in RETIRED:
                    warns.append(f"{path} {t}: {RETIRED[t]}")
                for spec in REQUIRED.get(key, []):
                    if not has(node, spec):
                        errors.append(f"{path} {t}: missing required {spec.replace('|', ' or ')}")
                for spec in RECOMMENDED.get(key, []):
                    if not has(node, spec):
                        warns.append(f"{path} {t}: missing recommended {spec.replace('|', ' or ')}")
                for prop in ("name", "headline"):
                    val = node.get(prop)
                    if isinstance(val, str) and len(val) > 3 and t not in ("Organization", "ListItem", "Person", "Brand", "WebSite"):
                        if val.lower().strip() not in visible:
                            warns.append(f"{path} {t}.{prop} not found in visible text: {val[:60]!r}")
                if t == "Offer" and "price" in node:
                    price = str(node["price"])
                    if price not in visible and price.rstrip("0").rstrip(".") not in visible:
                        warns.append(f"{path} Offer.price {price} not found in visible text")
            check_values(node, path, errors, warns)
    return errors, warns, found


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("sources", nargs="+")
    ap.add_argument("--summary", action="store_true", help="one line per file instead of full detail")
    args = ap.parse_args()
    total_err, readable = 0, 0
    for src in args.sources:
        try:
            raw = load(src)
        except Exception as exc:
            print(f"{src}: cannot read ({exc})")
            continue
        readable += 1
        errors, warns, found = audit(src, raw)
        total_err += len(errors)
        types = ", ".join(sorted(set(found))) or "none"
        if args.summary:
            print(f"{'FAIL' if errors else 'ok  '} {src}  types=[{types}] errors={len(errors)} warnings={len(warns)}")
            continue
        print(f"== {src}\n   types: {types}")
        for e in errors:
            print(f"   ERROR {e}")
        for w in warns:
            print(f"   WARN  {w}")
    if not readable:
        return 2
    return 1 if total_err else 0


if __name__ == "__main__":
    sys.exit(main())