docs: design the schema.org vocabulary catalog for seo/json-ld-validity

[oekazuma]

Refs #421 (spike deliverable — implementation will follow as a separate PR once this design is agreed).

Answers the spike's four questions with verified facts about schema-dts 2.0.0 (types-only, one ~992 KB schema.d.ts, ~1,000 exported type aliases, @deprecated JSDoc on superseded terms):

1. Scope: @type existence only. Property-name and property-domain validation are rejected, not deferred — schema.org explicitly tolerates extension properties and Google ignores unknown ones, so a property check would flag legitimate markup forever.
2. Home: a new arm of seo/json-ld-validity (it already owns "malformed at the JSON-LD level"; unknown type fires at the rule's registered warning, no severity split). Includes a cheap case-insensitive did-you-mean suggestion.
3. Case / contexts: exact case-sensitive matching; any non-schema.org (or remapping) @context exempts the document — silence over false positives on exotic contexts.
4. Size: names-only catalog ≈ 20 KB committed in core; the only expensive option (property-domain map) falls away with Q1.

Mechanism follows the repo's committed-generated-file pattern (docs/generated.ts, action-pin.generated.ts): schema-dts as a catalog devDependency, a generator script parsing schema.d.ts with the TypeScript compiler API (alias-vs-interface distinction does the filtering; count sanity band 700–1,500), and a drift test so a Renovate bump of schema-dts fails CI until the catalog is regenerated — that drift test is the currency mechanism.

The doc also pre-registers the phase-1 implementation requirements: new penalized findings can appear on existing projects (declared-gate-movement changeset + full --fail-on truth table per the #428 practice), no io-budget effect, en+ja docs, core minor.

Doc-only change — no changeset.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@oekazuma, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 19 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e1d63869-a372-4447-a1c5-9b019ead8d90

📥 Commits

Reviewing files that changed from the base of the PR and between 7561d74 and d95d27c.

📒 Files selected for processing (1)

• docs/superpowers/specs/2026-08-09-jsonld-vocabulary-catalog-design.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}