Articles and guides on launching and growing your online store
Integrations, SEO, marketing, dropshipping and online store automation

AI Catalog (ai-catalog.json) for a Website: What It Is and How to Set It Up

AI Catalog (ai-catalog.json) for a website: structure, examples, and data types

AI Catalog (ai-catalog.json): What It Is and How to Set It Up

A step-by-step guide: why ai-catalog.json matters, which fields are required, how to specify a catalog with language and pers_shop, where to manage the ai_catalog page on BooStore, and how JSON validation works.

1. What ai-catalog.json is and why you need it

ai-catalog.json is a machine-readable catalog of a website's key resources for AI agents and LLMs. It complements llms.txt: llms.txt provides a text description, while AI Catalog lists specific pages with identifiers and representative user queries.

  • Helps AI search and agents understand the store structure and find the right sections.
  • Does not replace sitemap.xml or robots.txt; they serve different purposes.
  • Published at /.well-known/ai-catalog.json and available without authorization.

2. Spec 1.0: required rules

Validation runs when the ai_catalog page is saved. If the JSON does not match the rules, the page is not saved.

  • specVersion must be the string "1.0" (a bare number is an error).
  • host must contain only displayName.
  • entries must contain at least one item.
  • identifier must be urn:air:::, Latin characters only.
  • url must be a full https:// address returning 200.
  • representativeQueries must contain 2 to 5 strings.

3. Minimal example

BooStore defaults for a regular site include only the home page of your domain with the language prefix. Add more resources manually.

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Your site name"
  },
  "entries": [
    {
      "identifier": "urn:air:example.com:site:home",
      "displayName": "Home page",
      "type": "text/html",
      "url": "https://example.com/en/",
      "representativeQueries": [
        "about the site and its sections",
        "contacts and terms"
      ]
    }
  ]
}

4. Extended example: different data types

The extended example covers different data types: a page, an article, a product category, a product, a blog category, and a manufacturer. Catalog URLs include the language and pers_shop: /<lang>/pers_shop/, /<lang>/pers_shop/<category>/, /<lang>/pers_shop/<category>/<slug>_<id>.htm.

{
  "specVersion": "1.0",
  "host": { "displayName": "My store" },
  "entries": [
    {
      "identifier": "urn:air:example.com:page:about",
      "displayName": "About page",
      "type": "text/html",
      "url": "https://example.com/en/about.htm",
      "representativeQueries": ["about the company and terms", "contacts and details"]
    },
    {
      "identifier": "urn:air:example.com:article:how-to-choose",
      "displayName": "Article “How to choose a product”",
      "type": "text/html",
      "url": "https://example.com/en/blog/news_en/how-to-choose.htm",
      "representativeQueries": ["how to choose a product", "tips before buying"]
    },
    {
      "identifier": "urn:air:example.com:category:laptops",
      "displayName": "Product category “Laptops”",
      "type": "text/html",
      "url": "https://example.com/en/pers_shop/laptops/",
      "representativeQueries": ["laptops in the catalog", "laptop prices"]
    },
    {
      "identifier": "urn:air:example.com:product:437544",
      "displayName": "Product “Laptop model 437544”",
      "type": "text/html",
      "url": "https://example.com/en/pers_shop/laptops/laptop-model_437544.htm",
      "representativeQueries": ["laptop specs and price", "model reviews"]
    },
    {
      "identifier": "urn:air:example.com:blog:news",
      "displayName": "Blog category “News”",
      "type": "text/html",
      "url": "https://example.com/en/blog/news_en/",
      "representativeQueries": ["store news", "useful articles"]
    },
    {
      "identifier": "urn:air:example.com:producer:brand",
      "displayName": "Manufacturer “Brand”",
      "type": "text/html",
      "url": "https://example.com/en/producer/brand/",
      "representativeQueries": ["Brand manufacturer products", "brand and its models"]
    }
  ]
}

5. The AI Catalog functional page

AI Catalog is a functional page under Pages. It lets you fill the public /.well-known/ai-catalog.json: specify the site name and the key pages AI agents should know about.

  • The main BooStore.pro site already has the platform catalog filled in: capabilities, llms.txt, and documentation.
  • For your site, the catalog is filled in manually on the AI Catalog page.
  • The default for a regular site is only the home page with the language; add the rest yourself.

The public file URL is /.well-known/ai-catalog.json.

6. How to fill /.well-known/ai-catalog.json

