Skip to content

Add local-business storefront catalog example (SMB as an agentic resource)#60

Open
jrajaratnam wants to merge 1 commit into
ards-project:mainfrom
ValariSolutions:add-local-business-example
Open

Add local-business storefront catalog example (SMB as an agentic resource)#60
jrajaratnam wants to merge 1 commit into
ards-project:mainfrom
ValariSolutions:add-local-business-example

Conversation

@jrajaratnam

Copy link
Copy Markdown

What

Adds conformance/examples/local-business/local-business-catalog.json — a worked
ai-catalog.json for a fictional small local business (a plumbing company at the
RFC 2606 domain bobs-plumbing.example), following the pattern established by the
FDA Drug NDC Directory example (#46).

Why a local-business example

The existing examples cover an enterprise API (FDA, #46) and generic/basic
catalogs. The long tail of agentic resources is neither: it's the millions of
small businesses whose "agent surface" is a conversational assistant plus a
handful of storefront tools (availability, quotes, hours). This example shows
what publishing that surface looks like end to end:

  • One business, two artifact types — an application/a2a-agent-card+json
    entry (conversational agent, referenced via url at the registered
    /.well-known/agent-card.json path) and an application/mcp-server-card+json
    entry (structured storefront tools, embedded via data) — exercising both
    halves of strict value-or-reference (§3.4).
  • SMB-grade trust — a trustManifest whose attestations are the local
    equivalents of enterprise compliance: a state contractor license lookup and a
    liability-insurance certificate (attestation type treated as an open set,
    as in Add FDA Drug NDC Directory API catalog example #46).
  • Schema.org-vocabulary metadata (§4.5) — schemaOrgType, address,
    telephone, service area, opening hours — the filter dimensions a registry
    needs for "find me a plumber open now near Minneapolis"-class queries.
  • RFC 2606 namingbobs-plumbing.example per ADR-0003.

Conformance

Passes conformance/bin/conformance-test manifest with strict JSON Schema
validation enabled (0 errors, 0 warnings): URN format, value-or-reference, and
representativeQueries sizing all green.

Note on type + mediaType

Each entry emits the IANA media type under both type and mediaType,
with identical values. The base ai-catalog spec and this spec's examples have
not fully converged on one property name (see #43 and #27, both of which emit
the pair for cross-spec compatibility). The schema tolerates the extra
property, and publishers like us are already dual-emitting in production so
consumers of either spelling can parse the catalogs. Happy to collapse this
example to a single field the moment the WG settles the canonical name — which
would be great to see happen before the 1.0 media-type freeze.

@jrajaratnam

Copy link
Copy Markdown
Author

Cross-referencing the two open issues this example touches:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant