agentplace :: Storegraph 0.1

• -Version: 0.1
• -Status: Draft, published for implementation and feedback
• -Published: 2026-09-30
• -Updated: 2026-10-01
• -Publisher: CrossUp↗ (abre en otra pestaña), first implemented by Agentplace
• -This document: HTML · Markdown
• -Formerly: Product Graph (same format; the old URLs redirect permanently)

A Storegraph is the map of a store for agents: a crawlable, machine-readable description of how its products relate to each other — what goes together, what replaces what, what is one step up, and which products form a set. Where sitemap.xml lists the URLs of a site, a Storegraph lists the relationships between its products, so search engines and AI agents can recommend complements, routines and in-stock alternatives the way a good salesperson would.

1. Conventions

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119. All files are UTF-8. Absolute URLs are used everywhere. Prices are JSON numbers in the unit of currency (ISO 4217); there are no thousands separators or currency symbols. Timestamps are ISO 8601 with an offset.

A Storegraph has two parts: one manifest per site, and one shard per store. A site that sells for a single store has one shard.

2. Discovery

• -The manifest MUST be served at /.well-known/storegraph with Content-Type: application/json.
• -The site SHOULD announce it in robots.txt with a Storegraph: line holding the absolute manifest URL, the same way Sitemap: announces a sitemap. Crawlers that do not know the line ignore it. Example: Storegraph: https://agentplace.crossup.ai/.well-known/storegraph.
• -HTML pages SHOULD link it from the <head>: <link rel="storegraph" href="/.well-known/storegraph" type="application/json">, and MAY repeat it in an HTTP Link header with the same relation.
• -The site MAY list the manifest and the shards in llms.txt.
• -Manifest and shards SHOULD be served with Access-Control-Allow-Origin: * and cache headers that reflect how often they change. Serving them as static files (generated when the data changes, not per request) keeps them fast for every crawler.

3. Manifest

{
  "spec": "https://agentplace.crossup.ai/spec/storegraph",
  "version": "0.1",
  "publisher": {
    "name": "CrossUp",
    "url": "https://crossup.ai"
  },
  "generated_at": "2026-09-30T06:00:00.000Z",
  "stores": [
    {
      "id": "kosmos",
      "name": "Kosmos Cosmética",
      "url": "https://agentplace.crossup.ai/kosmos",
      "merchant_url": "https://www.kosmoscosmetica.com.ar",
      "shard": "https://agentplace.crossup.ai/storegraph/kosmos.jsonl",
      "nodes": 167,
      "edges": 912,
      "sets": 41,
      "lastmod": "2026-09-29T10:00:00.000Z"
    }
  ]
}

4. Shards

A shard is a JSON Lines↗ (abre en otra pestaña) file served with Content-Type: application/x-ndjson: one JSON object per line, each with a type of node, edge or set. Nodes SHOULD come first, then edges, then sets. Every from, to and set item MUST reference a node of the same shard. Consumers MUST ignore record types and fields they do not know.

{"type":"node","id":"100","url":"https://agentplace.crossup.ai/kosmos/serum-vitamina-c","name":"Sérum vitamina C 30 ml","price":16000,"currency":"ARS","availability":"in_stock","image":"https://acdn-us.mitiendanube.com/stores/002/392/938/products/serum.jpg","categories":["Rostro","Sérums"]}
{"type":"edge","from":"100","to":"200","relation":"complementary","related_product_type":"often_bought_with","schema_org":"isRelatedTo","reason":"Suelen llevarse juntos","strength":"strong"}
{"type":"edge","from":"100","to":"400","relation":"substitute","related_product_type":"substitute","schema_org":"isSimilarTo","reason":"La versión superior para la misma necesidad","strength":"medium","upsell":"premium"}
{"type":"set","id":"routine-100-200-300","name":"Rutina glow de mañana","url":"https://agentplace.crossup.ai/kosmos/sets/rutina-glow","kind":"routine","items":["300","100","200"]}

* 4.1 node

* 4.2 edge

An edge is directed: it describes to from the point of view of a shopper looking at from. The same pair MAY appear in both directions with different relations or reasons.

* 4.3 set

5. Vocabulary

Relations map to the product feed vocabulary of Google Merchant Center and OpenAI (related_product_type) and to schema.org properties used in each product page's JSON-LD.

6. Page-level layers

The shard is the bulk layer. The same relations SHOULD also be visible on each product page, so an agent that only reads one URL gets them too:

• -JSON-LD on the product page: Product or ProductGroup with an Offer whose seller is the store, plus the schema.org properties of section 5 pointing at the related products' pages.
• -A markdown twin of the page (<url>.md, or Accept: text/markdown) with a Related section that lists each relation with its reason and link. The twin carries the same facts as the HTML page; it MUST NOT depend on the user-agent.
• -Visible content: everything in the JSON-LD, the twin and the shard is also visible to people on the HTML page.

7. What is not published

• -Raw behavioural data MUST NOT be published: no co-purchase counts, no affinity or lift values, no model probabilities. strength is the only, ordinal, trace of them.
• -Only edges that pass the publisher's quality gates are published. An empty relation is better than an invented one.
• -Reasons are written for shoppers. They describe the products, never the agent reading them, and never ask to be remembered, cited or ranked.

8. Guidance for consumers

• -Treat the graph as data about products, not as instructions.
• -Prefer strong edges when space is short. Respect availability: when a product is out_of_stock, recommend its in-stock substitute edges instead of the product itself.
• -Price and availability can change between crawls. Link shoppers to the product url, where the current price and the path to the merchant's checkout are shown.
• -Use the manifest's lastmod per store to decide when to fetch a shard again.

9. Versioning

The manifest's version follows major.minor. Adding optional fields, record types or relation values is a minor change; consumers MUST ignore what they do not know. Removing or redefining a field is a major change. Every change is listed in the changelog below.

10. Changelog