Skip to content

docs(schema): replace reference.adcp.org placeholder with RFC 2606 .example domain#4655

Merged
bokelley merged 1 commit into
mainfrom
claude/issue-4652-example-domain-cleanup
May 22, 2026
Merged

docs(schema): replace reference.adcp.org placeholder with RFC 2606 .example domain#4655
bokelley merged 1 commit into
mainfrom
claude/issue-4652-example-domain-cleanup

Conversation

@bokelley
Copy link
Copy Markdown
Contributor

Closes #4652

The creative_agents[].agent_url description string in both list-creative-formats-response.json schemas (creative and media-buy variants) used reference.adcp.org as an example URL. adcp.org is not the organization's domain (adcontextprotocol.org is), and .adcp reads as a fictional or unknown TLD — exactly the confusion the issue describes. Several reviewers on #3307 asked whether meta.adcp, nytimes.adcp, etc. were real domains. This fixes the last two source/ schema files with the pattern.

Files changed: 2 source schema files only. dist/schemas/** are immutable released snapshots; they will be regenerated from source on the next schema build.

Non-breaking justification: Both changes are to description string fields — non-normative prose in JSON Schema. No wire format, enum value, type constraint, or required field is touched. Existing producers and consumers are unaffected.

Scope note: The issue listed 7 files. Only 2 had actual reference.adcp.org domain patterns on main. The other 5 contain field names (adcp_error, adcp_task_id) and property access (result.adcp.major_versions) — not domain-style .adcp placeholders — so no changes were needed there.

Pre-PR review:

  • code-reviewer: approved — non-breaking description-field edit; --empty changeset correct; dist/ stale-on-merge is expected and handled by release pipeline
  • docs-expert: approved — clean, minimal, correct fix; .example.com is the right RFC 2606 form; no information lost in the shortened string

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout <num>
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See #3121
for context.

Session: https://claude.ai/code/session_01N6Z46r5L7JxToG8u8w8VKk


Generated by Claude Code

…xample domain

Fixes #4652. The creative_agents[].agent_url description string in both
list-creative-formats-response.json schemas used reference.adcp.org as
an example URL. adcp.org is not the org's domain (adcontextprotocol.org
is), and .adcp reads like a fictional TLD. Replaced with
reference.example.com — now both examples in the string use the RFC 2606
reserved .example domain consistently. Also removed a redundant trailing
sentence that repeated information already in the parent array description.

https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}
@bokelley bokelley added the claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage. label May 17, 2026
@bokelley bokelley marked this pull request as ready for review May 22, 2026 18:05
Copy link
Copy Markdown
Contributor

@aao-release-bot aao-release-bot Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. description is non-normative JSON Schema metadata — zero wire impact, no field/type/enum/required touched. Right shape for a no-bump changeset.

Things I checked

  • Both source files diff to a single description string each. Confirmed no type, required, enum, additionalProperties, or $ref changes at static/schemas/source/creative/list-creative-formats-response.json:29 and static/schemas/source/media-buy/list-creative-formats-response.json:29.
  • .changeset/4652-example-domain-cleanup.md has empty ---\n--- frontmatter (no version bump). Matches prior art (.changeset/3573-agent-url-canonicalization-cleanup.md) and docs/reference/versioning.mdx:192, which scopes patch to wording/validation that "never change schema." Even patch is arguably more than this deserves.
  • reference.example.com is RFC 2606-reserved — the right placeholder. No remaining reference.adcp.org in static/ or docs/ source. The string survives only in the changeset body, which is correct since it names the value being removed.
  • dist/schemas/** untouched. Released bundles are immutable per the tarball-verification doc; the fix lands in the next bundle.
  • No docs page references reference.adcp.org — no cross-file drift to chase.

Follow-ups (non-blocking — file as issues)

  • The dropped sentence is the one load-bearing thing in this diff. "Call list_creative_formats on this URL to get its formats." was the only place the per-field description told a reader what verb to send at agent_url. The parent creative_agents description on the line above carries the recursive-discovery semantic ("recursively query… No authentication required for list_creative_formats"), so the information isn't lost at the schema level — but SDK consumers who only see the per-field description in generated typings lose the inline cue. Worth a one-line follow-up restoring a compact form, e.g. "Base URL for the creative agent (e.g., 'https://reference.example.com'). Call list_creative_formats on this URL to discover its formats." Keeps the cleanup, keeps the hint.
  • PR body line "no information lost in the shortened string" is strictly wrong in the text-diff sense — the sentence is gone. The accurate framing is "redundant with the parent creative_agents description; deduplicated, not lost." Notable mostly because the pre-PR review summary quoted that phrase as evidence. Worth tightening in future triage-bot bodies.

Subagent verdicts: code-reviewer approve; ad-tech-protocol-expert sound-with-caveats (caveat is the same dropped-sentence point, non-blocking).

Approving.

@bokelley bokelley merged commit 40e4e17 into main May 22, 2026
14 checks passed
@bokelley bokelley deleted the claude/issue-4652-example-domain-cleanup branch May 22, 2026 18:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Spec hygiene: replace .adcp placeholder domains with RFC 2606 .example

2 participants