feat(ci): add schema link checker for docs PRs by BaiyuScope3 · Pull Request #1209 · adcontextprotocol/adcp

BaiyuScope3 · 2026-02-26T18:29:26Z

Summary

Adds a GitHub Actions workflow that validates schema URLs in documentation
Fixes incorrect schema version links across documentation (v1/v2 → v3 or latest)
Updates unreleased schema links to use /schemas/latest/

Schema Link Checker

The new workflow (.github/workflows/check-schema-links.yml) addresses #1181 by:

Extracting schema URLs from docs (e.g., https://adcontextprotocol.org/schemas/v3/media-buy/sync-audiences-request.json)
Validating each URL:
- Checks if the schema exists in static/schemas/source/
- Checks if the schema exists in the corresponding versioned release (dist/schemas/X.Y.Z/)
- Suggests the correct version if schema exists elsewhere
Dynamically determining versions:
- vN → finds latest N.x.x release in dist/schemas/
- Calculates the next expected release (e.g., "3.0.0-beta.4")
Commenting on PRs with:
- ❌ Errors: Schema doesn't exist, or exists in a different version (fails the check)
- ⚠️ Warnings: Schema exists in source/latest but not yet released (does not fail)

v1 Schema Alias

The v1 alias continues to point to latest for backward compatibility. This means:

Existing v1 links will resolve to the latest development schemas
New schemas added to source are immediately accessible via v1

Schema Link Fixes

Fixed incorrect version links in documentation:

v1/v2 → v3 (schemas released in v3):

Content standards tasks (calibrate_content, create/get/list/update_content_standards, etc.)
Creative delivery (get_creative_delivery)
Conversion tracking (log_event, sync_event_sources, event-custom-data, user-match)
Pricing options (cpa-option, cpm-option, time-option, vcpm-option)
Property governance (base-property-source)
Protocol capabilities (get-adcp-capabilities-response)

v2/v3 → latest (schemas in source but not yet released):

get_media_buys request/response
sync_catalogs request/response
sync_audiences request/response
get_account_financials request/response
report_usage request/response
Catalog item schemas (app-item, hotel-item, vehicle-item, etc.)
Creative brief, offering asset schemas

Test plan

Verify the workflow triggers on this PR
Check that the workflow comments with warnings about unreleased schemas
Verify schema link checker runs on future doc PRs
Verify v1 links continue to resolve to latest

Closes #1181

Adds a GitHub Actions workflow that validates schema URLs in documentation: - Checks if referenced schemas exist in static/schemas/source/ - Warns when schemas exist in source but haven't been released yet - Dynamically determines the next release version (works for any vN) - Comments on PRs with broken links and guidance on how to fix them Also updates sync_audiences schema links from v1 to v3. The v3 links will work once 3.0.0-beta.4 is released (sync_audiences was added after beta.3). Closes #1181 Made-with: Cursor

Made-with: Cursor

- Create dist/schemas/1.0.0/ with 48 schemas unique to v1 - Update v1 symlink to point to 1.0.0 instead of latest - Remove v1->latest special cases from build script, HTTP middleware, and CI - v1 now resolves like other major versions (v1 -> 1.0.0) Schemas in 1.0.0 include catalog items, creative briefs, audience members, and other schemas that were added after the v2.x and v3.x release lines. Made-with: Cursor

- brand.json: v1 → v3 (exists in v3 beta.2+) - core/offering.json: v1 → v3 (exists in v3 beta.1+) - core/targeting.json: v1 → v3 (exists in v2 and v3) - core/brand-ref.json: v2 → v3 (exists in v3 beta.2+) - core/event.json: v2 → v3 (exists in v3 beta.2+) - core/optimization-goal.json: v2 → v3 (exists in v3 beta.2+) - core/creative-brief.json: v2 → v1 (only exists in 1.0.0) Made-with: Cursor

Previously, the workflow only commented when issues were found. This left stale warning comments on PRs even after the issues were fixed. Now the workflow deletes the old comment when all schema links are valid. Made-with: Cursor

- Fix grep pattern to match URLs with hyphens (use [^"') ] instead of \s) - Show success message instead of deleting comment when all links pass - Add commit SHA and message to comment header for traceability Made-with: Cursor

github-actions · 2026-02-26T19:21:43Z

Schema Link Check Results

Commit: e5ce8cc - docs: add schema URL guidelines to CLAUDE.md

✅ All schema links checked - 88 URLs verified, all good!

GITHUB_SHA points to the merge commit, but we want to show the actual PR commit SHA that users can click to see the changes. Made-with: Cursor

The regex was capturing markdown link syntax like `](url` because backticks weren't excluded from the character class. Made-with: Cursor

When a schema URL uses v1 but the schema only exists in v3, the check now reports this as an error with a suggestion to use the correct version instead of just warning about unreleased schemas. Made-with: Cursor

The 1.0.0 release incorrectly included schemas that were created after 3.0.0-beta.3. These schemas should wait for the next v3 release instead. Changes: - Remove dist/schemas/1.0.0/ (all schemas were post-3.0.0-beta.3) - Remove scripts/create-v1-release.cjs (flawed logic) - Update CI to check latest before other versions - Prioritize warning for schemas in latest over suggesting other versions Made-with: Cursor

All documentation schema links now use v3 instead of v1. Some schemas are already released in 3.0.0-beta.3, others will be available in the next beta release. Updated files: - docs/protocol/get_adcp_capabilities.mdx - docs/accounts/tasks/get_account_financials.mdx - docs/accounts/tasks/sync_accounts.mdx - docs/creative/catalogs.mdx - docs/creative/task-reference/build_creative.mdx - docs/reference/migration/channels.mdx - docs/reference/migration/pricing.mdx - docs/reference/migration/geo-targeting.mdx - docs/reference/migration/creatives.mdx - docs/reference/media-channel-taxonomy.mdx - docs/reference/release-notes.mdx Made-with: Cursor

Changed from an error saying "build issue" to a warning with actionable guidance: change to latest or wait for the next release. Made-with: Cursor

In production, /schemas/latest/ serves from static/schemas/source/, not from dist/schemas/latest/. Updated CI to recognize that if a schema exists in source, it's available at the latest URL. Made-with: Cursor

These schemas were added after v2.5.3 and only exist in v3: - content-standards/* (all tasks) - core/event-custom-data, core/user-match - creative/get-creative-delivery-* - media-buy/log-event-*, sync-event-sources-*, get-media-buys-* - pricing-options/* (cpa, cpm, time, vcpm) - property/base-property-source - protocol/get-adcp-capabilities-response Made-with: Cursor

Additional files with v2 URLs that needed updating: - docs/media-buy/specification.mdx (log-event, sync-event-sources, get-adcp-capabilities-response) - docs/media-buy/product-discovery/media-products.mdx (cpm-option) - docs/governance/property/tasks/property_lists.mdx (base-property-source) - docs/governance/property/specification.mdx (base-property-source) - docs/signals/specification.mdx (get-adcp-capabilities-response) - docs/creative/specification.mdx (get-adcp-capabilities-response) Made-with: Cursor

For schemas not yet in any release, use /schemas/latest/ so links work immediately. These will be updated to versioned URLs after the next release. Updated files: - docs/media-buy/task-reference/get_media_buys.mdx - docs/media-buy/task-reference/sync_catalogs.mdx - docs/media-buy/task-reference/sync_audiences.mdx - docs/media-buy/specification.mdx - docs/accounts/tasks/get_account_financials.mdx - docs/accounts/tasks/report_usage.mdx - docs/creative/catalogs.mdx - docs/creative/task-reference/build_creative.mdx Made-with: Cursor

docs/creative/catalogs.mdx

Reverts changes that made v1 point to 1.0.0. v1 should continue to fall back to latest for backward compatibility. Made-with: Cursor

BaiyuScope3 · 2026-02-26T21:27:59Z

example on when the url link was not correct
1. Wrong url OR wrong version tag OR schema is really not exist

2. Schema exist but not released yet (latest)

3. All links are using correct schema version

- Document how to choose correct schema version in docs - Use /schemas/latest/ for unreleased schemas with reminder comment - Use version aliases (v2, v3) for released schemas - Reference CI workflow for validation Made-with: Cursor

CLAUDE.md

BaiyuScope3 · 2026-02-26T22:05:04Z

Schema Link Changes Summary

This PR fixes broken schema URLs across documentation. Here's a clickable summary of all changes:

❌ Previously Wrong → ✅ Now Fixed

v1 → v3 (schemas released in v3)

Old (misleading version link)	New (fixed)
/schemas/v1/account/sync-accounts-request.json	/schemas/v3/account/sync-accounts-request.json
/schemas/v1/account/sync-accounts-response.json	/schemas/v3/account/sync-accounts-response.json
/schemas/v1/protocol/get-adcp-capabilities-request.json	/schemas/v3/protocol/get-adcp-capabilities-request.json
/schemas/v1/protocol/get-adcp-capabilities-response.json	/schemas/v3/protocol/get-adcp-capabilities-response.json
/schemas/v1/core/offering.json	/schemas/v3/core/offering.json

v2 → v3 (schemas only in v3)

v1/v2/v3 → latest (unreleased schemas)

These schemas exist in source but haven't been released yet. Using /schemas/latest/ until next release:

Old (misleading version link)	New (latest)
/schemas/v1/account/get-account-financials-request.json	/schemas/latest/account/get-account-financials-request.json
/schemas/v1/account/get-account-financials-response.json	/schemas/latest/account/get-account-financials-response.json
/schemas/v3/account/report-usage-request.json	/schemas/latest/account/report-usage-request.json
/schemas/v3/account/report-usage-response.json	/schemas/latest/account/report-usage-response.json
/schemas/v2/media-buy/get-media-buys-request.json	/schemas/latest/media-buy/get-media-buys-request.json
/schemas/v2/media-buy/get-media-buys-response.json	/schemas/latest/media-buy/get-media-buys-response.json
/schemas/v1/media-buy/sync-audiences-request.json	/schemas/latest/media-buy/sync-audiences-request.json
/schemas/v1/media-buy/sync-audiences-response.json	/schemas/latest/media-buy/sync-audiences-response.json
/schemas/v2/media-buy/sync-catalogs-request.json	/schemas/latest/media-buy/sync-catalogs-request.json
/schemas/v2/media-buy/sync-catalogs-response.json	/schemas/latest/media-buy/sync-catalogs-response.json
/schemas/v1/core/catalog.json	/schemas/latest/core/catalog.json
/schemas/v1/core/catchment.json	/schemas/latest/core/catchment.json
/schemas/v1/core/app-item.json	/schemas/latest/core/app-item.json
/schemas/v1/core/destination-item.json	/schemas/latest/core/destination-item.json
/schemas/v1/core/education-item.json	/schemas/latest/core/education-item.json
/schemas/v1/core/flight-item.json	/schemas/latest/core/flight-item.json
/schemas/v1/core/hotel-item.json	/schemas/latest/core/hotel-item.json
/schemas/v1/core/job-item.json	/schemas/latest/core/job-item.json
/schemas/v1/core/real-estate-item.json	/schemas/latest/core/real-estate-item.json
/schemas/v1/core/store-item.json	/schemas/latest/core/store-item.json
/schemas/v1/core/vehicle-item.json	/schemas/latest/core/vehicle-item.json
/schemas/v2/core/creative-brief.json	/schemas/latest/core/creative-brief.json
/schemas/v1/core/offering-asset-group.json	/schemas/latest/core/offering-asset-group.json
/schemas/v1/core/requirements/offering-asset-constraint.json	/schemas/latest/core/requirements/offering-asset-constraint.json

Other Fixes

Old	New	Reason
/schemas/v2/core/creative-format.json	/schemas/v2/core/format.json	Wrong filename
/schemas/v1/brand.json	/schemas/v3/brand.json	Released in v3

Note: Schemas using /schemas/latest/ will be updated to versioned URLs after the next release (3.0.0-beta.4).

bokelley · 2026-02-26T23:03:45Z

@BaiyuScope3 to the comment about latest - confirming that latest remains the head/main branch, not versioned to last release

BaiyuScope3 · 2026-02-26T23:07:13Z

confirming that latest remains the head/main branch, not versioned to last release

Yess, this PR doesn’t change any version-link resolution logic. latest continues to track main (head).

So for now we can safely use /latest/ in the docs for schema links until the release is finalized. Once it’s released, we can switch to the versioned symlink paths like /v2/, /v3/, etc.

Note: right now /v1/ still resolves to /latest/ for backward compatibility. I’m not changing that to avoid breaking any downstream clients that sync schemas. But I updated the Claude instructions to use /latest/ (instead of /v1/) for new schemas to reduce confusion.

BaiyuScope3 added 9 commits February 26, 2026 13:27

fix(ci): use env var for comment to avoid template literal issues

25b5f8a

Made-with: Cursor

fix(docs): correct creative-format.json to format.json

9acbca6

Made-with: Cursor

fix(ci): fail schema link check on errors, allow warnings

489dd8d

Made-with: Cursor

fix(ci): handle v1 symlink correctly (points to latest, not 1.x)

aa5e13c

Made-with: Cursor

fix: improve schema link checker workflow

c7d133a

- Fix grep pattern to match URLs with hyphens (use [^"') ] instead of \s) - Show success message instead of deleting comment when all links pass - Add commit SHA and message to comment header for traceability Made-with: Cursor

BaiyuScope3 added 10 commits February 26, 2026 14:25

fix: use PR head commit SHA instead of merge commit in schema check

f11884d

GITHUB_SHA points to the merge commit, but we want to show the actual PR commit SHA that users can click to see the changes. Made-with: Cursor

fix: exclude backticks in schema URL regex to handle markdown links

e7fa452

The regex was capturing markdown link syntax like `](url` because backticks weren't excluded from the character class. Made-with: Cursor

fix: detect wrong version in schema URLs and suggest correct version

545727a

When a schema URL uses v1 but the schema only exists in v3, the check now reports this as an error with a suggestion to use the correct version instead of just warning about unreleased schemas. Made-with: Cursor

fix: improve CI message for schemas in source but not in latest

618d7a0

Changed from an error saying "build issue" to a warning with actionable guidance: change to latest or wait for the next release. Made-with: Cursor

fix: CI now treats source as latest for schema checks

cbc6603

In production, /schemas/latest/ serves from static/schemas/source/, not from dist/schemas/latest/. Updated CI to recognize that if a schema exists in source, it's available at the latest URL. Made-with: Cursor

BaiyuScope3 commented Feb 26, 2026

View reviewed changes

docs/creative/catalogs.mdx Show resolved Hide resolved

revert: restore v1 schema alias to point to latest

5a6908d

Reverts changes that made v1 point to 1.0.0. v1 should continue to fall back to latest for backward compatibility. Made-with: Cursor

BaiyuScope3 requested review from EmmaLouise2018 and bokelley February 26, 2026 21:30

docs: add schema URL guidelines to CLAUDE.md

e5ce8cc

- Document how to choose correct schema version in docs - Use /schemas/latest/ for unreleased schemas with reminder comment - Use version aliases (v2, v3) for released schemas - Reference CI workflow for validation Made-with: Cursor

BaiyuScope3 commented Feb 26, 2026

View reviewed changes

CLAUDE.md Show resolved Hide resolved

BaiyuScope3 merged commit d37237c into main Feb 27, 2026
8 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(ci): add schema link checker for docs PRs#1209

feat(ci): add schema link checker for docs PRs#1209
BaiyuScope3 merged 21 commits intomainfrom
fix/sync-audiences-schema-links-v3

BaiyuScope3 commented Feb 26, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

BaiyuScope3 commented Feb 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

BaiyuScope3 commented Feb 26, 2026 •

edited

Loading

Uh oh!

bokelley commented Feb 26, 2026

Uh oh!

BaiyuScope3 commented Feb 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

BaiyuScope3 commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Schema Link Checker

v1 Schema Alias

Schema Link Fixes

Test plan

Uh oh!

github-actions bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Schema Link Check Results

Uh oh!

Uh oh!

BaiyuScope3 commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

BaiyuScope3 commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Schema Link Changes Summary

❌ Previously Wrong → ✅ Now Fixed

v1 → v3 (schemas released in v3)

v2 → v3 (schemas only in v3)

v1/v2/v3 → latest (unreleased schemas)

Other Fixes

Uh oh!

bokelley commented Feb 26, 2026

Uh oh!

BaiyuScope3 commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BaiyuScope3 commented Feb 26, 2026 •

edited

Loading

github-actions bot commented Feb 26, 2026 •

edited

Loading

BaiyuScope3 commented Feb 26, 2026 •

edited

Loading

BaiyuScope3 commented Feb 26, 2026 •

edited

Loading

BaiyuScope3 commented Feb 26, 2026 •

edited

Loading