ARC/1.0 — Agent-Readable Catalog

Spezifikationsversion ARC/1.0 · Veröffentlicht am 2026-06-10 · Status: Stabil
Steward: Save The Brain (KaliCart) · Lizenz: CC BY 4.0 · Referenzimplementierung: KaliCart Bridge ≥ 1.0.114 für WooCommerce

Abstract. ARC definiert, wie ein E-Commerce-Storefront seinen Katalog als maschinenlesbare, schreibgeschützte REST-Oberfläche bereitstellt, die autonome KI-Agenten entdecken, denen sie vertrauen und die sie konsumieren können — ohne Scraping, Authentifizierung oder Anbieterbindung. Sie spezifiziert drei Discovery-Signale, ein selbstbeschreibendes Discovery-Dokument, einen Katalog-Endpunkt-Vertrag, ein normatives Produktobjekt, ein explizites Consent-Modell für die föderierte Indexierung sowie Interoperabilität mit UCP (/.well-known/ucp). ARC ist plattformneutral; dieses Dokument verwendet durchgehend WooCommerce-Beispiele.

1. Konformitätsstufen & Terminologie

Die Schlüsselwörter must, must not, should und may sind wie in RFC 2119 beschrieben zu interpretieren.

Stufe	Name	Anforderungen
ARC-READ	Lesbarer Katalog	Mindestens ein Discovery-Signal (§2), ein gültiges Discovery-Dokument (§3) sowie die Endpunkte `search`, `products`, `product` und `categories` (§4), die Produktobjekte (§5) ausliefern. Keine Authentifizierung auf keiner dieser Oberflächen.
ARC-TRUST	Vertrauenswürdiger Katalog	ARC-READ, plus: Qualitäts-Quarantäne (§5.6), explizite Consent-Flags (§6), Freshness-Metadaten, ehrliche Bestandskonfidenz (§5.4) und die Preis-/Gesamtsummen- Verifizierungsregeln aus §5.3.
ARC-CHECKOUT	Checkout-Übergabe	ARC-TRUST, plus Checkout-Sitzungen (§7). Die Zahlung must auf dem Merchant-Storefront verbleiben; ARC-Oberflächen verarbeiten niemals Zahlungen.

2. Discovery-Signale

Ein konformer Storefront must mindestens eines — und should alle — der folgenden Signale veröffentlichen, die jeweils zum Discovery-Dokument auflösen:

2.1 HTML-Head-Link

<link rel="kalicart-agent" type="application/json"
      href="https://shop.example.com/wp-json/kalicart/v1/discovery" />

Die Relation rel="kalicart-agent" im <head> des Storefronts ist das primäre In-Band-Signal. Agenten, die Storefront-HTML parsen, should den Head prüfen, bevor sie einen Katalog aus dem Seiteninhalt rekonstruieren. Implementierungen may zusätzlich einen sichtbaren Body-Anker (Badge) rendern, der auf einen von Mensch/Agent lesbaren Index verweist; Feldtests zeigen, dass Body-Anker die Discovery durch DOM-browsende Agenten deutlich verbessern.

2.2 Well-known-Pfade

Der Storefront should /.well-known/agent.json, /.well-known/agent-catalog und einen implementierungsbenannten Alias (Referenz: /.well-known/kalicart-bridge) ausliefern, jeweils mindestens mit der Discovery-Dokument-URL und der Implementierungsversion.

2.3 Crawl-Oberflächen

Der Storefront may die Discovery-URL in robots.txt bekanntgeben (als Kommentar-/Allow-Eintrag) und eine agentenorientierte Sitemap bereitstellen, die die Katalog-Endpunkte aufzählt.

3. Das Discovery-Dokument

Ein einziges, selbstbeschreibendes JSON-Dokument. Es ist der Vertrag: ein Agent, der es gelesen hat, braucht keine Out-of-Band-Dokumentation. Normative Felder:

