Schema Reference
Auto-generated reference for all ASP schema types.
| Field |
Type |
Required |
Description |
version |
string |
Yes |
Protocol version in YYYY-MM-DD format. |
services |
object |
Yes |
Map of service name to service definition. |
capabilities |
array\<capability> |
Yes |
Array of capability declarations. |
Capability Declaration
| Field |
Type |
Required |
Description |
name |
string |
Yes |
Reverse-domain identifier, e.g. dev.asp.services.discovery. |
version |
string |
Yes |
Capability version in YYYY-MM-DD format. |
spec |
string |
No |
Link to the human-readable spec page. |
schema |
string |
No |
Link to the JSON schema. |
extends |
string |
No |
Name of the capability this extends. Only set for extensions. |
Shared Types
Money
| Field |
Type |
Required |
Description |
amount |
integer |
Yes |
Value in smallest currency unit (e.g. 1299 = $12.99). |
currency |
string |
Yes |
ISO 4217 currency code. Default: USD |
Postal Address
| Field |
Type |
Required |
Description |
street_line_1 |
string |
Yes |
Primary street address. |
street_line_2 |
string |
No |
Secondary address line (apt, suite, unit). |
city |
string |
Yes |
City name. |
state |
string |
No |
State or province. |
postal_code |
string |
Yes |
Postal or ZIP code. |
country_code |
string |
Yes |
ISO 3166-1 alpha-2 country code. |
latitude |
number |
No |
Latitude for proximity-based operations. |
longitude |
number |
No |
Longitude for proximity-based operations. |
Image
| Field |
Type |
Required |
Description |
url |
string |
Yes |
URL of the image. |
alt_text |
string |
No |
Accessible alt text for the image. |
width |
integer |
No |
Image width in pixels. |
height |
integer |
No |
Image height in pixels. |
type |
string |
No |
Purpose of this image. Helps clients pick the right asset for context (e.g. thumbnail for search results, banner for detail page). Values: thumbnail, banner, logo, hero |
| Field |
Type |
Required |
Description |
page |
integer |
No |
Page number to retrieve. Default: 1 |
page_size |
integer |
No |
Number of items per page. Default: 20 |
total_items |
integer |
No |
Total number of items across all pages. |
total_pages |
integer |
No |
Total number of pages. |
Discovery Types
Price Level
Enum values: budget, moderate, premium, luxury
Service Category
No properties defined.
Provider Filter
| Field |
Type |
Required |
Description |
location |
[postal_address] |
Yes |
Location to search around. |
category |
[service_category] |
No |
Filter by service category. |
is_open_now |
boolean |
No |
Only return providers currently open. |
min_rating |
number |
No |
Minimum provider rating. |
max_service_minutes |
integer |
No |
Maximum acceptable service time in minutes. |
price_level |
[price_level] |
No |
Filter by price tier. |
minimum_order_cents |
integer |
No |
Minimum order amount in cents. |
query |
string |
No |
Free-text search query. |
is_promoted |
boolean |
No |
Whether the provider is currently being promoted. |
Provider
| Field |
Type |
Required |
Description |
id |
string |
Yes |
Unique provider identifier. |
name |
string |
Yes |
Display name of the provider. |
category |
[service_category] |
Yes |
Primary service category classification. |
rating |
number |
Yes |
Average provider rating. |
rating_count |
integer |
No |
Number of ratings/reviews. Gives agents confidence to recommend: '4.8 stars from 2,300 reviews'. |
estimated_service_minutes |
integer |
Yes |
Estimated service time in minutes. |
service_fee_cents |
integer |
Yes |
Service fee in cents. |
minimum_order_cents |
integer |
Yes |
Minimum order amount in cents. |
price_level |
[price_level] |
Yes |
Price tier classification. |
is_open_now |
boolean |
Yes |
Whether the provider is currently accepting orders. |
image |
[image] |
Yes |
Provider logo or hero image. |
address |
[postal_address] |
Yes |
Physical location of the provider. |
is_promoted |
boolean |
Yes |
Whether the provider is currently being promoted. |
tags |
array\<string> |
Yes |
Free-form tags relevant to this provider, e.g. 'fast food', 'gourmet', 'date night', 'romantic'. |
operating_hours |
array\<operating_hours_entry> |
No |
Weekly operating schedule. Omit if provider is always available or schedule is unknown. |
next_opens_at |
string |
No |
ISO 8601 datetime when a currently closed provider next opens. Allows agents to say 'opens at 11am tomorrow' without parsing the full schedule. |
images |
array\<image> |
No |
Multiple images for different contexts (thumbnail for search, banner for detail page, etc.). |
Operating Hours Entry
| Field |
Type |
Required |
Description |
day |
string |
Yes |
Day of the week. Values: monday, tuesday, wednesday, thursday, friday, saturday, sunday |
open_time |
string |
Yes |
Opening time in HH:MM (24-hour local time). |
close_time |
string |
Yes |
Closing time in HH:MM (24-hour local time). Use '23:59' for midnight close. |
Catalog Types
Service Catalog
| Field |
Type |
Required |
Description |
provider_id |
string |
Yes |
Identifier of the provider this catalog belongs to. |
provider_name |
string |
No |
Display name of the provider. |
sections |
array\<catalog_section> |
Yes |
Catalog sections containing items. |
last_updated |
string |
No |
Timestamp of the last catalog update. |
Catalog Section
| Field |
Type |
Required |
Description |
id |
string |
Yes |
Unique section identifier. |
title |
string |
Yes |
Display title for this section. |
description |
string |
No |
Optional section description. |
items |
array\<catalog_item> |
Yes |
Items in this section. |
is_featured |
boolean |
Yes |
Whether this section is currently featured. |
Catalog Item
| Field |
Type |
Required |
Description |
id |
string |
Yes |
Unique item identifier. |
title |
string |
Yes |
Display name of the item. |
description |
string |
Yes |
Item description. |
price_cents |
integer |
Yes |
Base price in cents. |
image |
[image] |
Yes |
Item image. |
modifier_groups |
array\<modifier_group> |
No |
Available customization groups for this item. |
is_available |
boolean |
Yes |
Whether this item is currently available for ordering. Default: True |
is_featured |
boolean |
Yes |
Whether this item is currently featured. |
tags |
array\<string> |
No |
Free-form tags relevant to this item, e.g. 'fast food', 'gourmet', 'date night', 'romantic'. |
images |
array\<image> |
No |
Multiple images for different contexts (thumbnail for list view, hero for detail page, etc.). |
Modifier Group
| Field |
Type |
Required |
Description |
id |
string |
Yes |
Unique group identifier. |
title |
string |
Yes |
Display title for this modifier group. |
required |
boolean |
No |
Whether the user must select an option from this group. Default: False |
min_selections |
integer |
No |
Minimum number of options the user must select. Default: 0 |
max_selections |
integer |
No |
Maximum number of options the user may select. Default: 1 |
options |
array\<modifier_option> |
Yes |
Available options in this group. |
Modifier Option
| Field |
Type |
Required |
Description |
id |
string |
Yes |
Unique option identifier. |
label |
string |
Yes |
Display label for this option. |
price_delta_cents |
integer |
No |
Price adjustment in cents when this option is selected. Default: 0 |
Fulfillment Types
Fulfillment
| Field |
Type |
Required |
Description |
type |
string |
Yes |
Fulfillment type identifier. Values: delivery, pickup, ride, booking, on_site |
estimated_service_minutes |
integer |
No |
Estimated service time in minutes from order confirmation. |
service_fee_cents |
integer |
No |
Service fee in cents. |
address |
[postal_address] |
Yes |
Address for the fulfillment (delivery destination, pickup location, etc.). |
instructions |
string |
No |
Special fulfillment instructions (e.g. 'Leave at door', 'Meet at lobby'). |
is_asap |
boolean |
Yes |
Whether to fulfill as soon as possible vs. a scheduled time. Default: True |
fees |
array\<fee> |
No |
Itemized fees beyond the base price. Lets agents explain cost breakdowns: 'Delivery fee $5, service fee $3.' |
tip |
[tip] |
No |
Optional gratuity for the service provider or driver. |
scheduled_for |
string |
No |
Requested service time as ISO 8601 datetime. Used when is_asap is false, e.g. 'Deliver at 7pm tonight'. |
available_time_slots |
array\<object> |
No |
Time slots the provider offers. Agent presents these as choices: 'They have slots at 6pm, 6:30pm, or 7pm.' |
Fee
| Field |
Type |
Required |
Description |
type |
string |
Yes |
Fee category. Base types cover common cross-vertical fees; domain profiles may define additional types. Values: delivery, service, small_order, platform, surge, booking, bag |
label |
string |
Yes |
Human-readable display name, e.g. 'Delivery fee', 'Bag charge', 'Surge pricing'. |
amount_cents |
integer |
Yes |
Fee amount in minor currency units (cents). |
Tip
| Field |
Type |
Required |
Description |
type |
string |
Yes |
How the tip is calculated. Values: percentage, fixed |
percentage |
number |
No |
Tip as a percentage of the order total. Present when type is 'percentage'. |
amount_cents |
integer |
Yes |
Resolved tip amount in minor currency units (cents). |
Item Customization
| Field |
Type |
Required |
Description |
special_instructions |
string |
No |
Free-text instructions for this item. |
modifiers |
array\<string> |
No |
Selected modifier option IDs from the item's modifier groups. |
Loyalty Discount
| Field |
Type |
Required |
Description |
loyalty_tier |
string |
No |
User's loyalty tier as defined by the marketplace, e.g. 'gold', 'premium', 'VIP', 'level_3'. |
loyalty_discount_percent |
number |
No |
Discount percentage applied based on loyalty tier. |
Order Tracking Types
Fulfillment Status
| Field |
Type |
Required |
Description |
order_id |
string |
Yes |
Identifier of the order being tracked. |
status |
string |
Yes |
Current order status. Values: accepted, in_progress, en_route, completed, cancelled |
estimated_service_minutes |
integer |
No |
Updated estimated service time in minutes. |
updated_at |
string |
Yes |
Timestamp of the last status update. |
agent_location |
object |
No |
Real-time agent location for live tracking. |
history |
array\<object> |
No |
Ordered timeline of status transitions. Enables agents to narrate the full journey: 'Accepted at 7:01, picked up at 7:15.' |
is_delayed |
boolean |
No |
Whether the order is running behind the original estimate. Allows agents to proactively warn: 'Heads up, your order is running late.' |
delay_minutes |
integer |
No |
How many minutes behind the original estimate. e.g. 'Running about 10 minutes late.' |
Status Update Event
| Field |
Type |
Required |
Description |
event_type |
string |
Yes |
Event type identifier. |
order_id |
string |
Yes |
Identifier of the order whose status changed. |
status |
[fulfillment_status] |
Yes |
The updated fulfillment status. |
timestamp |
string |
No |
When the event was emitted. |
Reviews Types
Review
| Field |
Type |
Required |
Description |
id |
string |
Yes |
Unique review identifier. |
order_id |
string |
Yes |
The order this review is for. |
provider_id |
string |
Yes |
The provider being reviewed. |
rating |
number |
Yes |
Overall rating out of 5. |
comment |
string |
No |
Optional free-text review. |
scores |
object |
No |
Optional category scores, e.g. {"food": 5, "delivery": 3} or {"cleanliness": 4, "location": 5}. |
created_at |
string |
Yes |
When the review was submitted. |
Streaming Types
Tracking Stream Event
| Field |
Type |
Required |
Description |
event_type |
string |
Yes |
Discriminator for routing the message to the correct handler. Values: location_update, status_changed, heartbeat |
order_id |
string |
No |
Identifier of the order being tracked. Present on all events except heartbeat. |
timestamp |
string |
Yes |
Server timestamp when the event was emitted. |
Personalization Types
User Profile
| Field |
Type |
Required |
Description |
name |
string |
Yes |
User's display name. |
loyalty_tier |
string |
No |
Current loyalty program tier as defined by the marketplace, e.g. 'gold', 'premium', 'VIP', 'level_3'. |
loyalty_points |
integer |
No |
Accumulated loyalty points. |
preferred_categories |
array\<service_category> |
No |
User's preferred service categories for personalized recommendations. |
order_history |
array\<order_history_entry> |
No |
Recent order history for reorder suggestions and personalization. |
default_address |
[postal_address] |
No |
User's saved default address. |
Order History Entry
| Field |
Type |
Required |
Description |
order_id |
string |
Yes |
Unique order identifier. |
provider_id |
string |
Yes |
Identifier of the provider. |
provider_name |
string |
No |
Display name of the provider. |
items |
array\<object> |
No |
Items ordered. |
ordered_at |
string |
Yes |
Timestamp when the order was placed. |
total_cents |
integer |
No |
Total order amount in cents. |
| Field |
Type |
Required |
Description |
id |
string |
Yes |
Unique promotion identifier. |
title |
string |
Yes |
Display title for the promotion. |
description |
string |
No |
Detailed promotion description. |
type |
[promotion_type] |
Yes |
Classification of this promotion. |
discount_percent |
number |
No |
Discount percentage if applicable. |
applicable_provider_id |
string |
No |
Provider this promotion applies to, if scoped. |
valid_until |
string |
No |
Expiration timestamp. |
minimum_order_cents |
integer |
No |
Minimum order value to qualify, in cents. |
Enum values: discount, reorder, category, loyalty