Present a recognizable Service

Separate Service branding, resource images, and language

ODP provides distinct presentation fields because a Service mark, an Offering image, and translated metadata answer different questions. Keeping those concerns separate lets an Agent select the correct visual and language without interpreting filenames or presentation text.

• Branding: a square icon and horizontal logo identify the Service across directories, applications, and compact interfaces
• Resource images: ordered images depict a particular Collection or Offering rather than the Service as a whole
• Localization: language metadata and HTTP negotiation identify which translated representation an Agent received

Publish both Service marks

branding is optional, but when present it contains both icon and logo. Each mark requires a Resource Reference in src and can include a type hint.

{
  "branding": {
    "icon": {
      "src": "/images/icon.svg",
      "type": "image/svg+xml"
    },
    "logo": {
      "src": "/images/logo.svg",
      "type": "image/svg+xml"
    }
  }
}

Branding supports PNG, WebP, and SVG. The optional type is a pre-retrieval hint and is especially useful when the URL does not reveal the format. The successful response remains authoritative and must match an advertised type.

Preserve the original artwork

A client that normalizes branding fits and centers the source within the appropriate canvas. It preserves the aspect ratio and never crops or stretches the artwork merely to fill the target dimensions.

Services provide enough source resolution to avoid upscaling. An SVG source must provide positive intrinsic dimensions or positive view-box dimensions so a client can determine its aspect ratio.

Add images to Collections and Offerings

A Collection or Offering can include images, an ordered array containing one to 16 image descriptors. These images depict the catalog resource; they do not replace the Service icon or logo.

{
  "images": [
    {
      "src": "/images/offerings/web-search.webp",
      "alt": "Search results displayed in a research workspace",
      "width": 1200,
      "height": 800,
      "type": "image/webp"
    },
    {
      "src": "https://cdn.example.com/images/source-details.jpg",
      "alt": "Source details with citations",
      "width": 1200,
      "height": 800,
      "type": "image/jpeg"
    }
  ]
}

When type is omitted, an Agent determines the image format from the response Content-Type. A filename extension can help a publisher choose whether to advertise a hint, but it is not authoritative.

Put the primary image first

The first descriptor identifies the primary image. Choose the image that can represent the Collection or Offering when an Agent has room to display only one visual.

A Terse Representation can include only that primary image even when the Full Representation contains more. The descriptor itself remains complete; a Service does not partially serialize its fields to make a smaller summary.

Retrieve images without credentials

Branding and resource images are public supporting resources. An Agent never attaches AEP credentials, payment credentials, cookies, or authorization fields copied from another request when retrieving them.

• Resolve: resolve an origin-relative src against the Service origin, not the containing representation path
• Verify: treat the response Content-Type as authoritative and reject a mismatched advertised type
• Isolate: sanitize and safely isolate displayed SVG, or rasterize it before presentation
• Bound: apply redirect, network-address, decoding, rendering, and resource limits to untrusted image content

A branding response is limited to 1,048,576 bytes and five redirects. For Collection and Offering imagery, clients apply their own bounded image policy. An invalid resource image makes only that image unusable; the containing resource remains usable.

Declare the representation language

Every Service Document requires language and localizations, including a Service published in only one language. language identifies the current representation, while localizations lists the available Service metadata languages and always includes the current language.

{
  "language": "en",
  "localizations": ["en", "es", "fr"]
}

Both fields use RFC 5646 language tags. The list contains one to 16 unique tags; a single-language Service uses a list such as ["en"]. Service metadata does not promise that every Collection or Offering is available in the same languages.

Select a localized representation

An Agent expresses language preferences with Accept-Language. A Service with multiple representations applies RFC 4647 Lookup and returns the best available match.

Accept-Language: fr-CA, fr;q=0.9, en;q=0.7

Content-Language: fr
Vary: Accept-Language

Inherit language from the nearest context

Collections and Offerings can declare their own language metadata. They omit it when they use the language already established by the containing response or Service Document.

Content-Language identifies the language actually selected for the HTTP representation. It does not change the stable Resource Identity of a Collection or Offering.

Keep presentation metadata dependable

• Service branding: publish both marks together and use each in the canvas for which it was designed
• Resource imagery: put the strongest representative image first and describe meaningful images with localized alternative text
• Public retrieval: resolve each reference independently and keep credentials out of every image request
• Language variants: negotiate with HTTP headers, return the selected language, and keep cache validators variant-specific

Next steps