docs(schema): replace reference.adcp.org placeholder with RFC 2606 .example domain#4655
Merged
Merged
Conversation
…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}
Contributor
There was a problem hiding this comment.
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
descriptionstring each. Confirmed notype,required,enum,additionalProperties, or$refchanges atstatic/schemas/source/creative/list-creative-formats-response.json:29andstatic/schemas/source/media-buy/list-creative-formats-response.json:29. .changeset/4652-example-domain-cleanup.mdhas empty---\n---frontmatter (no version bump). Matches prior art (.changeset/3573-agent-url-canonicalization-cleanup.md) anddocs/reference/versioning.mdx:192, which scopes patch to wording/validation that "never change schema." Even patch is arguably more than this deserves.reference.example.comis RFC 2606-reserved — the right placeholder. No remainingreference.adcp.orginstatic/ordocs/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 parentcreative_agentsdescription 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_agentsdescription; 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #4652
The
creative_agents[].agent_urldescription string in bothlist-creative-formats-response.jsonschemas (creative and media-buy variants) usedreference.adcp.orgas an example URL.adcp.orgis not the organization's domain (adcontextprotocol.orgis), and.adcpreads as a fictional or unknown TLD — exactly the confusion the issue describes. Several reviewers on #3307 asked whethermeta.adcp,nytimes.adcp, etc. were real domains. This fixes the last twosource/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
descriptionstring 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.orgdomain patterns onmain. The other 5 contain field names (adcp_error,adcp_task_id) and property access (result.adcp.major_versions) — not domain-style.adcpplaceholders — so no changes were needed there.Pre-PR review:
--emptychangeset correct;dist/stale-on-merge is expected and handled by release pipeline.example.comis the right RFC 2606 form; no information lost in the shortened stringSession: https://claude.ai/code/session_01N6Z46r5L7JxToG8u8w8VKk
Generated by Claude Code