Feld	Anf.	Bedeutung
`document_kind`	MUST	Feste Zeichenkette zur Identifikation der Dokumentfamilie (Referenz: `kalicart_agent_discovery`).
`schema_version`	MUST	Version des Dokumentschemas.
`plugin_version`	MUST	Implementierungsversion (semver).
`endpoints{}`	MUST	Absolute URLs für `discovery`, `search`, `products`, `product` (templated `{id}`), `categories`, `meta`.
`authentication`	MUST	`{required:false, scheme:"none"}` für alle öffentlichen Katalogoberflächen.
`capabilities{}`	MUST	Ehrliche boolesche Map: `search`, `offers`, `availability`, `shipping_policy`, `coupon_hints`, `cart`, `checkout`, `payments`, `mutations`, `read_only`. Nicht implementierte Capabilities must `false` sein.
`crawler_policy{}` / `intent_flags{}`	MUST (L2)	Consent-Modell — siehe §6.
`price_format`	MUST	Deklaration der Preiscodierung — siehe §5.3.
`variation_discovery`	MUST	Deklariert den Liste-vs-Detail-Varianten-Vertrag — siehe §5.5.
`freshness`	SHOULD (L2)	Ob die Daten live oder ein Snapshot sind, und deren Staleness-Grenze.
`trust{}`	SHOULD	`safe_for[]` / `not_for[]`-Aufgabenlisten, Checkout-Autorität, Coupon-Preisregel.
`ucp_profile_url`	SHOULD	Absolute URL von `/.well-known/ucp` — siehe §8.
`merchant{}`, `return_policy`, `merchant_shipping_policy`	SHOULD	Grenzwahrheiten, offengelegt als strukturierte Daten, niemals als Prosa-Hinweis.

Design-Regel — Grenzwahrheit. Alles, wofür der Merchant maßgeblich ist (Preis, Verfügbarkeit, Versand beim Checkout, Rückgaberichtlinie), must als strukturierte Daten mit einem expliziten Autoritätshinweis offengelegt werden und must not durch berechnete oder beratende Werte ersetzt werden.

4. Katalog-Endpunkte

Alle Endpunkte sind schreibgeschützt (GET), unauthentifiziert, JSON. Referenzbasis: /wp-json/kalicart/v1/.

Endpoint	Vertrag
`catalog/search`	Filter: `q`, `category`, `gender`, `color`, `on_sale`, `in_stock`, `min_price`, `max_price`. Akzeptierte Filter must von `catalog/meta` aufgezählt werden.
`catalog/products`	Paginierte Liste. Die Antwort must `products[]`, `total`, `page`, `per_page`, `total_pages` enthalten.
`catalog/product/{id}`	Einzelnes Produkt mit vollständigem `variants[]` (siehe §5.5).
`catalog/categories`	Kategoriebaum mit Produktanzahl pro Knoten. Kategorien sind die eigene Taxonomie des Merchants; ARC erzwingt keine globale Taxonomie.
`catalog/meta`	Akzeptierte Filter und die Preisspanne des Katalogs.

5. Das Produktobjekt

5.1 Identität

id, sku, type (simple|variable), name, slug, url, status, categories[] (jeweils mit einem vollständigen path wie "Wine > Prosecco"), tags[], barcodes[] (EAN/GTIN/UPC, sofern vorhanden — additiv, leer, wenn nicht vorhanden).

5.2 Herkunft

metadata.bridge_version (Implementierungsversion, die das Objekt erzeugt hat) und updated_at/created_at must vorhanden sein.

5.3 Preis

Katalogpreise werden als decimal_major_units codiert (z.B. 29.99 = 29,99 EUR), und die Codierung must in price_format deklariert werden. price.current ist immer der Katalogpreis des Merchants; Coupons sind bedingte Checkout-Ersparnisse und must not ihn ersetzen. list_price trägt den durchgestrichenen Listenpreis für die UCP-Interop. Agenten must not Summen nennen, die der Merchant-Checkout nicht berechnet hat (Gesamtsummen-Verifizierungsregel).

5.4 Stock

stock.availability_status verwendet UCP-Standardwerte (in_stock, out_of_stock, backorder). stock.confidence deklariert die Genauigkeit ehrlich: numeric_stock_quantity, availability_status_only oder variant_dependent. Ist quantity null, must not der Agent kein numerisches Inventar erfinden.

5.5 Varianten

variants[] ist immer ein Array, nie null. In Listen- und Suchantworten: ein einzelner Eintrag für einfache Produkte, ein leeres Array für variable Produkte — vollständige Varianten kommen von catalog/product/{id}. Diese Asymmetrie must in variation_discovery.list_context_note deklariert werden. Agenten must not einen Endpreis für ein variables Produkt nennen, bevor eine Variante ausgewählt wurde.

5.6 Qualitäts-Quarantäne ARC-TRUST

