Background
Surfaced during expert review of #679 (PR #679 fixes #677 — see #679).
The v2.5 brand_manifest field is documented as a URL to a JSON manifest, and the spec's own example points at a non-/.well-known/brand.json path:
https://cdn.acmecorp.com/brand-manifest.json
(from schemas/cache/2.5/core/brand-manifest-ref.json:29)
After #679, the v2.5→v3 adapter correctly extracts the hostname so the result satisfies v3's BrandReference.domain hostname regex. But v3's BrandReference schema is hostname-only (additionalProperties: false at schemas/cache/3.0/core/brand-ref.json), so v3 sellers derive the canonical manifest URL as https://{domain}/.well-known/brand.json.
Impact
A v2.5 buyer hosting their manifest at a CDN or custom path (e.g. https://cdn.acmecorp.com/brand-manifest.json) gets translated to {domain: \"cdn.acmecorp.com\"}, and the v3 seller will try to fetch https://cdn.acmecorp.com/.well-known/brand.json — which will typically 404.
The adapter cannot do better given the v3 schema constraint (no field to preserve the original URL), but the silent flattening leaves both the buyer and the seller debugging a 404 with no signal in the SDK.
Suggested mitigation
Emit a log warning at adapter-call time when the input URL's path is neither empty nor /.well-known/brand.json. Something like:
brand_manifest at <url> uses a non-standard path; v3 sellers derive {domain}/.well-known/brand.json from BrandReference.domain. Manifest fetch may 404.
Doesn't change behaviour, but surfaces the mapping loss to operators.
Out of scope here
Adding a v3 BrandReference.manifest_url field to preserve the original URL — that's a v3 spec change and belongs in the adcontextprotocol/adcontextprotocol repo, not here.
Background
Surfaced during expert review of #679 (PR #679 fixes #677 — see #679).
The v2.5
brand_manifestfield is documented as a URL to a JSON manifest, and the spec's own example points at a non-/.well-known/brand.jsonpath:(from
schemas/cache/2.5/core/brand-manifest-ref.json:29)After #679, the v2.5→v3 adapter correctly extracts the hostname so the result satisfies v3's
BrandReference.domainhostname regex. But v3'sBrandReferenceschema is hostname-only (additionalProperties: falseatschemas/cache/3.0/core/brand-ref.json), so v3 sellers derive the canonical manifest URL ashttps://{domain}/.well-known/brand.json.Impact
A v2.5 buyer hosting their manifest at a CDN or custom path (e.g.
https://cdn.acmecorp.com/brand-manifest.json) gets translated to{domain: \"cdn.acmecorp.com\"}, and the v3 seller will try to fetchhttps://cdn.acmecorp.com/.well-known/brand.json— which will typically 404.The adapter cannot do better given the v3 schema constraint (no field to preserve the original URL), but the silent flattening leaves both the buyer and the seller debugging a 404 with no signal in the SDK.
Suggested mitigation
Emit a log warning at adapter-call time when the input URL's path is neither empty nor
/.well-known/brand.json. Something like:Doesn't change behaviour, but surfaces the mapping loss to operators.
Out of scope here
Adding a v3
BrandReference.manifest_urlfield to preserve the original URL — that's a v3 spec change and belongs in theadcontextprotocol/adcontextprotocolrepo, not here.