Open Graph Protocol: Complete Developer Guide
A deep technical guide to the Open Graph protocol specification, namespace declarations, object types, and structured property arrays.
The Open Graph protocol (OGP) transforms ordinary web pages into rich objects in a social graph. Originally designed by Facebook, the protocol has become the universal standard for controlling how URLs are represented when shared across the internet.
This developer guide goes beyond the basics and covers the full OGP specification — including namespaces, structured properties, object types, arrays, and edge cases that trip up experienced engineers.
The Open Graph Namespace
Open Graph tags use the property attribute (not name) and are defined under the og: namespace. Technically, the HTML document should declare the namespace in the <html> tag:
<html prefix="og: https://ogp.me/ns#">In practice, most social crawlers parse OG tags without requiring a namespace declaration, but including it ensures strict RDFa compliance.
Required Properties
Every Open Graph object must include four properties:
<meta property="og:title" content="Open Graph Protocol: Complete Developer Guide" />
<meta property="og:type" content="article" />
<meta property="og:image" content="https://example.com/og-image.png" />
<meta property="og:url" content="https://example.com/blog/og-protocol-developer-guide" />These four tags represent the minimum viable metadata for any social preview card. Without og:title and og:image, most platforms will not render a card at all.
Structured Properties
Several OG properties accept structured sub-properties using a dot-notation syntax. The most important is og:image:
<!-- Primary image -->
<meta property="og:image" content="https://example.com/photo.jpg" />
<meta property="og:image:secure_url" content="https://example.com/photo.jpg" />
<meta property="og:image:type" content="image/jpeg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="A developer configuring Open Graph meta tags" />Why Structured Properties Matter
When you specify og:image:width and og:image:height, social platforms can render the preview card immediately without downloading the full image to determine its dimensions. This significantly improves rendering speed in feeds and chat windows.
The same structured property pattern applies to og:video and og:audio:
<meta property="og:video" content="https://example.com/video.mp4" />
<meta property="og:video:type" content="video/mp4" />
<meta property="og:video:width" content="1280" />
<meta property="og:video:height" content="720" />Object Types
The og:type property classifies your content. The protocol defines several type categories:
Website & Article
| Type | Use Case |
|---|---|
website |
Homepages, landing pages, general pages |
article |
Blog posts, news articles, editorials |
For article types, include these additional properties:
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2026-06-03T00:00:00Z" />
<meta property="article:modified_time" content="2026-06-15T00:00:00Z" />
<meta property="article:author" content="https://example.com/authors/sanjay" />
<meta property="article:section" content="Technology" />
<meta property="article:tag" content="Open Graph" />
<meta property="article:tag" content="SEO" />Other Types
| Type | Use Case |
|---|---|
profile |
Author pages, user profiles |
product |
E-commerce product pages |
video.movie |
Feature films |
video.episode |
TV show episodes |
music.song |
Individual music tracks |
book |
Published books |
Multiple Images and Arrays
You can specify multiple images by repeating the og:image tag. The first image is treated as the primary (shown in the preview), and platforms may use secondary images in gallery views:
<meta property="og:image" content="https://example.com/primary.jpg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image" content="https://example.com/secondary.jpg" />
<meta property="og:image:width" content="800" />
<meta property="og:image:height" content="600" />The same array pattern works for og:locale:alternate to declare multiple language versions:
<meta property="og:locale" content="en_US" />
<meta property="og:locale:alternate" content="fr_FR" />
<meta property="og:locale:alternate" content="de_DE" />
<meta property="og:locale:alternate" content="ja_JP" />For a deeper explanation of locales, see Open Graph Locale Explained.
Common Developer Mistakes
1. Using Relative Image URLs
Social crawlers fetch pages from their own servers. A relative path like /images/banner.png resolves to nothing on the crawler’s domain. Always use absolute HTTPS URLs.
2. Forgetting og:url
The og:url tag should point to the canonical URL of the page. This ensures that likes, shares, and engagement data consolidate under a single URL — even if users share variations with query parameters or trailing slashes.
3. Serving Different HTML to Bots
Some JavaScript frameworks render OG tags client-side, which is invisible to social crawlers. Always render OG tags server-side. See our Open Graph JavaScript Implementation guide for framework-specific solutions.
Protocol Reference
For the official specification, visit ogp.me. For a human-readable walkthrough of every property, read our Open Graph Protocol Documentation Explained.
Generate and preview your OG tags instantly with our free Open Graph Generator — or copy a ready-made template from Open Graph Protocol Example: Copy-Paste HTML.