Interpret catalog representations

One resource, two representations

Terse and full representations describe the same Collection or Offering. Selecting a representation changes how much information is returned, not the resource's identity or data model.

Select the representation

Every Collection and Offering operation accepts at most one representation query parameter. Its value is terse or full.

The selection applies to page items, not to the page envelope. Repeating the parameter or using another value produces 400 Bad Request. Requesting full items does not increase the Service's page-size or response-size limits.

Preserve field meaning

A field keeps the same name, location, type, and meaning in both representations. Volatile values can differ when the representations are generated at different times, but the contract of the field does not change.

• Omitted fields: a terse representation can leave out complete fields or members of nested objects
• Included values: an included scalar or array is not silently shortened unless that field explicitly defines summary behavior
• Images: a terse resource can include only the primary image even when its full representation contains more
• Actions: a terse Offering omits Actions because invocation details belong to full retrieval

auth_expands: true signals that acceptable Service authentication can expose additional fields. The field is omitted rather than set to false, and it neither promises access nor identifies protected fields.

Understand detail fields

A terse representation can use detail_fields to identify the minimal field subtrees that full retrieval will add. Each entry is a JSON Pointer beginning with a forward slash.

{
  "odp_version": "1.0",
  "items": [
    {
      "id": "research-report",
      "name": "Research report",
      "detail_fields": [
        "/description",
        "/attributes",
        "/actions"
      ]
    }
  ]
}

detail_fields is a non-empty array of at most 32 unique pointers. Each pointer begins with a forward slash, contains no more than 256 printable ASCII characters, and does not use the URI fragment form of a JSON Pointer.

A pointer to an omitted object or array covers its complete subtree. When present, the list is exhaustive; when a complete list would exceed its limits, the Service omits detail_fields rather than returning an incomplete list. Absence therefore makes no claim that the full representation contains nothing more.

Apply version and language context

Every ODP Top-Level Document carried in a request or response declares its own odp_version. An embedded terse item inherits the version of its containing document and does not repeat it. A later individual retrieval is a new top-level response and declares its version independently.

Language metadata follows a similar containing-context rule. The nearest applicable metadata wins in the order Collection or Offering, containing response, then Service Document.

Describe specialized data

An Offering uses attributes for non-empty, Service-defined structured data and schema.url to identify the JSON Schema that describes the complete attributes object. Multiple Offerings can share the same Attribute Schema.

{
  "schema": {
    "url": "/schemas/research-report.json"
  },
  "attributes": {
    "source_count": 20,
    "research_depth": "comprehensive"
  }
}

An Offering with attributes always includes its schema reference. A terse Offering can include partial attributes, but it still references the schema for the complete full object and can identify omitted attribute members through detail_fields. When no specialized data applies, the Service omits both fields.

Retrieve Attribute Schemas

Resolve schema.url against the Offering response URL and retrieve it with GET. Send Accept: application/schema+json and require that media type on a successful response.

• Dialect: the schema declares the JSON Schema Draft 2020-12 meta-schema with $schema
• References: process the references needed to interpret or validate the instance; cross-document references use $ref
• Dynamic references: $dynamicRef is supported only as a fragment beginning with #
• Caching: treat the schema as a mutable HTTP resource and follow its cache directives and validators

An Agent-oriented SDK should resolve and cache the reference graph it needs and return a locally complete schema representation. Its caller should not need additional network requests merely to interpret the Offering.

Validate Full and Terse attributes differently

Every value included in terse attributes still has the type and meaning assigned by the Attribute Schema. Partial does not mean untyped.

Keep schema failures scoped

An unavailable, invalid, unsupported, or non-matching Attribute Schema makes the Offering's attributes uninterpretable. It does not invalidate the Offering's identity, core description, Price Preview, browser link, Collection membership, or Actions.

Next steps