Describe what a Service offers

Choose what one Offering represents

An Offering is a Service-defined resource that can represent a physical product, digital service, piece of content, reservation, unit of capacity, or another available item. ODP gives these resources a common discovery structure without prescribing one commercial data model.

• Separate Offerings: create a separate Offering when a choice should be independently discoverable or has its own details, price, availability, or Actions
• Attributes: describe persistent characteristics of one Offering with typed Service-defined data
• Action input: accept request-specific choices, such as size or output format, when the caller invokes an Action

Choose a unit that has independent meaning in the Service's domain. An Offering is not always a product, and related Offerings do not necessarily form a product-and-variant hierarchy.

Publish a useful Full Offering

Every Full Offering contains odp_version, id, and name. Add only the optional fields that describe, present, organize, compare, or act upon that resource.

{
  "odp_version": "1.0",
  "id": "web-search",
  "name": "Web search",
  "description": "Search the web and return cited results.",
  "images": [
    {
      "src": "/images/offerings/web-search.png",
      "alt": "Web search"
    }
  ],
  "web_url": "/offerings/web-search",
  "collection_ids": [
    "research-tools"
  ],
  "price": {
    "type": "fixed",
    "amount": "0.01",
    "currency": "USD"
  },
  "schema": {
    "url": "/schemas/web-search.json"
  },
  "attributes": {
    "result_format": "json",
    "max_results": 100
  }
}

Make the Offering recognizable

An Offering's identity combines the Service origin, the Offering resource type, and its local id. Keep that ID stable while the same resource changes its name, description, imagery, price summary, or other mutable details.

• Description: explain what the Offering provides and what distinguishes it from nearby choices
• Images: place the primary image first and reserve additional images for the Full Offering when a terse result needs only a thumbnail
• Browser link: use web_url for an optional human-facing page without replacing the machine-readable Offering
• Language: identify localized representations through language metadata rather than mixing translations into one field

An origin-relative image or browser path resolves within the Offering Service. Use an absolute HTTPS URL when the resource intentionally lives at another origin.

Use terse results and full retrieval

Offering lists and searches return terse representations by default so Agents can navigate and compare a bounded page. Individual retrieval returns a Full Offering by default with every field the Service makes available for that request.

{
  "odp_version": "1.0",
  "items": [
    {
      "id": "web-search",
      "name": "Web search",
      "price": {
        "type": "fixed",
        "amount": "0.01",
        "currency": "USD"
      },
      "detail_fields": [
        "/description",
        "/images",
        "/web_url",
        "/collection_ids",
        "/schema",
        "/attributes",
        "/actions"
      ]
    }
  ]
}

• Required terse fields: always include id and name
• Useful summaries: include optional fields such as the primary image or Price Preview when they improve comparison
• Full retrieval: retrieve the same resource rather than treating its full form as another Offering
• Omitted details: use detail_fields when a terse result can exhaustively identify the field subtrees available in full retrieval

A terse Offering never contains actions. Retrieve the Full Offering before deciding which subsequent operation to use.

Interpret omitted fields correctly

A Full Offering omits an optional field when the field does not apply, the Service does not have it, or the current request cannot access it. Do not use empty attributes, collection_ids, or actions as placeholders for unused capabilities.

Keep specialized data typed

Put Service-defined Offering data in a non-empty attributes object and identify its JSON Schema Draft 2020-12 contract through schema.url. The schema describes the complete attributes object and can be shared by multiple Offerings.

Do not move specialized values into representation-specific summary containers. A field included in a terse representation keeps the same type and meaning it has in the Full Offering. See Custom attributes for schema design and validation.

Preview price without promising settlement

The optional price object is a discovery-time summary. It can communicate that an Offering is free, has a fixed price, falls within a range, starts at an amount, uses a metered rate, or requires a later quote.

See Pricing and payments for each preview type and the boundary between discovery and payment.

Advertise available Actions

A Full Offering can contain Actions that describe operations available after discovery. Advertising an Action tells the Agent what can be attempted; it does not invoke the operation, guarantee success, or replace the target endpoint's authentication and payment requirements.

Keep Actions out of terse Offerings, and omit actions when none apply. See Actions for identifiers, targets, methods, input schemas, and resolution.

Connect Offerings to Collections

collection_ids records direct membership. Omit it when an Offering belongs to no Collection; otherwise provide a non-empty array of unique Collection identifiers visible under the same access context.

A search can constrain results to direct members or explicitly include descendants. That query-time expansion does not change the Offering's published membership. See Collections for hierarchy and inverse membership rules.

Choose the Offering operation

Next steps