oEmbed interpretation

oEmbed is a protocol many external sites publish (YouTube, Vimeo, SoundCloud, Spotify, Flickr, and others): given a URL, a provider's oEmbed endpoint returns JSON describing an embeddable representation of it — a title, author, thumbnail, dimensions, and an html/rich embed snippet.

This document defines how Elonn turns a URL a member encounters — pasted into a message, followed as a link, found embedded in a page — into canonical data when that URL belongs to a provider Elonn recognizes. It is a sibling to html.md: both are format interpretation (decision.format_interpretation_owned_by_consuming_service_20260909), owned by the consuming Service (Find), built as reusable interpreter components — not a Provider (CLAUDE.md's architectural sense; an oEmbed *provider*, in this document, is the external site, the ordinary industry term — not an Elonn Provider adapting an external system to a Service).

The core invariant

Provider-supplied data may describe an Object, but it never determines what Elonn executes.

An oEmbed response is untrusted external content. It may claim any type. It may carry an html field containing an arbitrary third-party embed — a script tag, an iframe pointed anywhere, a widget. None of that is read for the purpose of deciding what Elonn instantiates. What Elonn instantiates is decided once, in advance, per provider, by Elonn — recorded in the provider table below — and never by the response itself.

Resolution: the provider table

Elonn holds its own table of recognized oEmbed providers. A URL is checked against this table before anything is fetched. Two outcomes:

• No match. The URL falls through unchanged to the generic path (html.md): fetch the page, interpret by content type.
• A match. Elonn extracts that provider's id from the URL itself — using a pattern Elonn wrote for that provider, applied to the member-supplied URL, never to anything the provider returns. What happens next depends on whether Elonn has vetted an embed target for this provider (below).

Resolution is provider-table-first by design (decision.oembed_provider_table_execution_boundary_20260912). A second resolution stage — following a page's own <link rel="alternate" type="application/json+oembed"> discovery tag when the table misses — is anticipated but deliberately not built yet. If it is built later, the same invariant holds without modification: a discovered endpoint may only ever supply metadata (below); a provider still needs a table entry with a vetted embed target to be granted embed capability. Discovery finds facts; it does not grant execution.

The embed target: Elonn-authored, not provider-supplied

For a provider Elonn has vetted, the table entry carries an embed URL template — a string Elonn wrote, with a placeholder for the id. The executable embed URL is the result of substituting the id (extracted from the member's URL, per above) into that template. Nothing from the provider's oEmbed response participates in constructing it.

input URL:
https://www.youtube.com/watch?v=abc123

Elonn extraction (pattern Elonn wrote, applied to the URL above):
id = abc123

Elonn-authored template (in the provider table):
https://www.youtube-nocookie.com/embed/{id}

canonical embed target:
https://www.youtube-nocookie.com/embed/abc123

This is deliberately narrower than "extract a src from the provider's html field and trust that." An iframe src pulled out of provider-returned HTML is still a URL the provider chose, on demand, at response time — the provider retains a lever over what gets instantiated. An Elonn-authored template keyed off an id Elonn itself parsed from the member's own URL has no such lever: the provider cannot cause Elonn to embed anything the provider didn't already reveal by simply being the host of that URL shape.

A provider with no vetted embed target may still have a table entry — for its oEmbed metadata endpoint alone (below) — without ever being granted embed capability. This is expected to be permanent for providers whose only embed path is an opaque widget-script blob (a tweet, an Instagram post): they degrade to a plain link representation rather than being reproduced as a bespoke embed. A richer representation for such a provider is a deliberate, separately vetted design decision, not a fallback path this document defines.

The oEmbed response: metadata only

When the matched provider has an oEmbed endpoint configured, Elonn fetches it — using the same retrieval discipline as any other external fetch (https-only, bounded timeout, bounded size). This fetch is best-effort: its absence or failure does not change whether the URL gets an embed target, only how much descriptive metadata the resulting Object carries.

The response splits three ways:

• Descriptive fields (title, author_name, provider_name, width, height) become descriptive canonical properties on the Object — title, aspect ratio, author.
• thumbnail_url (and thumbnail_width/thumbnail_height) becomes a Resource exactly the way any other external image URL becomes a Resource. It receives no special trust for having arrived via oEmbed.
• html, rich, and type are never read. type is not consulted even as a hint for which canonical Object type to produce — that decision was already made by the provider table, before the response existed. A response claiming "type": "video" and carrying a hostile html iframe does not make the URL a video Object, and grants the named origin nothing, if the provider table gave that provider no embed target.

Resulting canonical shapes

A provider-table match with an embed target produces a video Object:

Object
type: video
content:
title: <from oEmbed metadata, else "Video">
source: <the Elonn-constructed embed target>
source_url: <the original URL>
provider: <provider name, from the table>
provider_id: <the extracted id>
aspect: <from oEmbed width/height, else 16:9>
embeddable: true
playback: external
resource: <id of a Resource {kind: embed, source: the embed target}>
author: <from oEmbed metadata, when present>
thumbnail: <id of an image Resource, when a thumbnail was returned>

A provider-table match with no embed target produces a link Object instead — metadata and provenance only, no embeddable resource:

Object
type: link
content:
title: <from oEmbed metadata, else the provider name>
source_url: <the original URL>
provider: <provider name, from the table>
author: <from oEmbed metadata, when present>
source_resource: <id of a source-provenance Resource>
thumbnail: <id of an image Resource, when a thumbnail was returned>

Both shapes carry no Placement, for the same reason HTML interpretation never does (html.md, Placement invariant): World and the Runtime decide placement. Both are content-derived from the provider name and extracted id, not from the page the member happened to find the link on or the specific URL variant (watch page, short link, embed link) they pasted — the same video reached two different ways resolves to the same Object id, which is what lets it be shared: forwarding a reference to it, or reopening it from a different pasted form of the same URL, points at the one canonical Object.

Relationship to HTML interpretation

html.md's media-and-embedded-resources section documents an <iframe> found while interpreting a page being promoted to a video Object when it is a recognized provider embed. That promotion uses this same provider table: an iframe src is matched against it exactly as a bare pasted URL is, so a YouTube video embedded on a page and the same YouTube video pasted directly into a message resolve to the same Object. html.md remains the authority on document/page structure; this document is the authority on provider recognition and the execution boundary, for either call site.

Pipeline

Original URL
|
v
Provider table match
|
+-- no ----------------------> existing HTML/PDF/etc path (html.md)
|
yes
|
+--> Elonn extracts the provider id from the URL (not from provider content)
|
+--> Elonn constructs the oEmbed endpoint request (if the provider has one)
|
v
oEmbed response
|
+--> metadata ----------------> descriptive canonical properties
|
+--> thumbnail/photo URL -----> normal external Resource handling
|
+--> html ---------------------> NEVER interpreted/rendered
|
+--> type ---------------------> never consulted
|
v
Does Elonn's provider table entry
have an embed URL template?
|
+-- yes --> Elonn constructs the embed URL --> video Object
|
+-- no ---> link Object (metadata only)