ARC/1.0 — Agent-Readable Catalog
Abstract. ARC definisce come uno storefront e-commerce espone il proprio
catalogo come superficie REST leggibile da macchine, in sola lettura, che agenti AI autonomi
possono scoprire, di cui possono fidarsi e che possono consumare senza scraping, autenticazione
o vendor lock-in. Specifica tre segnali di discovery, un documento di discovery
autodescrittivo, un contratto per gli endpoint del catalogo, un oggetto prodotto normativo,
un modello di consenso esplicito per l'indicizzazione federata e l'interoperabilità con UCP
(/.well-known/ucp). ARC è neutrale rispetto alla piattaforma; questo documento usa
esempi WooCommerce.
1. Livelli di conformità e terminologia
Le parole chiave must, must not, should e may vanno interpretate come descritto nell'RFC 2119.
| Livello | Nome | Requisiti |
|---|---|---|
| ARC-READ | Catalogo leggibile | Almeno un segnale di discovery (§2), un documento di discovery valido (§3) e gli
endpoint search, products, product e categories
(§4) che servono oggetti prodotto (§5). Nessuna autenticazione su nessuna di queste superfici. |
| ARC-TRUST | Catalogo affidabile | ARC-READ, più: quarantena qualità (§5.6), flag di consenso espliciti (§6), metadati di freshness, confidenza dello stock onesta (§5.4) e le regole di verifica prezzo/totale del §5.3. |
| ARC-CHECKOUT | Handoff di checkout | ARC-TRUST, più sessioni di checkout (§7). Il pagamento must restare sullo storefront del merchant; le superfici ARC non processano mai pagamenti. |
2. Segnali di discovery
Uno storefront conforme must pubblicare almeno uno — e should pubblicarli tutti — dei seguenti segnali, ciascuno risolvibile verso il documento di discovery:
2.1 Link nell'head HTML
<link rel="kalicart-agent" type="application/json"
href="https://shop.example.com/wp-json/kalicart/v1/discovery" />La relazione rel="kalicart-agent" nell'<head> dello
storefront è il segnale primario in-band. Gli agenti che fanno il parsing dell'HTML dello
storefront should controllare l'head prima di ricostruire un catalogo
dal contenuto della pagina. Le implementazioni may inoltre mostrare
un'ancora visibile nel body (badge) che punta a un indice leggibile da umani/agenti; i test
sul campo mostrano che le ancore nel body migliorano sensibilmente la discovery da parte di
agenti che navigano il DOM.
2.2 Percorsi well-known
Lo storefront should servire /.well-known/agent.json,
/.well-known/agent-catalog e un alias con nome dell'implementazione
(riferimento: /.well-known/kalicart-bridge), ciascuno contenente come minimo
l'URL del documento di discovery e la versione dell'implementazione.
2.3 Superfici di crawl
Lo storefront may pubblicizzare l'URL di discovery nel
robots.txt (come voce commento/allow) ed esporre una sitemap orientata agli
agenti che enumera gli endpoint del catalogo.
3. Il documento di discovery
Un unico documento JSON autodescrittivo. È il contratto: un agente che lo ha letto non ha bisogno di documentazione fuori banda. Campi normativi:
| Campo | Req. | Significato |
|---|---|---|
document_kind | MUST | Stringa fissa che identifica la famiglia di documenti (riferimento: kalicart_agent_discovery). |
schema_version | MUST | Versione dello schema del documento. |
plugin_version | MUST | Versione dell'implementazione (semver). |
endpoints{} | MUST | URL assoluti per discovery, search, products, product (templato {id}), categories, meta. |
authentication | MUST | {required:false, scheme:"none"} per tutte le superfici pubbliche del catalogo. |
capabilities{} | MUST | Mappa booleana onesta: search, offers, availability, shipping_policy, coupon_hints, cart, checkout, payments, mutations, read_only. Le capability non implementate must essere false. |
crawler_policy{} / intent_flags{} | MUST (L2) | Modello di consenso — vedi §6. |
price_format | MUST | Dichiarazione dell'encoding del prezzo — vedi §5.3. |
variation_discovery | MUST | Dichiara il contratto delle varianti lista-vs-dettaglio — vedi §5.5. |
freshness | SHOULD (L2) | Se i dati sono live o uno snapshot, e il relativo bound di staleness. |
trust{} | SHOULD | Liste di task safe_for[] / not_for[], autorità di checkout, regola prezzo coupon. |
ucp_profile_url | SHOULD | URL assoluto di /.well-known/ucp — vedi §8. |
merchant{}, return_policy, merchant_shipping_policy | SHOULD | Verità di confine esposte come dati strutturati, mai come indicazioni discorsive. |
4. Endpoint del catalogo
Tutti gli endpoint sono GET in sola lettura, non autenticati, JSON. Base di
riferimento: /wp-json/kalicart/v1/.
| Endpoint | Contratto |
|---|---|
catalog/search | Filtri: q, category, gender, color, on_sale, in_stock, min_price, max_price. I filtri accettati must essere enumerati da catalog/meta. |
catalog/products | Lista paginata. La risposta must includere products[], total, page, per_page, total_pages. |
catalog/product/{id} | Singolo prodotto con variants[] completo (vedi §5.5). |
catalog/categories | Albero categorie con conteggio prodotti per nodo. Le categorie sono la tassonomia propria del merchant; ARC non impone una tassonomia globale. |
catalog/meta | Filtri accettati e range di prezzo del catalogo. |
5. L'oggetto prodotto
5.1 Identità
id, sku, type (simple|variable),
name, slug, url, status,
categories[] (ciascuna con un path completo come
"Wine > Prosecco"), tags[], barcodes[]
(EAN/GTIN/UPC quando presenti — additivo, vuoto quando assenti).
5.2 Provenienza
metadata.bridge_version (versione dell'implementazione che ha emesso l'oggetto) e
updated_at/created_at must essere presenti.
5.3 Prezzo
I prezzi del catalogo sono codificati come decimal_major_units (es. 29.99 =
29,99 EUR) e l'encoding must essere dichiarato in
price_format. price.current è sempre il prezzo di catalogo del merchant;
i coupon sono risparmi condizionali in checkout e must not sostituirlo.
list_price porta il prezzo di listino barrato per l'interop UCP. Gli agenti
must not citare totali che il checkout del merchant non ha calcolato
(regola di verifica del totale).
5.4 Stock
stock.availability_status usa i valori standard UCP
(in_stock, out_of_stock, backorder).
stock.confidence dichiara onestamente la precisione:
numeric_stock_quantity, availability_status_only, oppure
variant_dependent. Se quantity è null l'agente
must not inventare un inventario numerico.
5.5 Varianti
variants[] è sempre un array, mai null. Nelle risposte di
lista e ricerca: un singolo elemento per i prodotti semplici, un array vuoto
per i prodotti variabili — le varianti complete arrivano da catalog/product/{id}.
Questa asimmetria must essere dichiarata in
variation_discovery.list_context_note. Gli agenti must not
citare un prezzo finale per un prodotto variabile finché non è stata selezionata una variante.
5.6 Quarantena qualità ARC-TRUST
Ogni prodotto porta quarantine: {in_quarantine, score, flags[]}. Il punteggio
parte da 100 con detrazioni per titolo, descrizione, categoria, prezzo, immagine, SKU mancanti.
I prodotti messi in quarantena per difetti strutturali (titolo/descrizione/categoria/prezzo)
must essere esclusi da qualsiasi indice a valle costruito sul catalogo.
Il merchant mantiene una dashboard di salute privata; la superficie pubblica espone solo il verdetto.
5.7 Prontezza all'acquisto
purchase_readiness: {status, blocking_fields[], can_add_to_cart_directly}
dice all'agente se un add-to-cart diretto tramite checkout_url è possibile o quali
attributi vanno selezionati prima.
6. Consenso e crawl policy ARC-TRUST
ARC separa la lettura di un singolo negozio (sempre consentita sulle superfici pubbliche) dall'indicizzazione federata (aggregare il catalogo in un indice cross-merchant). Il consenso per quest'ultima è pubblicato dal merchant nel documento di discovery — il modello robots.txt: il segnale vive insieme ai dati, e l'indicizzatore è vincolato a rispettarlo.
"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
}Un indicizzatore federato must leggere questi flag al momento del
probe, must not ingerire un catalogo il cui
allow_global_indexing è false, e must identificarsi
con uno User-Agent onesto. L'implementazione di riferimento spedisce il consenso
abilitato di default con opt-out a un click nell'admin del merchant; entrambi
i default sono conformi, ma il toggle must esistere e i flag
pubblicati must rifletterlo entro il bound di freshness.
7. Sessioni di checkout (opzionale) ARC-CHECKOUT
POST checkout/session crea una sessione carrello per uno o più prodotti e
restituisce cart_url / checkout_url. L'umano completa il pagamento
sullo storefront del merchant. Le superfici ARC must not catturare
pagamenti, memorizzare credenziali di pagamento, o richiedere OAuth per questo handoff. La
capability è disattivata di default e il suo stato must essere
visibile in capabilities.checkout_sessions.
8. Interoperabilità UCP
Un'implementazione conforme should servire
/.well-known/ucp dichiarando catalog.search e
catalog.lookup, e collegarlo tramite ucp_profile_url.
I contratti availability_status, list_price e variants[]
di ARC sono allineati a UCP così che un solo catalogo serva entrambi gli ecosistemi senza
traduzione.
9. Considerazioni di sicurezza
Tutte le superfici pubbliche sono in sola lettura; capabilities.mutations
must essere false. Nessuna API key sulle superfici pubbliche — i
segreti nei contesti agente trapelano. I probe federati must
applicare protezioni SSRF (nessun IP letterale, nessun hostname interno, redirect/timeout
limitati) e uno User-Agent identificativo. Le superfici admin/health
must richiedere controlli di capability della piattaforma. Le
implementazioni must not chiamare servizi di terze parti dal server
del merchant come effetto collaterale del servire letture del catalogo.
10. Changelog della specifica
| Versione | Data | Note |
|---|---|---|
ARC/1.0 | 2026-06-10 | Prima release stabile. Codifica il contratto spedito da KaliCart Bridge 1.0.76: tre segnali di discovery, documento di discovery, cinque endpoint del catalogo, oggetto prodotto con quarantena e prontezza all'acquisto, modello di consenso opt-out per l'indicizzazione federata, sessioni di checkout opzionali, interop UCP. |
Feedback e report di implementazione: GitHub issues.