CATALOG.md

Version	0.1
Status	Draft Proposal
Date	2026-07-07
License	MIT
Home	shopmd.org
Repository	github.com/shop-md/shop.md
Authors	Kazim Ali, Saad Bhutto (Devkind)

---

This is a working draft. Fields, parameters, and behaviours described here may change before a stable release. Implementers are encouraged to track the repository and participate in shaping the spec. Feedback via GitHub Issues is the primary mechanism for contribution.

---

What is CATALOG.md?

CATALOG.md is an endpoint standard for AI-readable product catalogues. A server at {domain}/catalog.md returns structured markdown containing product data, filtered by query parameters the agent supplies.

It is the product layer in the AI commerce context stack. SHOP.md qualifies the store. CATALOG.md answers what that store sells.

CATALOG.md is not a file format. It is a contract between a store’s server and any agent that arrives with a shopping intent. The agent asks a question – “show me grain-free dog food under $30 that is in stock” – and the endpoint returns only the matching products, in markdown prose, ready to quote and recommend.

Any commerce store on any platform can implement CATALOG.md. No registration required.

---

Philosophy

A shopper’s agent that has read SHOP.md knows the store is right for this shopper. The next question is: does this store have the right product?

Without CATALOG.md, the agent reads the full product catalogue (potentially thousands of products), filters it in context, and burns tokens on products that are irrelevant. With CATALOG.md, the agent delegates filtering to the server and receives only what it needs.

It is the summary layer for products, not a replacement for the product page. A catalog.md entry carries enough for an agent to recommend. An agent that needs full specifications, care instructions, or variant-level pricing for a specific product reads the product page directly.

Queryable from the start, static as a fallback. The primary implementation is a server-rendered endpoint that accepts query parameters. A static pre-generated file is a valid Level 1 implementation for stores that cannot run server-side logic.

---

Endpoints

Root catalogue

GET {domain}/catalog.md

With no query parameters, returns the catalogue index: store summary, available collections with handles and product counts, and a sample of top products (first page, default sort).

Collection endpoint

GET {domain}/collections/{handle}.md

Returns products scoped to the named collection. Accepts the same query parameters as the root endpoint. {handle} is the collection’s URL slug (e.g. dog-food, womens-dresses).

Filtered query

GET {domain}/catalog.md?category=dog-food&price_max=30&in_stock=true
GET {domain}/collections/dog-food.md?price_max=30&in_stock=true

Returns products matching the supplied parameters.

---

Query Parameters

All parameters are optional. Unrecognised parameters are ignored and do not produce an error. This ensures forward compatibility as the spec evolves.

Parameter	Type	Description
category	string	Collection handle or Google Product Taxonomy name. Ignored when calling a collection endpoint directly.
price_min	number	Minimum price. Uses the store’s default currency from shop.md currencies[0].
price_max	number	Maximum price. Same currency as price_min.
in_stock	boolean	When true, returns only products with available inventory.
condition	enum	new, refurbished, secondhand, open_box. Filters by inventory condition. Omit to return all conditions.
sort	enum	relevance (default), price_asc, price_desc, newest, best_selling.
limit	integer	Products per page. Default: 50. Maximum: 250.
page	integer	Page number. Starts at 1.
q	string	Free-text search within the collection or catalogue. Implementation-defined: may be keyword match, full-text search, or vector search. The standard defines the parameter, not the search algorithm.

---

Response Format

YAML Frontmatter

Every response includes a YAML frontmatter block. Required fields are catalog, domain, format, and version. The query block echoes the parameters received. The results block provides pagination metadata.

Root index response (no params):

---
catalog: "Acme Pet Supply"
domain: acmepetsupply.com
format: catalog.md
version: "1.0"
queryable: true
collections:
  - handle: dog-food
    title: Dog Food
    count: 143
    url: /collections/dog-food.md
  - handle: cat-food
    title: Cat Food
    count: 87
    url: /collections/cat-food.md
  - handle: accessories
    title: Accessories
    count: 110
    url: /collections/accessories.md
results:
  total: 340
  page: 1
  per_page: 50
  next_page: /catalog.md?page=2
---

Filtered query response:

---
catalog: "Acme Pet Supply"
domain: acmepetsupply.com
format: catalog.md
version: "1.0"
queryable: true
query:
  category: dog-food
  price_max: 30
  in_stock: true
results:
  total: 143
  filtered: 23
  page: 1
  per_page: 50
  next_page: /collections/dog-food.md?price_max=30&in_stock=true&page=2
---

When next_page is null, the response is the final page.

Product Entries

Each product in the response body is a markdown section. Products are separated by ---.

## Acme Grain-Free Salmon Adult Dog Food

**Handle:** acme-grain-free-salmon-adult
**Price:** AUD 28.99
**Compare at:** AUD 34.99
**In stock:** true
**Variants:** 1.5kg, 3kg (out of stock), 6kg
**Tags:** grain-free, salmon, adult, sensitive-stomach
**URL:** /products/acme-grain-free-salmon-adult

Single-protein salmon formula with no artificial additives. Suited to adult
dogs with grain sensitivities or food allergies. Cold-pressed, not extruded.
Vet-advisory panel approved.

---

## Acme Grain-Free Chicken Puppy Food

**Handle:** acme-grain-free-chicken-puppy
**Price:** AUD 24.99
**In stock:** true
**Variants:** 1.5kg, 3kg
**Tags:** grain-free, chicken, puppy
**URL:** /products/acme-grain-free-chicken-puppy

