Skip to content

Commit d81a719

Browse files
GouniManikumar12GouniManikumar12
committed
Revise ad auction schemas and examples for new data model
Major update to ad auction, bid, event, and ledger schemas and example payloads. Changes include: renaming and restructuring fields for clarity (e.g., agent_id → brand_agent_id, ts → timestamp), expanded creative and pricing structures, new wallet-record schema, and improved normalization of context and event data. Test fixtures and documentation updated to match the new schema versions.
1 parent f68d96f commit d81a719

18 files changed

Lines changed: 621 additions & 608 deletions

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ Each schema defines an optional `ext` container that may include any number of v
7272
- **`platform-request`** – Payload AI platforms send to operators when a user expresses commercial intent. It captures raw query text, locale/geo, optional conversation history, transport auth, and any vendor extensions under `ext`.
7373
- **`context-request`** – Payload operators send to subscribed brand agents after classifying the opportunity. Operators may derive or redact fields from the originating `platform-request` before fanout.
7474

75-
This split keeps the platform/operator contract stable while allowing operators to enrich or anonymize data before reaching bidders.
75+
Key fields include `context_id`, `intent` (type/decision phase/context summary), `allowed_formats`, and the operator-signed `auth` block. This split keeps the platform/operator contract stable while allowing operators to enrich or anonymize data before reaching bidders.
7676

7777
---
7878

‎examples/auction-result.example.json‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,21 @@
22
"auction_id": "auc_981",
33
"serve_token": "stk_abcxyz123",
44
"winner": {
5-
"agent_id": "ag_123",
6-
"clearing_price_cpx": "0.042",
7-
"preferred_unit": "CPA"
5+
"brand_agent_id": "brand_agent_123",
6+
"campaign_id": "cmp_nimbus_launch",
7+
"product_id": "prod_nimbus_crm",
8+
"cpx_price": "5",
9+
"cpc_price": "145",
10+
"cpa_price": null,
11+
"billable_unit": "CPC"
812
},
913
"render": {
1014
"label": "[Ad]",
11-
"title": "Pipedrive CRM",
12-
"body": "Built for founders.",
15+
"title": "Nimbus CRM Pro",
16+
"body": "AI-native CRM for 5-50 person teams.",
1317
"cta": "Try for free",
14-
"url": "https://admesh.click/stk_abcxyz123"
18+
"url": "https://admesh.click/stk_abcxyz123",
19+
"image": "https://cdn.example.com/nimbus/crm.png"
1520
},
1621
"ttl_ms": 60000
17-
}
22+
}

