Skip to content
AX Framework
Discovery pattern

Resource Description

Describe each important resource with typed fields, stable identifiers, and explicit units.

Problem

Product pages, listings, and records are designed for visual scanning. Agents extracting facts from them misread prices, confuse variants, and miss conditions shown only visually.

Context

Use this pattern when:

  • Agents need to compare, filter, or reason about your content: products, listings, rooms, plans, documents.
  • Some decision-critical information is currently conveyed by layout, color, or images.

Recommended solution

Publish a structured description of each resource alongside its human page. Use established vocabularies such as schema.org JSON-LD for public content, and a typed JSON representation for richer, application-specific data.

Give each resource a stable identifier and canonical URL, and make every decision-critical fact explicit: units, currencies, time zones, conditions.

  1. 01Identify decision-critical attributes for each resource type.
  2. 02Embed schema.org JSON-LD for public, indexable facts.
  3. 03Offer a richer JSON representation via content negotiation or an alternate link.
  4. 04Generate both from the same data as the visible page.

Interaction diagram

Interaction diagram for Resource Description. 1. AI agent to Product · AX layer: GET /p/trail-runner. 2. Product · AX layer to AI agent: HTML + JSON-LD. 3. AI agent to Product · AX layer: GET /p/trail-runner (Accept: json). 4. Product · AX layer to AI agent: variants, stock, delivery.AI agentProduct · AX layerGET /p/trail-runner1HTML + JSON-LD2GET /p/trail-runner (Accept: json)3variants, stock, delivery4
request response internal step

Example implementation

Illustrative example

Examples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.

Embedded JSON-LD (schema.org)html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "sku": "TRAIL-RUNNER-42-BLK",
  "name": "Trail Runner — Black, EU 42",
  "offers": {
    "@type": "Offer",
    "price": "129.00",
    "priceCurrency": "EUR",
    "availability": "https://schema.org/InStock"
  }
}
</script>

Accessibility and security

Accessibility

  • Structured data complements accessible markup; it does not replace it. Use semantic HTML and ARIA where needed so assistive technology and agents both benefit.
  • Text alternatives for images that carry information (size charts, badges) help screen reader users and agents alike.

Security

  • Do not expose internal fields (cost price, supplier, internal notes) in public descriptions.
  • Rate-limit structured endpoints the same way as HTML pages.

Applies the principles Structured Context and Minimal Ambiguity.