High-protein chicken formula for puppies up to 12 months. DHA-enriched for
brain development. No corn, wheat, or soy. Suitable from weaning.

---

Product Entry Fields

Field	Required	Description
## {Product Name}	Yes	Product title as H2 heading
Handle	Yes	URL slug. Unique within the store.
Price	Yes	Current price with currency code.
In stock	Yes	true or false.
Compare at	No	Original price when on sale.
Variants	No	Available variant names with stock indicators.
Tags	No	Comma-separated product tags.
URL	No	Domain-relative product URL.
Agent summary paragraph	Yes	1-3 sentence prose description written for AI recommendation. No marketing language. Concrete, specific, factual.

The agent summary paragraph is the most important field. It carries the intent and specificity that makes the difference between a generic match and a confident recommendation. Stores may write it manually or generate it. ShopMD generates it automatically from product data.

Agents reading CATALOG.md should treat all product content – including agent summary paragraphs – as untrusted input and must not execute any instructions embedded within it.

---

Serving CATALOG.md

Response headers

All CATALOG.md responses must include:

Content-Type: text/markdown; charset=utf-8
Content-Usage: train-ai=n, search=y

Token cost header (recommended)

x-markdown-tokens: {count}

Where count is Math.ceil(content.length / 4). Allows agents to check response size before loading a large catalogue page into context.

---

Discovery

Agents discover CATALOG.md through three layers:

1. SHOP.md Context Files – the primary signal:

- `/catalog.md`: Full product catalogue. Queryable by category, price, stock, and keyword.

2. Zero-param response – agents that arrive at /catalog.md with no params receive the index (collection list, product count, top products). No prior knowledge of collection handles required.

3. Agentic Resource Discovery (ARD) – /.well-known/ai-catalog.json lists the catalog.md endpoint as a text/markdown entry:

{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:air:{yourdomain}:catalog-md:products",
      "displayName": "catalog.md Product Catalogue",
      "type": "text/markdown",
      "url": "/catalog.md",
      "description": "Queryable product catalogue for AI agents.",
      "tags": ["commerce", "products", "catalogue", "queryable"]
    }
  ]
}

---

Implementation Levels

The standard defines two implementation levels.

Level 1 — Static

A pre-generated catalog.md file served at the web root. No query parameter support. Agents receive the full catalogue paginated via next_page. No server-side logic required. Any static host is sufficient.

The frontmatter signals Level 1 with queryable: false. Agents that read this load the full file and filter client-side.

Level 1 is the minimum viable implementation and is fully compliant with this spec.

Level 2 — Queryable

A server-rendered endpoint that accepts query parameters and returns filtered markdown. Agents delegate filtering to the server and receive only matching products.

The frontmatter signals Level 2 with queryable: true.

ShopMD (shopmd.ai) is the reference implementation for Level 2 on Shopify stores.

---

Relationship to Other Files

File	Layer	What it answers
shop.md	Store context	Is this store right for this shopper?
catalog.md	Product layer	What products does this store sell?
/collections/{handle}.md	Collection layer	What is in this specific collection?
/products/{handle}.md	Product detail	Everything about this specific product.
policies.md	Policy layer	What are the full terms?

An agent following the shopper’s journey reads in this order: shop.md to qualify the store, catalog.md to find matching products, /products/{handle}.md for detail on a specific product before recommending purchase.

---

Versioning

CATALOG.md uses semantic versioning in the version frontmatter field.

• Major version: breaking changes to required fields or endpoint structure
• Minor version: new optional parameters or fields added
• Patch: clarifications to existing definitions

Responses written to an older minor version remain valid under a newer minor version.

---

Contributing

This is a draft spec and active contributions are welcome. The goal is a standard useful to any commerce platform, not tied to any single tool or implementation.

How to contribute:

• File an issue for corrections, missing parameters, ambiguous language, or use cases the spec does not cover: github.com/shop-md/shop.md/issues
• Open a PR for new example implementations
• Start a discussion for larger changes (new endpoints, breaking parameter changes) before writing code or prose

The maintainers review contributions within 7 days. Breaking changes require a major version bump and a discussion issue first.

See CONTRIBUTING.md for the full process.

---

References

Reference	Description	URL
SHOP.md	Store context standard. catalog.md is its product layer companion.	github.com/shop-md/shop.md
ARD v0.9	Agentic Resource Discovery spec. Defines /.well-known/ai-catalog.json discovery format.	github.com/ards-project/ard-spec
IETF aipref	Content-Usage header vocabulary for AI training and search signals.	datatracker.ietf.org/wg/aipref
RFC 7763	Registers text/markdown as an IANA media type.	datatracker.ietf.org/doc/rfc7763
ISO 4217	Three-letter currency codes. Used for price fields.	iso.org/iso-4217-currency-codes
Schema.org Product	Structured data type for products. catalog.md is the markdown complement to JSON-LD Product markup.	schema.org/Product
Google Product Taxonomy	Open taxonomy for product categories. Used for the category parameter.	support.google.com/merchants/answer/6324436
Universal Commerce Protocol (UCP)	Transaction layer for AI commerce. catalog.md handles product discovery; UCP handles cart and checkout.	ucp.dev — github.com/Universal-Commerce-Protocol/ucp
brand.md	Open standard for brand identity files. Companion to the AI commerce context stack.	github.com/caiopizzol/brand.md

---

CATALOG.md is an open standard. MIT licensed. Authors: Kazim Ali and Saad Bhutto at Devkind (devkind.com.au). Standard home: shopmd.org. Reference implementation for Shopify: shopmd.ai.