Open Pages → Create Functional page → AI Catalog. Paste your JSON into the text field and save. There is no pre-filled sample — use the examples above.

/.well-known/ai-catalog.json — If the JSON is invalid, the page is not saved and an error message appears in admin.

7. Recommendations

  • Use only real URLs that return 200.
  • Use 2–5 natural queries per entry.
  • Do not duplicate entries or mix languages in URLs.
  • Update the catalog when the store structure changes.
  • Validate JSON before saving: errors are shown in admin.

8. Full guide: placement, robots/sitemap, and validation

What it is. AI Catalog is a machine-readable manifest for AI agents. See this article for details: AI Catalog.

Where to place it. The public file must respond at /.well-known/ai-catalog.json in the domain root. On BooStore, /ai-catalog.json (301 to well-known) and language versions /{lang}/ai-catalog.json also work for compatibility.

How to create it on BooStore. Open Pages → Create Functional page → AI Catalog, paste JSON into the text field, and save. Validation checks specVersion, host.displayName, entries, identifier, https URLs, and representativeQueries. There is no hard entry-count limit — up to 500 is recommended. If JSON is larger than 512 KB, a warning is shown but saving is allowed.

Sitemap and robots. Do not add ai-catalog.json or llms.txt to sitemap.xml: the sitemap is for HTML pages. Do not block them in robots.txt; it is useful to explicitly allow them: Allow: /.well-known/ai-catalog.json and Allow: /llms.txt.

Recommended together with llms.txt. Add /llms.txt: it gives AI a text description, while AI Catalog provides a structured list of key resources. More: llms.txt guide.

llms.txt example

The file is created the same way as AI Catalog: Pages → Create Functional page → type “LLM / llms.txt”. Paste a short site description and links to key sections into the text field.

# Site name
> Short description of the site and store.

## Store
- Catalog: https://example.com/en/pers_shop/
- Delivery: https://example.com/en/delivery.htm
- Payment: https://example.com/en/payment.htm

## Company
- About: https://example.com/en/about.htm
- Contacts: https://example.com/en/contacts.htm

The public file address is /llms.txt in the domain root.

Validation: after saving, open /.well-known/ai-catalog.json and make sure it returns 200, application/json, valid JSON, and that URLs in entries open. Validation errors are shown in admin when saving the page.
  • Use only real https:// URLs that return 200.
  • Use 2–5 natural queries in representativeQueries.
  • Use Latin characters in identifier as urn:air:domain:category:name.
  • Update the catalog when the store structure changes.
  • Do not duplicate entries or mix languages in URLs unnecessarily.

9. FAQ

How is ai-catalog.json different from llms.txt?

llms.txt is a text knowledge base; ai-catalog.json is a structured list of key resources.

Is a catalog required in the defaults?

No. Only the home page is provided by default; add the rest yourself.

What happens if JSON is invalid?

The page is not saved and an error message appears in admin.

Do I need a separate file in the root?

No. Everything is filled in on the AI Catalog functional page.

Where should ai-catalog.json be placed?

The correct path is /.well-known/ai-catalog.json in the domain root. BooStore redirects /ai-catalog.json to it, and language versions are available at /{lang}/ai-catalog.json.

Should ai-catalog.json and llms.txt be added to sitemap.xml?

No. The sitemap is for HTML pages; manifests and text summaries do not belong there.

How are ai-catalog.json and robots.txt related?

Do not block the file in robots.txt. It is better to explicitly allow /.well-known/ai-catalog.json and /llms.txt so search and AI crawlers can read them.

Can I create AI Catalog on BooStore without code?

Yes: Pages → Create Functional page → AI Catalog. JSON is validated on save and errors are shown in admin. There is no hard entry-count limit; up to 500 is recommended.

Should llms.txt be listed in ai-catalog.json?

Not necessarily. AI Catalog lists the site's key HTML pages, while llms.txt is a separate text file at /llms.txt that AI agents find at the standard path. You can add it to entries as an extra resource if you want, but it is not required.

Why use llms.txt together with AI Catalog?

llms.txt provides a text description for AI, while AI Catalog provides a structured resource list. Use them together. Guide: llms.txt guide.

Need a store with AI Catalog ready? Create a site on BooStore — catalog, SEO, and AI markup are built in.

Create a site on BooStore

Online store payment methods: how to accept money (Ukraine/world). Full BooStore guideGuide to Creating llms.txt for Your Website. SEO for AI.Online Store Promotion from Scratch: Full Traffic Strategy