EmbedLink Standard

EmbedLink Standard

This document describes a suggested standard technique for specifying content with which other sites or user agents may generate a rich link to a specific web page. For instance, when a user of a social networking site posts a link to a web page, that site may use this standard to try to extract a useful summary of the linked page including an image or video to represent the page, the title of the page, etc. This standard is intended to replace the earlier oEmbed standard (which is unaffiliated with this standard) in order to overcome some problems with oEmbed.

oEmbed Considered Harmful

Okay, that's a cliche, and definitely overstates it a bit. But honestly, I liked oEmbed when I first saw it, but the more I thought about it and used it, the more concerns I had about it.

I have four main objections to oEmbed:

  1. It requires the server to support an additional resource, and a dynamic one, at that. To serve oEmbed content for photo, video, or rich type, the server must respect the client-requested maxwidth and maxheight query parameters which means it must dynamically size the content, or else dynamically generate error responses.
  2. It requires a separate fetch to get a relatively small amount of meta data. I'm not sure if this would have made better sence at an earlier time in history, but with modern networks, there's a very small penalty for including the meta data directly in the parent document (much of which is likely to already be there, such as author and description), and a comparatively large penalty for having to do a separate fetch.
  3. The use of the JSON format encourages people to do a Javascript eval() on code from an unknown and untrusted source, which is a major security risk. Obviously there are other ways to handle the JSON data, but this would be the easiest and most obvious way to handle it in many instances.
  4. In a similar vein, the html property (for the video and rich oEmbed types) encourages people to include raw HTML from an unknown and untrusted source directly in their page, which is another major security risk. Once again, there are many ways to handle this better: you can parse the content and strip out potentially dangerous content, but that's a significant amount of work, and forces a trade off between how safe it is and how rich the HTML really is. You can also put the supplied HTML in an iframe served from a different host name (as suggested by oEmbed), but that is significantly more work (most likely requires storage on the server) and may not even be possible in all cases (for instance, if the site only has one host name, or has no host name, only an IP).

With HTML5, I believe that oEmbed is obsolete: a handful of link elements in the head with some new rel values, along with conventional elements such as title and meta, should be sufficient.

To review, the four types ("varieties") of embeddable resources that oEmbed supports are: photo, video, link, and rich. The link is only used to provide additional meta data, but I argue that any meta data supplied by an oEmbed response can more easily be included directly in the head of the source document using meta tags.

The rich type is used to serve arbitrary HTML content. I would argue that this is basically a terrible idea in the first place. It uses the html property of the oembed data, which, as mentioned, encourages clients to do very insecure things. The purpose of the rich type would be to generate your own "thumbnail" of your page and provide that for other people to embed in their sites. Most consumers won't want to use your thumbnail because it doesn't match their look and feel, and it takes quite a bit of work to do it securely. The only secure way to do it is to put the provided html content in an iframe, served from a different host, so if you really want to use this mechanism, why not just provide a URL and point an iframe directly at it? This ensures that the consumer can't choose to do the most unsafe thing of putting the providers html directly on their page.

The photo and video are used to specify an image or video to which the source page is closely related (for instance, the main video of interest on a video streaming site, or a headline photo on an article). Such resources should be able to be provided as URLs anyway, there's no need to use the html property of the oembed structure. The only reason to use rich HTML content to provide a video is so that adaptive content can be used to choose the best size and media type based on the browser, for instance. To elliminate the security risks and complications of providing HTML content directly, the adaptiveness can be offloaded to the consumer by providing multiple URLs and specfying, for each, the size and type, similar to how the rel="shortcut icon" link is currently used in HTML5. Additionally, providers can still use a specific keyword to designate a URL to which query parameters can be appended to specify the maxwidth and maxheight values, if the provider wants to support it.

Summary of Resource Types

The following four sections summarize how the EmbedLink standard handles each of the four types of resources supported by oEmbed.


The oEmbed video type can be replaced with a <link> element in the document head, with the rel attribute set to "video" and the href attribute set to the URL of a video to be provided. The sizes and type attribute should be used identically to how they are used for rel="shortcut icon" (in HTML5): the sizes attribute is a space separated list of sizes for which the specified URL can be used. For videos, there will most likely only be one size per URL, unless the video format is scalable or some sort of container which can hold multiple sizes. Additionally, the attribute "any" (part of the HTML5 spec) can be used. Per this specification, the "any" value should be used to indicate that the URL given in the href attribute supports the "maxwidth" and "maxheight" query parameters, as specified in the oEmbed format. If "any" is used, no other value should be used for the sizes attribute of the link. The sizes attribute should be always be used for EmbedLink resources. More details on both the sizes and type attribute are below.


The oEmbed photo type can be suported almost identically to the video type, but with a rel attribute set to "image".