Jedes Produkt trägt quarantine: {in_quarantine, score, flags[]}. Der Score beginnt bei 100 mit Abzügen für fehlenden Titel, Beschreibung, Kategorie, Preis, Bild, SKU. Produkte, die wegen struktureller Mängel (Titel/Beschreibung/Kategorie/Preis) unter Quarantäne gestellt wurden, must von jedem nachgelagerten, auf dem Katalog aufgebauten Index ausgeschlossen werden. Der Merchant behält ein privates Health-Dashboard; die öffentliche Oberfläche zeigt nur das Verdikt.

5.7 Kaufbereitschaft

purchase_readiness: {status, blocking_fields[], can_add_to_cart_directly} teilt dem Agenten mit, ob ein direktes Add-to-Cart via checkout_url möglich ist oder welche Attribute zuerst ausgewählt werden müssen.

6. Consent & Crawl-Policy ARC-TRUST

ARC trennt das Lesen eines einzelnen Shops (auf öffentlichen Oberflächen immer erlaubt) von der föderierten Indexierung (Aggregation des Katalogs in einen händlerübergreifenden Index). Die Zustimmung für Letzteres wird vom Merchant im Discovery-Dokument veröffentlicht — das robots.txt-Modell: das Signal lebt bei den Daten, und der Indexierer ist verpflichtet, es zu respektieren.

"crawler_policy": {
  "allow_llm_training":    false,
  "allow_live_agent_reads": true,
  "allow_global_indexing":  true
},
"intent_flags": {
  "single_merchant_only":    true,
  "global_indexable":        true,
  "federated_search_source": true,
  "agent_read_surface":      true
}

Ein föderierter Indexierer must diese Flags zum Zeitpunkt des Probes lesen, must not einen Katalog aufnehmen, dessen allow_global_indexing false ist, und must sich mit einem ehrlichen User-Agent identifizieren. Die Referenzimplementierung liefert die Zustimmung standardmäßig aktiviert mit Ein-Klick-Opt-out im Merchant-Admin aus; beide Standardeinstellungen sind konform, aber der Umschalter must existieren, und die veröffentlichten Flags must ihn innerhalb der Freshness-Grenze widerspiegeln.

7. Checkout-Sitzungen (optional) ARC-CHECKOUT

POST checkout/session erstellt eine Warenkorb-Sitzung für ein oder mehrere Produkte und liefert cart_url / checkout_url. Der Mensch schließt die Zahlung auf dem Merchant-Storefront ab. ARC-Oberflächen must not Zahlungen erfassen, Zahlungsdaten speichern oder OAuth für diese Übergabe verlangen. Die Capability ist standardmäßig deaktiviert, und ihr Status must in capabilities.checkout_sessions sichtbar sein.

8. UCP-Interoperabilität

Eine konforme Implementierung should /.well-known/ucp ausliefern, das catalog.search und catalog.lookup deklariert, und es über ucp_profile_url verlinken. Die Verträge availability_status, list_price und variants[] von ARC sind auf UCP abgestimmt, sodass ein Katalog beide Ökosysteme ohne Übersetzung bedient.

9. Sicherheitsüberlegungen

Alle öffentlichen Oberflächen sind schreibgeschützt; capabilities.mutations must false sein. Keine API-Schlüssel auf öffentlichen Oberflächen — Geheimnisse in Agentenkontexten sickern durch. Föderierte Probes must SSRF-Schutzmaßnahmen anwenden (keine IP-Literale, keine internen Hostnamen, begrenzte Redirects/Timeouts) und einen identifizierenden User-Agent. Admin-/Health-Oberflächen must Plattform-Capability-Prüfungen verlangen. Implementierungen must not Drittanbieterdienste vom Server des Merchants als Nebeneffekt der Katalog-Auslieferung aufrufen.

10. Änderungsprotokoll der Spezifikation

Version	Datum	Notizen
`ARC/1.0`	2026-06-10	Erste stabile Veröffentlichung. Kodifiziert den von KaliCart Bridge 1.0.76 ausgelieferten Vertrag: drei Discovery-Signale, Discovery-Dokument, fünf Katalog-Endpunkte, Produktobjekt mit Quarantäne und Kaufbereitschaft, Opt-out-Consent-Modell für die föderierte Indexierung, optionale Checkout-Sitzungen, UCP-Interop.

Feedback und Implementierungsberichte: GitHub issues.