X. Discovery

OEmbed providers can choose to make their endpoints discoverable by serving a file called oembed.xml in the root of their domain. For instance, Flickr could provider a discovery file at flickr.com/oembed.xml. The contents of the file should be as follows:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed>
	<config ttl="24" />
	<match pattern="{URL Pattern}" endpoint="{Endpoint URL}" type="{Type}" />
	<match pattern="{URL Pattern}" endpoint="{Endpoint URL}" type="{Type}" />
</oembed>

The order of the different elements does not matter, except the relative position of any <match> elements. Consumers should test URLs against <match> rules from top to bottom.

The <config> element is optional. The ttl (Time-To-Live) property specifies a suggested cache time for the configuration, in hours. Consumers may choose to ignore this, however, and cache the configuration for as long as they deem appropriate. A TTL of 7 days is recommended for either oembed.xml files that don't contain a TTL, or oembed.xml files that return a 404 response. That is to say, consumers should cache the non-existance of a oembed.xml file for 7 days.

One or more <match> elements contain the URL pattern to API Endpoint mappings. The URL pattern should not include the scheme or domain - the scheme (HTTP or HTTPS) and domain are inferred from the URL to the XML file itself. The pattern and should start with a forward-slash and may only contain '*' as a wildcard (matching zero or more characters of any kind). The Endpoint URL should include the scheme, which must be HTTP. The Type specifies whether the endpoint expects to be passed a format argument (explicit) or whetherthe format is implied by the Endpoint URL itself (xml or json).

X.1. Example oembed.xml configuration files

Single rule configuration for flickr.com:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed>
	<match pattern="/*" endpoint="http://www.flickr.com/services/oembed/" type="explicit" />
</oembed>

Multi rule configuration for qik.com:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed>
	<match pattern="/video/*" endpoint="http://qik.com/api/oembed.xml" type="xml" />
	<match pattern="/video/*" endpoint="http://qik.com/api/oembed.json" type="json" />
	<config ttl="72" />
</oembed>

X.2. oembed.xml DTD

The following DTD can be used to validate oembed.xml files:

<!ELEMENT oembed (match+,config?)>
<!ELEMENT match EMPTY>
<!ELEMENT config EMPTY>
<!ATTLIST config ttl CDATA "168">
<!ATTLIST match pattern CDATA #REQUIRED>
<!ATTLIST match endpoint CDATA #REQUIRED>
<!ATTLIST match type CDATA #REQUIRED>