The oEmbed rich type can be supported similarly to the video and photo types, using a <link> element in the document head, with the rel attribute set to "rich-embed". The sizes and type attributes can be used identically to how they are used for Video and Phot types.


The oEmbed link type is not needed; its only purpose is to use the oEmbed structure to provide additional meta data. This meta data can be included inline in the document using <meta> and other conventional elements in the document head, as described below.

All oEmbed Response Parameters

All the necessary oEmbed response parameters (i.e., meta data) are either unecessary or can be supplied using the following mechanisms.

The oembed type parameter is replaced by the specified values of the rel attribute on the <link> element for the resource: "video", "image", or "rich-embed".
Is not required, since we're not using the oEmbed format.
The title describes the supplied resource specifically. Typically, this should be the same as the document title, but if you want to supply a different title for the specific resource, you can use the HTML title attribute on the <link> element.
Use the conventional mechanisms to specify the author of the parent document. This should apply to the resource. The suggested mechanism is using a <meta> element with name attribute set to "author", which is part of the HTML5 specification.
Use conventional mechanisms to specify the author URL for the parent document. The suggested mechanism is using a <link> element with the rel attribute set to "author", which is part of the HTML5 specification.
Use conventional mechanisms to specify the name of the site from which the resource is referenced. For instance, the <title> element, or a <meta> element with name attribute set to "application-name". A different <meta> scheme can also be used.
This should simply be the URL from which the resource is linked, so it is not generally needed. If it is, it is most likely because you want to specify a more canonical URL, in which case you can use a <link> element with the rel attribute set to "canonical", or a similar mechanism.
Use normal HTTP cache directives for the served resource.

This is needed for video and rich types: for photo type, the image itself (or a specific size of it) is the thumbnail. For video and rich types, a thumbnail can be specified by using another <link> element with rel set to "video" or "rich-embed", respectively, and the type set to some image mime-type. It is highly recommended that mime-type for thumbnails begins with "image/" so it's easier to identify as such. As with the video or rich content itself, multiple thumbnails in different mime-types and sizes can be supplied using the sizes and type attribute as previously discussed.

