Expose referenced asset metadata in Assets queries

[kof]

Problem

Markdown frontmatter can reference an Asset Manager image:

featureImage: "./assets/article-image.png"

Assets queries currently return this field as a path-derived URL string, so the referenced image metadata—especially its Asset Manager description—is unavailable. Using the description as image alt text requires a second query and a brittle filename-based join.

Desired outcome

Allow Assets queries to resolve selected asset-reference fields into structured asset data:

post.properties.featureImage.src
post.properties.featureImage.description
post.properties.featureImage.width
post.properties.featureImage.height

This should work wherever local asset references appear, including nested objects and arrays.

Scope and constraints

• Asset resolution is opt-in so existing queries continue returning strings.
• Users can select only the required asset fields.
• Supported metadata includes id, src, name, description, mimeType, width, and height.
• Resolve relative paths from the containing Markdown or JSON document.
• Support nested paths such as:
  • properties.featureImage
  • properties.socialImage
  • properties.showcase.images[].src
• External URLs remain usable and do not fail the query.
• Missing assets return a predictable unresolved value and diagnostic.
• Expanded metadata counts toward query size diagnostics.
• Query preview, generated preview, published runtime, and static export return the same shape.

The final query syntax is an implementation decision, but resolution must be explicit and field-selective.

Webstudio blog usage

Update the blog query to resolve properties.featureImage and bind the Image component as follows:

src: post.properties.featureImage.src
alt: post.properties.featureImage.description ?? post.properties.title

This removes empty alt attributes without duplicating descriptions in Markdown or loading and joining every image through another resource.

Acceptance criteria

• Existing queries remain backward compatible.
• An opted-in query returns the referenced image’s Asset Manager description.
• Changing an asset description updates rendered alt text without editing Markdown.
• Blog listing images render non-empty alt attributes.
• Missing descriptions fall back to the article title.
• No second image query or filename matching is required.
• Tests cover local references, nested references, external URLs, missing assets, missing descriptions, and output-size accounting.
• Content Engine documentation explains reference resolution and includes an accessible image example.