Introduction

The Open Graph protocol enables any web page to become a rich object in a social graph. For instance, this is used on Facebook to allow any web page to have the same functionality as any other object on Facebook.

While many different technologies and schemas exist and could be combined together, there isn't a single technology which provides enough information to richly represent any web page within the social graph. The Open Graph protocol builds on these existing technologies and gives developers one thing to implement. Developer simplicity is a key goal of the Open Graph protocol which has informed many of the technical design decisions.


Basic Metadata

To turn your web pages into graph objects, you need to add basic metadata to your page. We've based the initial version of the protocol on RDFa which means that you'll place additional <meta> tags in the <head> of your web page. The four required properties for every page are:

As an example, the following is the Open Graph protocol markup for The Rock on IMDB:

<html prefix="og: http://ogp.me/ns#">
<head>
<title>The Rock (1996)</title>
<meta property="og:title" content="The Rock" />
<meta property="og:type" content="video.movie" />
<meta property="og:url" content="http://www.imdb.com/title/tt0117500/" />
<meta property="og:image" content="http://ia.media-imdb.com/images/rock.jpg" />
...
</head>
...
</html>

Optional Metadata

The following properties are optional for any object and are generally recommended:

For example (line-break solely for display purposes):

<meta property="og:audio" content="http://example.com/bond/theme.mp3" />
<meta property="og:description" 
  content="Sean Connery found fame and fortune as the
           suave, sophisticated British agent, James Bond." />
<meta property="og:determiner" content="the" />
<meta property="og:locale" content="en_GB" />
<meta property="og:locale:alternate" content="fr_FR" />
<meta property="og:locale:alternate" content="es_ES" />
<meta property="og:site_name" content="IMDb" />
<meta property="og:video" content="http://example.com/bond/trailer.swf" />

The RDF schema (in Turtle) can be found at ogp.me/ns.


Structured Properties

Some properties can have extra metadata attached to them. These are specified in the same way as other metadata with property and content, but the property will have extra :.

The og:image property has some optional structured properties:

A full image example:

<meta property="og:image" content="http://example.com/ogp.jpg" />
<meta property="og:image:secure_url" content="https://secure.example.com/ogp.jpg" />
<meta property="og:image:type" content="image/jpeg" />
<meta property="og:image:width" content="400" />
<meta property="og:image:height" content="300" />

The og:video tag has the identical tags as og:image. Here is an example:

<meta property="og:video" content="http://example.com/movie.swf" />
<meta property="og:video:secure_url" content="https://secure.example.com/movie.swf" />
<meta property="og:video:type" content="application/x-shockwave-flash" />
<meta property="og:video:width" content="400" />
<meta property="og:video:height" content="300" />

The og:audio tag only has the first 3 properties available (since size doesn't make sense for sound):

<meta property="og:audio" content="http://example.com/sound.mp3" />
<meta property="og:audio:secure_url" content="https://secure.example.com/sound.mp3" />
<meta property="og:audio:type" content="audio/mpeg" />

Arrays

If a tag can have multiple values, just put multiple versions of the same <meta> tag on your page. The first tag (from top to bottom) is given preference during conflicts.

<meta property="og:image" content="http://example.com/rock.jpg" />
<meta property="og:image" content="http://example.com/rock2.jpg" />

Put structured properties after you declare their root tag. Whenever another root element is parsed, that structured property is considered to be done and another one is started.

For example:

<meta property="og:image" content="http://example.com/rock.jpg" />
<meta property="og:image:width" content="300" />
<meta property="og:image:height" content="300" />
<meta property="og:image" content="http://example.com/rock2.jpg" />
<meta property="og:image" content="http://example.com/rock3.jpg" />
<meta property="og:image:height" content="1000" />

means there are 3 images on this page, the first image is 300x300, the middle one has unspecified dimensions, and the last one is 1000px tall.


Object Types

In order for your object to be represented within the graph, you need to specify its type. This is done using the og:type property:

<meta property="og:type" content="website" />

When the community agrees on the schema for a type, it is added to the list of global types. All other objects in the type system are CURIEs of the form

<head prefix="my_namespace: http://example.com/ns#">
<meta property="og:type" content="my_namespace:my_type" />

The global types are grouped into verticals. Each vertical has its own namespace. The og:type values for a namespace are always prefixed with the namespace and then a period. This is to reduce confusion with user-defined namespaced types which always have colons in them.

Music

og:type values:

music.song

music.album

music.playlist

music.radio_station

Video

og:type values:

video.movie

video.episode

video.tv_show

A multi-episode TV show. The metadata is identical to video.movie.

video.other

A video that doesn't belong in any other category. The metadata is identical to video.movie.

No Vertical

These are globally defined objects that just don't fit into a vertical but yet are broadly used and agreed upon.

og:type values:

article - Namespace URI: http://ogp.me/ns/article#

book - Namespace URI: http://ogp.me/ns/book#

profile - Namespace URI: http://ogp.me/ns/profile#

website - Namespace URI: http://ogp.me/ns/website#

No additional properties other than the basic ones. Any non-marked up webpage should be treated as og:type website.


Types

The following types are used when defining attributes in Open Graph protocol.

Type Description Literals
Boolean A Boolean represents a true or false value true, false, 1, 0
DateTime A DateTime represents a temporal value composed of a date (year, month, day) and an optional time component (hours, minutes) ISO 8601
Enum A type consisting of bounded set of constant string values (enumeration members). A string value that is a member of the enumeration
Float A 64-bit signed floating point number All literals that conform to the following formats:

1.234
-1.234
1.2e3
-1.2e3
7E-10
Integer A 32-bit signed integer. In many languages integers over 32-bits become floats, so we limit Open Graph protocol for easy multi-language use. All literals that conform to the following formats:

1234
-123
String A sequence of Unicode characters All literals composed of Unicode characters with no escape characters
URL A sequence of Unicode characters that identify an Internet resource. All valid URLs that utilize the http:// or https:// protocols

Discussion and support

You can discuss the Open Graph Protocol in the Facebook group or on the developer mailing list. It is currently being consumed by Facebook (see their documentation), Google (see their documentation), and mixi. It is being published by IMDb, Microsoft, NHL, Posterous, Rotten Tomatoes, TIME, Yelp, and many many others.


Implementations

The open source community has developed a number of parsers and publishing tools. Let the Facebook group know if you've built something awesome too!

A simple lightweight WordPress plugin which adds Open Graph metadata to WordPress powered sites.