fix: define FormatId as proper object type per ADCP spec

Problem: FormatId was incorrectly defined as a string type alias,
but the ADCP spec requires it to be a structured object with
agent_url and id fields.

Root Cause: The format-id.json schema was missing from the downloaded
schemas, causing the type generator to create a placeholder string type.

Solution:
- Downloaded format-id.json schema from adcontextprotocol.org
- Defined FormatId as proper Pydantic model with agent_url and id fields
- Updated tests to use correct FormatId structure: {agent_url, id}

This ensures all format references use the structured format ID objects
as required by the ADCP specification, enabling proper format resolution
across different creative agents.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: bokelley

schemas/cache/1.0.0/format-id.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "/schemas/v1/core/format-id.json",
+  "title": "Format ID",
+  "description": "Structured format identifier with agent URL and format name",
+  "type": "object",
+  "properties": {
+    "agent_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_-]+$",
+      "description": "Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')"
+    }
+  },
+  "required": ["agent_url", "id"],
+  "additionalProperties": false
+}

src/adcp/types/generated.py

@@ -22,12 +22,31 @@
 
 # These types are referenced in schemas but don't have schema files
 # Defining them as type aliases to maintain type safety
-FormatId = str
 PackageRequest = dict[str, Any]
 PushNotificationConfig = dict[str, Any]
 ReportingCapabilities = dict[str, Any]
 
 
+# ============================================================================
+# FORMAT ID TYPE (manually defined from spec)
+# ============================================================================
+
+class FormatId(BaseModel):
+    """
+    Structured format identifier with agent URL and format name.
+
+    Based on https://adcontextprotocol.org/schemas/v1/core/format-id.json
+    """
+
+    agent_url: str = Field(
+        description="URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)"
+    )
+    id: str = Field(
+        pattern="^[a-zA-Z0-9_-]+$",
+        description="Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')"
+    )
+
+
 # ============================================================================
 # CORE DOMAIN TYPES
 # ============================================================================

tests/test_client.py

@@ -257,12 +257,18 @@ async def test_list_creative_formats_parses_mcp_response():
     formats_data = {
         "formats": [
             {
-                "format_id": "https://creative.example.com#banner_300x250",
+                "format_id": {
+                    "agent_url": "https://creative.example.com",
+                    "id": "banner_300x250"
+                },
                 "name": "Medium Rectangle",
                 "type": "display",
             },
             {
-                "format_id": "https://creative.example.com#video_16x9",
+                "format_id": {
+                    "agent_url": "https://creative.example.com",
+                    "id": "video_16x9"
+                },
                 "name": "Video 16:9",
                 "type": "video",
             },
@@ -306,7 +312,10 @@ async def test_list_creative_formats_parses_a2a_response():
     formats_data = {
         "formats": [
             {
-                "format_id": "https://creative.example.com#native_feed",
+                "format_id": {
+                    "agent_url": "https://creative.example.com",
+                    "id": "native_feed"
+                },
                 "name": "Native Feed Ad",
                 "type": "native",
             }