Open Graph Protocol Documentation Explained
A human-readable walkthrough of the official Open Graph protocol documentation at ogp.me, covering every property, type, and structured object.
The official Open Graph protocol documentation lives at ogp.me. While authoritative, it’s dense and written in a specification style that can be difficult to parse for developers who just want to implement tags quickly.
This article walks through the official documentation section by section, explaining what each part means in practical terms.
The Specification Structure
The OGP documentation is organized into these sections:
- Basic Metadata — The four required properties.
- Optional Metadata — Recommended but non-mandatory tags.
- Structured Properties — Sub-properties for images, video, and audio.
- Object Types — Content type classifications and their specific properties.
- Arrays — How to declare multiple values for a property.
Basic Metadata Explained
The documentation states that every page must include four root properties. In plain HTML:
<meta property="og:title" content="Page Title" />
<meta property="og:type" content="website" />
<meta property="og:image" content="https://example.com/image.png" />
<meta property="og:url" content="https://example.com/page" />What the docs don’t emphasize enough: og:url should always be the canonical URL — the single, authoritative URL for the page. If users can reach the same page via http://, https://, www., or non-www variants, og:url should point to whichever one you’ve canonicalized.
Optional Metadata Explained
The specification lists several optional properties that “should” be included:
| Property | What the Docs Say | What It Means in Practice |
|---|---|---|
og:description |
“A one to two sentence description” | Keep under 200 characters. Social platforms truncate longer descriptions. |
og:determiner |
“The word that appears before this object’s title” | Rarely used. Options: "a", "an", "the", "", "auto". |
og:locale |
“The locale these tags are marked up in” | Format: language_TERRITORY (e.g., en_US). Default: en_US. See Open Graph Locale Explained. |
og:locale:alternate |
“Array of other locales this page is available in” | Used for multilingual sites with translated content. |
og:site_name |
“The name of the overall site” | Your brand name (e.g., "Open Graph Generator"). |
Structured Properties Explained
The documentation introduces “structured properties” for media objects. This is where many developers get confused.
When you declare og:image, you can follow it with sub-properties that describe that specific 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 photo of the product" />The critical rule: structured sub-properties must immediately follow their parent property in the HTML source. If you insert other tags between og:image and og:image:width, some parsers may fail to associate them.
For image sizing requirements, see the Open Graph Image Size Guide.
Object Types Explained
The og:type value determines which additional properties are available. The documentation groups types into verticals:
Websites and Articles
website— Default. No additional properties required.article— Unlocksarticle:published_time,article:author,article:section,article:tag.
Media Types
music.song,music.album,music.playlist,music.radio_stationvideo.movie,video.episode,video.tv_show,video.other
People and Products
profile— Unlocksprofile:first_name,profile:last_name,profile:username,profile:gender.book— Unlocksbook:author,book:isbn,book:release_date,book:tag.
In practice, 95% of pages use either website or article.
Arrays Explained
The documentation mentions that properties can have multiple values through “arrays.” This simply means repeating the same property tag:
<meta property="og:image" content="https://example.com/photo1.jpg" />
<meta property="og:image" content="https://example.com/photo2.jpg" />
<meta property="article:tag" content="Open Graph" />
<meta property="article:tag" content="SEO" />
<meta property="article:tag" content="Meta Tags" />The first value is treated as the primary (used in the card preview), with subsequent values serving as alternates.
What the Documentation Doesn’t Cover
The official OGP spec hasn’t been significantly updated since its initial release. Several important practical considerations are missing:
- Twitter Card integration — Twitter has its own meta tag system that falls back to OG tags. See Twitter Open Graph Fallback Explained.
- Image file size limits — Each platform has different maximum file sizes (typically 5–8 MB).
- Cache invalidation — The spec doesn’t address how to force platforms to re-scrape updated tags.
- Dynamic rendering for SPAs — JavaScript-rendered OG tags require server-side or edge rendering.
Related Resources
- Open Graph Protocol: Complete Developer Guide
- What Is Open Graph? Complete Guide
- Open Graph Tags: Complete List With Examples
- Preview and validate your implementation with the Open Graph Inspector