‎examples/bid.example.json‎

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,27 @@
11
{
2-
"bid_id": "b_7823",
3-
"agent_id": "ag_123",
2+
"bid_id": "bid_7823",
3+
"brand_agent_id": "brand_agent_123",
44
"context_id": "ctx_92f",
5-
"wallet_id": "w_890",
6-
"bid_vector": {
5+
"wallet_id": "wallet_890",
6+
"pricing": {
77
"cpx": "0.05",
88
"cpc": "0.45",
9-
"cpa": "10.00"
9+
"cpa": "10.00",
10+
"currency": "USD"
1011
},
11-
"preferred_unit": "CPA",
12-
"creative": {
13-
"title": "Pipedrive CRM",
14-
"body": "CRM built for growing teams.",
15-
"cta": "Start free trial",
16-
"deeplink": "https://pipedrive.com/signup"
12+
"offer": {
13+
"creative_input": {
14+
"brand_name": "Nimbus",
15+
"product_name": "Nimbus CRM Pro",
16+
"descriptions": ["AI-native CRM for 5-50 person teams."],
17+
"value_props": ["Automated pipeline insights", "Embedded copilots"],
18+
"resource_urls": ["https://nimbus.example/signup"],
19+
"image_urls": ["https://cdn.example.com/nimbus/crm.png"]
20+
}
1721
},
18-
"ts": "2025-11-11T18:00:01Z",
22+
"timestamp": "2025-11-11T18:00:01Z",
1923
"auth": {
20-
"nonce": "n_456",
21-
"sig": "sig_789"
24+
"nonce": "nonce_456",
25+
"signature": "sig_789"
2226
}
23-
}
27+
}

‎examples/context-request.example.json‎

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,22 @@
11
{
2-
"request_id": "rq_92f",
3-
"session_id": "s_001",
4-
"platform_id": "pf_chatapp",
2+
"context_id": "ctx_92fA1",
3+
"session_id": "sess_001",
4+
"operator_id": "admesh_operator",
5+
"platform_id": "openai_chat",
56
"query_text": "best CRM for small teams",
6-
"surface": "chat",
77
"locale": "en-US",
88
"geo": "US",
9-
"pricing": {
10-
"cpx_floor": "0.03"
9+
"verticals": ["crm", "smb_software"],
10+
"intent": {
11+
"type": "commercial",
12+
"decision_phase": "compare",
13+
"context_summary": "User is evaluating CRM tools and narrowing down options.",
14+
"turn_index": 3
1115
},
12-
"features": {
13-
"topic": [
14-
"crm",
15-
"smb"
16-
],
17-
"user_type": "human"
18-
},
19-
"ts": "2025-11-11T18:00:00Z",
20-
"auth": {
21-
"nonce": "n_123",
22-
"sig": "sig_abcd"
16+
"allowed_formats": ["weave", "citation", "product_card"],
17+
"timestamp": "2025-11-14T18:22:00Z",
18+
"auth": { "nonce": "nonce_123", "sig": "sig_hmac_123abc" },
19+
"extensions": {
20+
"admesh": { "operator_relevance_score": 0.87 }
2321
}
24-
}
22+
}

‎examples/event-cpc-click.example.json‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
11
{
22
"event_type": "cpc_click",
33
"serve_token": "stk_abcxyz123",
4-
"event_id": "ev_991",
5-
"s2s": true,
4+
"session_id": "sess_001",
5+
"platform_id": "pf_openai_chat",
6+
"brand_agent_id": "ba_451",
7+
"wallet_id": "w_0021",
8+
"pricing": {
9+
"unit": "CPC",
10+
"amount_cents": 45
11+
},
612
"click_metadata": {
7-
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
8-
"ip_address": "192.168.1.1",
9-
"referrer": "https://chatapp.example/session/s_001"
13+
"source": "deep_link",
14+
"position": 1
1015
},
11-
"ts": "2025-11-11T18:02:00Z"
12-
}
16+
"timestamp": "2025-11-14T18:00:02Z"
17+
}

‎schemas/auction-result.json‎

Lines changed: 20 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"$schema": "https://json-schema.org/draft/2020-12/schema",
33
"title": "AuctionResult",
4-
"description": "Result of an ad auction, returned to the platform with the winning creative",
4+
"description": "Winning bid and reservation details returned to the AI platform.",
55
"type": "object",
66
"required": [
77
"auction_id",
@@ -11,81 +11,55 @@
1111
"properties": {
1212
"auction_id": {
1313
"type": "string",
14-
"description": "Unique identifier for this auction",
1514
"example": "auc_981"
1615
},
1716
"no_bid": {
1817
"type": "boolean",
19-
"description": "Set to true when the auction window closes without any valid bids",
20-
"default": false
18+
"default": false,
19+
"description": "Whether this auction ended with no bids"
2120
},
2221
"serve_token": {
2322
"type": "string",
24-
"description": "Token used to track events for this ad serve",
2523
"example": "stk_abcxyz123"
2624
},
2725
"winner": {
2826
"type": "object",
29-
"description": "Information about the winning bid",
27+
"description": "Winning bid info",
3028
"properties": {
31-
"agent_id": {
29+
"brand_agent_id": {
3230
"type": "string",
33-
"description": "ID of the winning advertiser agent",
34-
"example": "ag_123"
35-
},
36-
"clearing_price_cpx": {
37-
"type": "string",
38-
"description": "Clearing price for CPX in USD",
39-
"pattern": "^\\d+\\.\\d{2,}$",
40-
"example": "0.042"
31+
"example": "ba_451"
4132
},
4233
"preferred_unit": {
4334
"type": "string",
44-
"description": "Charging model for this serve",
45-
"enum": [
46-
"CPX",
47-
"CPC",
48-
"CPA"
49-
],
35+
"enum": ["CPX", "CPC", "CPA"],
5036
"example": "CPA"
37+
},
38+
"reserved_amount_cents": {
39+
"type": "integer",
40+
"minimum": 0,
41+
"description": "Amount held at auction time",
42+
"example": 500
5143
}
5244
}
5345
},
5446
"render": {
5547
"type": "object",
56-
"description": "Creative content to display to the user",
48+
"description": "Creative payload",
5749
"properties": {
58-
"label": {
59-
"type": "string",
60-
"description": "Disclosure label (always '[Ad]')",
61-
"example": "[Ad]"
62-
},
63-
"title": {
64-
"type": "string",
65-
"description": "Ad title",
66-
"example": "Pipedrive CRM"
67-
},
68-
"body": {
69-
"type": "string",
70-
"description": "Ad body text",
71-
"example": "Built for founders."
72-
},
73-
"cta": {
74-
"type": "string",
75-
"description": "Call-to-action text",
76-
"example": "Try for free"
77-
},
50+
"label": { "type": "string", "example": "[Ad]" },
51+
"title": { "type": "string", "example": "Scale your CRM" },
52+
"body": { "type": "string", "example": "Built for founders." },
53+
"cta": { "type": "string", "example": "Try for free" },
7854
"url": {
7955
"type": "string",
80-
"description": "Click-through URL with tracking",
8156
"format": "uri",
8257
"example": "https://admesh.click/stk_abcxyz123"
8358
}
8459
}
8560
},
8661
"ttl_ms": {
8762
"type": "integer",
88-
"description": "Time-to-live in milliseconds for this auction result",
8963
"minimum": 1000,
9064
"maximum": 300000,
9165
"example": 60000
@@ -95,43 +69,13 @@
9569
}
9670
},
9771
"oneOf": [
98-
{
99-
"required": ["winner", "render"],
100-
"properties": {}
101-
},
72+
{ "required": ["winner", "render"] },
10273
{
10374
"required": ["no_bid"],
10475
"properties": {
105-
"no_bid": {
106-
"const": true
107-
}
76+
"no_bid": { "const": true }
10877
}
10978
}
11079
],
111-
"examples": [
112-
{
113-
"auction_id": "auc_981",
114-
"serve_token": "stk_abcxyz123",
115-
"winner": {
116-
"agent_id": "ag_123",
117-
"clearing_price_cpx": "0.042",
118-
"preferred_unit": "CPA"
119-
},
120-
"render": {
121-
"label": "[Ad]",
122-
"title": "Pipedrive CRM",
123-
"body": "Built for founders.",
124-
"cta": "Try for free",
125-
"url": "https://admesh.click/stk_abcxyz123"
126-
},
127-
"ttl_ms": 60000
128-
},
129-
{
130-
"auction_id": "auc_982",
131-
"serve_token": "stk_no_bid",
132-
"ttl_ms": 60000,
133-
"no_bid": true
134-
}
135-
],
13680
"$id": "https://aip.org/schemas/auction-result.json"
13781
}

0 commit comments

Comments
 (0)