Additionally, class attribute of the <link> element SHOULD include the value "thumbnail" to indicate that the resource is a thumbnail for another resource. This is less important for video types, but should still be honored. For rich-embed types, the mime-type for for the resource can be anything, including an image type, so the use of the "thumbnail" class can help consumers identitify which resource you intended to be used as a thumbnail. Consumers SHOULD take this into consideration, but are free to choose any of the specified resources of any type or size, both for the thumbnail and for the main embedded content (if there's even a difference).

thumbnail_width and thumbnail_height
The size of the thumbnail image is specified using the sizes attribute of the <link> element, same as for the nominal (non-thumbnail) resources.


Maximum COnstrained Size

This standard makes use of the concept of a maximum constrained size for resources, given a constraining size, specified as a maximumwidth and maximumheight. The maximum constrained size is the largest size which honors both the original aspect ratio and the specified constraining size. In otherwords, neither dimension will exceed the corresponding dimension of the costraining size, one dimension will be exactly equal to the corresponding dimension of the constraining size, and the aspect ratio will be the same as for the original resource (not necessarily the same as the constraining size).

Specifying the Sizes of a resoruce

The sizes attribute of a <link> element MUST always specify an exact size of the served resource. If the resource is a container that contains a specific set of items at particular sizes, they SHOULD each be listed. Sizes which the resource does not contain MUST NOT be listed.

If the provider wishes to do dynamic scaling of the resource on request, they should include the value "any" in the list of supported sizes for the resource. The mechanism for scaling is similar to that specified by oEmbed: the consumer should specify a maxwidth and maxheight query parameter attached directly to the specified URL when fetching the resource, and the served resource must honor those constraints. An additional constraint over the oEmbed mechanism is that providers SHOULD serve up a resource whose size is the maximum constrained size of the original resource given the requested constraining size. The consumer MAY assume that this is the case and render the resource accordingly.

In other words, do not use the "any" size mechanism if you only plan to pick the closest match from a set of values: if this is the case, then simply provide each of those sizes as their own resource using separate <link> elements. Only use the "any" mechanism if you will perform arbitrary scaling as requested by the consumer.

It is recommended that if the "any" size is specified, the URL which is given should already contain a query string which the provider can expect to be included in all requests for the resource (it could be a dummy query that is simply ignored by the provider). This accounts for consumers which incorrectly assume that there is a query string and append their own maxwidth and maxheight parameters directly to it using the '&' character. Consumers SHOULD check the provided URL to determine if there is a query string or not and use the correct syntax for appending parameters (i.e., a '?' before the first parameter if there is not already a query string, and a '&' if there is already a query string).

If the "any" size is specified, the provider MUST also specify a specific default numerical size for the resource. This MUST be the size that will be served if neither the maxwidth nor the maxheight parameter is specified in the request URL. Additionally, it specifies to the consumer the aspect ratio for the resource so that they can determine a maximum constrained size for the resource.

Resources which are abritrarily scalable (like SVG or other vector based graphics) MUST still specify a valid non-empty value for the sizes attribute. Such a resource should include in its list of sizes a maximum constrained size for the resource corresponding to each of the following standard constraining sizes: (12x12), 16x16, 24x24, 32x32, (48x48), 64x64, 128x128, (256x256), 512x512, 1024x1024, 2048x2048 (Those shown in paranethesis are strongly encouraged but are considered less important than the others). This allows some consumers to use the item for a variety of common sizes without knowing that it is scalable (for instance, if they are relying on a separate agent to actually render the resource, such as a web browser). Any additional valid sizes for the resource may also be included.

Scalable resources SHOULD also include the "any" size to suggest that the consumer can use the resource for any constraining size. Since the resource is scalable, the provider can simply ignore the maxwidth and maxheight parameters and serve the same resource for any request. Once again, this allows consumers to use the resource for any size they want without realizing that it is scalable.

Choosing a Resource

When multiple resources of the same type are supplied, the consumer can use the type and sizes attributes to determine which one best suits their needs. The following general process is RECOMMENDED: For each link of the appropriate type (video, image, or rich-embed), the first step is to score the resource based on it's mime type. You can use the actual mime-type if you want to fetch the resource, or just use the type hinted in the type attribute. If the mime-type is something you can't or won't handle, then just reject the resource as an option. Otherwise, score it based on your preference for the mime-type. For instance, some mime-types may tend to be better quality, some may tend to take up more space, etc. You will need to prioritize based on your aims. It is recommended to score on a scale from 0 to 1 with 1 being the most preferred type.

Next, score the resource based on size. If the resource lists a size which exactly matches what you want, give it a score of 1. If the size is smaller than what you want, score it based on how close it is to what you want. Likewise, if it is larger than what you want and you are able to scale the resource (based on it's mime type and your abilities to handle it), you can likewise score it based on how close it is to your desired size. If you are unable to scale it and it only supports sizes that are larger than you want, then you can reject it outright. Note that depending on your aims, you may choose to favor either images that are smaller than desired or images that are larger than desired but can be scaled. For instance, larger images that are scaled down are necessarily generally in the process (unless they are vector graphics). On the other hand, they will provide a larger image.

If the resource includes the "any" size and you are able to support adding query parameters when fetching it, than it can support any size.

You may also wish to include the aspect ratio in your size scoring if you prefer a particular aspect ratio.

Lastly, you may wish to score the scheme/protocol of the resource's URL. For instance, if it is a scheme you are unable to support, you will need to reject the resource. You may also prefer https or other cryptographically secured schemes over unsecured schemes, and may even reject any unsecured schemes all together.

Once you have all of your individual component scores for a resource, do a weighted sum of the scores, weighted according to how important each component is to you. For instance, you may have a slight preference for certain mime-types, but the size is what's really important, so the size score would be weighted more heavily. You can use successive binary weights if you want to make one score trump the others entirely. For instance, if you want to select a resource first of all based on scheme, and then only care about the size to break ties, and then only care about the mime-type to break further ties, then you would weight your scheme score by 0.5, and then add 0.5 to the weighted value, so that it has a value in [0.5, 1]. You would weight your size score by 0.25, but add 0.25, so it has a value in [0.25, 0.5], and then weight your scheme score by 0.25 with no additional offset, so it has a value in [0, 0.25]. When you add them all up, no size score will cause a resource with a worse scheme score to win out, for instance.

Once you've scored each resource, simply select the one with the highest score.

Misc. Meta

The following mechanism can be used to associate miscellaneous meta data with a resource: the <link> element should have a unique identifier specified by its id attribute. Any number of <meta> element can be included in the document whose name starts with the same identifier string, followed by a colon, followed by any other string. The string following the colon in the name identifies the meta data being specified, and the <meta> elements content attribute gives the value of the meta data.

The meta data identifiers (the string following the colon) SHOULD start with "X-" to indicate that the label is non-standard. In the future, certain meta data may be standardized in which case those names will not include the leading "X-" and will become reserved. Perfixing your strings with "X-" now ensures you will not overlap with reserved values in the future.

Suppliers SHOULD NOT use this mechanism to specify any meta data which can be provided in some other way as described in the specification. This includes the geometric size of the resource (specified with the <link> element's sizes attribute), the mime-type (specified with the <link> element's type attribute), the title of the resource (the title attribute of the <link>), etc.

Consumers SHOULD NOT use this misc. meta data to determine which resource to select.