Overview
Schema reference for structuring products, services, offers, policies, locations, availability, and customer actions for AI systems.
- Required client identity.
- Optional location and offer details.
- Public/private field separation.
- Graph version metadata.
Required fields
A published Commerce Graph needs client identity, graph version, approved client profile, public sources, offers, policies, locations where relevant, and customer action paths. Unapproved or private fields must not appear in public output.
- merchant_id
- graph_version
- business.name
- business.website
- sources
- offers
- actions
Optional fields
Optional fields add precision when they are supported by source evidence: regions, service areas, menus, packages, availability, eligibility, deposit rules, cancellation rules, fulfillment rules, and partner export metadata.
Public and private fields
Public fields are approved for public output, JSON-LD, MCP-compatible access, protocol profiles, and partner exports. Private notes, internal review notes, privileged status, and implementation tasks stay out of public outputs.
Commerce Graph JSON schema excerpt
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://akii.com/schemas/commerce-graph.schema.json",
"type": "object",
"required": ["merchant_id", "graph_version", "business", "sources", "offers", "actions"],
"properties": {
"merchant_id": { "type": "string" },
"graph_version": { "type": "string" },
"status": { "enum": ["draft", "approved", "published"] },
"business": {
"type": "object",
"required": ["name", "website"],
"properties": {
"name": { "type": "string" },
"website": { "type": "string", "format": "uri" },
"category": { "type": "string" },
"locations": { "type": "array", "items": { "$ref": "#/$defs/location" } }
}
},
"offers": { "type": "array", "items": { "$ref": "#/$defs/offer" } },
"actions": { "type": "array", "items": { "$ref": "#/$defs/action_path" } },
"sources": { "type": "array", "items": { "$ref": "#/$defs/source" } }
}
}