Semantic Web. Web 3.0. The wave of the future.

But the future isn't here just yet.

Though Open Graph (OG) is very promising (and more than a little scary), it seems to me that it's still very much in beta. But I give Facebook credit for failing forward.

The main problems I have with it are:

1. Though OG appears to be very powerful, the existing documentation is sufficient only for the most trivial apps.
2. It's possible to permanently, irrevocably break your app's OG integration.
3. It's impossible to migrate data safely if you decide to re-structure your object schema.
4. Though video integration is strong, there are too many restrictive rules around having top-notch image integration. In fact, you basically have to be Instragram™ to get it.

OK, So What Exactly Is Open Graph?

Those familiar with the notion of semantic web will recognize this:

So semantic web is all about structuring your data in a way that mimics sentences in natural languages.

OG is Facebook's take on semantic web.

• Users are Facebook identities. They are people who may use your app through FB.
• Objects are the pages of your app. For example, you may have a "Music Collection" object type, and the definition of a given collection is the page where it can be found. You can use FB's default data types, or define your own.
• Actions are the things that Users can do to or with your Objects

Whereas Facebook's previous APIs allowed you to define the entire story in an API call, with OG you simply pass the url of the page on which the user did something, the identity of the user, and the action that was taken, and Facebook will suck in the rest of the data it needs from the OG declarations you made in the head of the html document of that page (e.g. User "Lucas" Action "read" Object "a story about Kim Kardashian's butt").

How We Tried To Use Open Graph At PandaWhale

Since the technology is so young, there is very little expertise in the dev community about how to use OG in advanced ways. So there's a learning process. And that's fine, but the problem is that it's not always clear how best to organize your object definitions a priori. For example, for v1 of our OG integration at PandaWhale, I defined the following objects:

• Photos. These are meant to be the photos/images that people stash with our bookmarklet.
• Videos. YouTube and Vimeo vids our users stash. This is a "primitive" Facebook Open Graph data type (og:video).
• Articles. Another FB data type (og:article). It is commonly used by social readers, and I intended it to be for convos that are neither stashed videos nor stashed images.

So I also defined a commenting and posting Actions (pandawhale:comment_on and pandawhale:post), both of which can act on any of our 3 object types ("Lucas posted a video", "Lucas commented on an article", etc.). The integration seemed to work great, especially for videos, which produce attractive share stories that let videos be played in-context on Facebook.

At that point there were only a handful of apps whose OG integration might be said to be better than ours -- Pinterest and Instagram come to mind -- but it's a big pond, and those are some big fish.

We wanted to take our OG integration "to the next level," so we decided to experiment with recreating our convo stash structure on Facebook. We wanted to give users new ways to aggregate and sort their stories, which also happens to be one of the main capabilities Facebook is using to sell people on OG. It wasn't clear in the beginning, but Custom Object Properties are the key to doing these advanced tricks.

But og: object types are immutable, meaning you cannot add custom properties to them. This means that if you use the og:video type to get those slick video shares right off the bat, you'll have to destroy your old video stories when you migrate to a custom object type which defines a video as a property (is it supposed to be obvious that you should do that?). Ditto for og:article, or any other OG "native" type.

I would be OK with that, but you have to destroy those old stories in order to move forward. Even worse, you cannot change the object type associated with a given url after the first time it gets sucked in and categorized by Facebook, even if you change the OG metadata in the head of the document. FB's "caching" appears to be permanent in this respect. This could cause problems as serious as all users who signed up before a certain date NEVER having access to certain OG functionality that your new users get.

Furthermore, if you remove ALL of your object definitions and start over from a clean slate, it appears that the FB app filter becomes permanently broken for that app. Thankfully, I only did this to a development app. It would be a disaster in production to have to change the FB side of your app (and therefore the OAuth keys).

Lessons Learned About Integrating With Open Graph

1. NEVER use default OG data types like og:video and og:article as top-level objects in your app. If you want to have video, define some other object type and give it an og:video property.
2. Remember that you can make custom properties that are of custom object types. For example, we have a pandawhale:stash (collection of convos) object type and a pandawhale:stasher (person who collects) type. The pandawhale:stash represents a stash on PandaWhale, whereas a stasher is a person. I defined a custom property pandawhale:stash:owner which I declared as type pandawhale:stasher, which is pretty awesome.
3. Try to think through what types of collections and stories you're likely to want early on, and design your object schema accordingly. It's definitely not trivial to make basic schema changes later. Facebook may make better migration tools down the road, but for now you risk serious data loss as a result of re-defining your object schema. Remember, you want to ADD new objects and properties as you grow, not REMOVE them as removing object types causes loss of data.
4. Consider making every publicly-available page an OG object. If people can visit and interact with the page, why not embed the OG metadata and define an OG object in your app settings? Even if you aren't generating stories based on these pages yet, it still allows you more control over what FB shares of that page will look like since Facebook parses this metadata each time someone attempts to share one of your urls.

EDIT: June 6, 2012

The "irrevocable" breakage I experienced with my development app appears to be fixed now, apparently as a result of deauthorizing and then reauthorizing the app. So it seems to not be truly permanent, but you should still be careful with your app settings as you don't want to ask each user to remove and re-add your app.

One does not simply implement Open Graph applications.

Great writeup, Lucas.

I don't think of Open Graph as an evolution of Semantic Web.

I think of Open Graph as Facebook's implementation of the Interest Graph.

I also think that although Open Graph is Facebook's future, there's a rough road ahead to getting people -- specifically, developers -- to understand what's possible and what's desirable in our implementations of apps that use Open Graph.

In the meantime, there is suffering because of bugs and lack of documentation.

Especially documentation of best practices with examples.

This is a fantastic article, thank you for taking the time to put it together!