Open Graph
When someone shares a URL, the receiving application often tries to build a preview. Without structured metadata, it may guess which title, image, and description best represent the resource—and guess poorly.
The Open Graph Protocol provides a shared vocabulary for describing a web page as an object. Compatible applications can identify the content’s title, type, URL, description, images, and related fields. The protocol originated at Facebook and is now used across many apps and services.
Implementing Open Graph does not transfer ownership of your content to a platform. You still control the page, its metadata, and the resources it references. Consumers may interpret properties differently and are not required to display every field. Valid Open Graph markup does not guarantee a preview, indexing, rankings, or featuring.
Where Open Graph came from
Open Graph was designed so ordinary web pages could participate in a social graph with enough structured information to represent an object richly. It builds on RDFa-style metadata: namespaced properties expressed as HTML <meta> elements, normally in the document <head>.
The authoritative specification is published at ogp.me. It is a protocol specification, not a W3C Recommendation or an IETF RFC. Platform link-preview rules (image sizes, refresh schedules, debugging tools) are separate from the protocol itself. Publishers can implement valid Open Graph and still see different results across consumers.
Describe a page as an object
Open Graph metadata lives in the HTML of the page that represents the object:
<meta property="og:title" content="Notes from the lab">
<meta>carries a property declaration.propertynames the Open Graph field (not the HTMLnameattribute used for ordinary descriptions).contentholds the value.- The
og:prefix identifies the Open Graph namespace. - The property name (such as
title) identifies which field you are setting.
A minimal document:
<!doctype html>
<html lang="en" prefix="og: https://ogp.me/ns#">
<head>
<meta charset="utf-8">
<title>Example Site</title>
<meta property="og:title" content="Example Site">
<meta property="og:type" content="website">
<meta property="og:url" content="https://joshua.example/">
<meta
property="og:image"
content="https://joshua.example/images/preview.jpg"
>
</head>
<body>
<main>
<h1>Example Site</h1>
<p>Writing, projects, and other experiments.</p>
</main>
</body>
</html>
The prefix attribute declares the Open Graph namespace. The four core properties identify the object. The visible <h1> and body remain ordinary HTML for people.
The foundation of an Open Graph object
The protocol identifies four required properties for every page.
| Property | Role | Example |
|---|---|---|
og:title |
Title of the object as it should appear in the graph | Notes from the lab |
og:type |
Kind of object | article, website, music.song |
og:image |
Absolute URL of a representing image | https://joshua.example/images/workbench.jpg |
og:url |
Canonical object URL / permanent ID in the graph | https://joshua.example/notes/lab/ |
og:title
Supplies the object title. It often resembles the HTML <title> and visible <h1> but need not be identical word for word. Prefer a title for the specific page (article, project, homepage), not a slogan reused everywhere.
og:type
Identifies the object kind. Use documented types such as website and article, or specialized types in music and video verticals. Do not invent global types consumers will not recognize.
og:image
Points at an image that represents the object. Use an absolute http or https URL, a suitable MIME type, and a publicly reachable resource. Individual applications may impose their own size and aspect preferences.
og:url
Identifies the canonical URL of the object. Keep it consistent with permanent redirects and with HTML rel="canonical" when you publish one. Conflicting URLs confuse consumers about which resource is canonical. See SEO fundamentals.
Provide a more useful description
Optional properties recommended by the protocol include:
| Property | Purpose |
|---|---|
og:description |
One- or two-sentence summary of the object |
og:site_name |
Name of the overall site when the object is part of a larger site |
og:locale |
Locale of the tags, as language_TERRITORY (default en_US) |
og:locale:alternate |
Other locales this page is available in |
og:determiner |
Word before the title in a sentence (a, an, the, "", auto) |
og:audio |
URL of audio that accompanies the object |
og:video |
URL of video that complements the object |
Describe the specific page, not a generic site slogan. Distinguish og:site_name (Harbor Notes) from og:title (Notes from the lab). Open Graph locales use underscores (en_US, en_GB); HTML lang usually uses BCP 47 tags (en, en-US). A media URL does not guarantee embedded playback.
Make your preview images reliable
Structured image properties refine og:image:
og:image:url— identical toog:imageog:image:secure_url— HTTPS alternate when usefulog:image:type— MIME typeog:image:width/og:image:height— actual pixel dimensionsog:image:alt— description of what is in the image (not a caption)
<meta
property="og:image"
content="https://joshua.example/images/workbench.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 wooden workbench with two monitors and a laptop"
>
Dimensions should match the real file. og:image:alt is alternative text for the image content, not the filename. 1200×630 is a commonly used preview size among some platforms—not a universal Open Graph requirement. Similar structured properties exist for og:video and (partially) og:audio.
What happens when there is more than one value?
Repeat a property to create an array. The first value is preferred when values conflict:
<meta property="og:image" content="https://joshua.example/images/primary.jpg">
<meta property="og:image" content="https://joshua.example/images/secondary.jpg">
Structured properties attach to the preceding root. When another root begins, the previous structured group ends.
Correct grouping:
<meta property="og:image" content="https://joshua.example/images/a.jpg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image" content="https://joshua.example/images/b.jpg">
<meta property="og:image:width" content="800">
<meta property="og:image:height" content="800">
Incorrect: declaring two images, then a single height that consumers may attach only to the last image. Put each image’s structured fields immediately after that image’s root tag.
Describe what kind of content you’re publishing
Object types are either globally defined or namespaced extensions. Global vertical types use a period (music.song, video.movie). Custom namespaces use CURIEs with colons.
website
Default treatment for unmarked pages and ordinary site roots. No extra vertical properties beyond the basics.
article
Writing with optional article:* properties (below). Namespace: https://ogp.me/ns/article#.
profile
People-oriented objects with profile:* properties. Namespace documented on ogp.me.
book
Published books with book:* properties.
Music
Namespace https://ogp.me/ns/music#. Types include music.song, music.album, music.playlist, and music.radio_station, with properties such as music:duration, music:album, music:musician, music:song, and music:release_date.
Video
Namespace https://ogp.me/ns/video#. Types include video.movie, video.episode, video.tv_show, and video.other, with properties such as video:actor, video:director, video:duration, video:release_date, video:tag, and video:series.
Do not invent unsupported globals such as game, photograph, or software. When Open Graph lacks a precise type, use a valid general representation (often website) and add Schema.org for finer typing.
Describe published writing
Article properties:
| Property | Meaning |
|---|---|
article:published_time |
First publication (ISO 8601 datetime) |
article:modified_time |
Last change |
article:expiration_time |
When the article is considered out of date |
article:author |
Author profile URL(s) |
article:section |
High-level section (for example Technology) |
article:tag |
Topical tags for the article |
article:tag describes article topics—not slash-page categories or URL conventions. Visible HTML dates should agree with these fields.
<meta property="og:title" content="Notes from the lab">
<meta property="og:type" content="article">
<meta property="og:url" content="https://joshua.example/notes/lab/">
<meta property="og:image" content="https://joshua.example/images/workbench.jpg">
<meta property="og:description" content="Rebuilding a workbench and shipping a cleaner Atom feed.">
<meta property="og:site_name" content="Harbor Notes">
<meta property="article:published_time" content="2026-10-01T09:30:00-07:00">
<meta property="article:modified_time" content="2026-10-03T11:00:00-07:00">
<meta property="article:author" content="https://joshua.example/about/">
<meta property="article:section" content="Lab notes">
<meta property="article:tag" content="indieweb">
<meta property="article:tag" content="woodworking">
Profile metadata
profile may use profile:first_name, profile:last_name, profile:username, and profile:gender (enum male / female per the current specification). Treat these as optional. Do not publish personal attributes merely because the protocol defines them.
Profile Open Graph differs from Microformats2 h-card, Schema.org Person, and HTML rel="me". Those systems can coexist when they describe the same person consistently.
Music metadata
Example song on an independent site:
<meta property="og:title" content="Pier Lights">
<meta property="og:type" content="music.song">
<meta property="og:url" content="https://joshua.example/music/pier-lights/">
<meta property="og:image" content="https://joshua.example/images/pier-lights.jpg">
<meta property="og:audio" content="https://joshua.example/audio/pier-lights.mp3">
<meta property="music:duration" content="214">
<meta property="music:musician" content="https://joshua.example/about/">
<meta property="music:release_date" content="2026-09-01">
Metadata describes the release; the audio file is a separate resource. Consumers may show a preview without playing audio.
Video metadata
<meta property="og:title" content="Harbor fog, reel one">
<meta property="og:type" content="video.other">
<meta property="og:url" content="https://joshua.example/videos/harbor-fog/">
<meta property="og:image" content="https://joshua.example/images/harbor-fog-poster.jpg">
<meta property="og:video" content="https://joshua.example/videos/harbor-fog.mp4">
<meta property="og:video:type" content="video/mp4">
<meta property="video:duration" content="180">
<meta property="video:release_date" content="2026-08-12">
<meta property="video:tag" content="documentary">
Protocol validity differs from whether an application embeds the video. Prefer public HTTPS media URLs and a clear poster image.
Books and other published works
<meta property="og:title" content="Notes on Quiet Machines">
<meta property="og:type" content="book">
<meta property="og:url" content="https://joshua.example/books/quiet-machines/">
<meta property="og:image" content="https://joshua.example/images/quiet-machines-cover.jpg">
<meta property="book:author" content="https://joshua.example/about/">
<meta property="book:isbn" content="9780000000000">
<meta property="book:release_date" content="2026-05-01">
<meta property="book:tag" content="essays">
Photography, software, games, and digital artwork may lack a dedicated global Open Graph type. Use accurate core properties (often website or article when appropriate) and add Schema.org types such as Photograph, SoftwareApplication, or VideoGame when you need precision. Do not invent Open Graph types.
Complete implementation example: A published article
<!doctype html>
<html lang="en" prefix="og: https://ogp.me/ns#">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Notes from the lab | Harbor Notes</title>
<meta
name="description"
content="Rebuilding a workbench and shipping a cleaner Atom feed."
>
<link rel="canonical" href="https://joshua.example/notes/lab/">
<meta property="og:title" content="Notes from the lab">
<meta property="og:type" content="article">
<meta property="og:url" content="https://joshua.example/notes/lab/">
<meta
property="og:image"
content="https://joshua.example/images/workbench.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 wooden workbench with two monitors and a laptop"
>
<meta
property="og:description"
content="Rebuilding a workbench and shipping a cleaner Atom feed."
>
<meta property="og:site_name" content="Harbor Notes">
<meta property="og:locale" content="en_US">
<meta
property="article:published_time"
content="2026-10-01T09:30:00-07:00"
>
<meta
property="article:modified_time"
content="2026-10-03T11:00:00-07:00"
>
<meta property="article:author" content="https://joshua.example/about/">
<meta property="article:section" content="Lab notes">
<meta property="article:tag" content="indieweb">
<meta property="article:tag" content="woodworking">
</head>
<body>
<header>
<p><a href="https://joshua.example/">Harbor Notes</a></p>
<nav aria-label="Site">
<a href="https://joshua.example/notes/">Notes</a>
<a href="https://joshua.example/about/">About</a>
</nav>
</header>
<main>
<article>
<h1>Notes from the lab</h1>
<p>
Published
<time datetime="2026-10-01T09:30:00-07:00">Oct. 1, 2026</time>
</p>
<p>
I rebuilt my workbench and published a cleaner Atom feed.
</p>
</article>
</main>
</body>
</html>
Core og:* fields identify the object; article:* fields add publication context; the body remains readable without JavaScript. Canonical and og:url match.
Examples for other content types
Homepage (website):
<meta property="og:title" content="Harbor Notes">
<meta property="og:type" content="website">
<meta property="og:url" content="https://joshua.example/">
<meta property="og:image" content="https://joshua.example/images/site.jpg">
<meta property="og:description" content="Writing, photos, and small projects.">
<meta property="og:site_name" content="Harbor Notes">
Photography project: use strong og:image / description / URL with website (or article if it is a write-up), then Schema.org Photograph or ImageGallery for specificity.
Music / video / book: use the examples in the sections above.
Software or game: valid general Open Graph (often website) plus Schema.org SoftwareApplication or VideoGame—not invented og:type values.
How Open Graph complements the page itself
| Metadata | Purpose |
|---|---|
HTML <title> |
Document identity |
| Meta description | General page summary |
| Canonical link | Preferred resource URL |
og:title |
Object title for compatible consumers |
og:description |
Object summary |
og:image |
Object preview image |
og:url |
Canonical object identity |
og:type |
Object classification |
Values may differ slightly while describing the same resource. Contradictions—different titles, mismatched dates, or an og:url that disagrees with rel="canonical"—should be corrected so people and machines see one story.
Open Graph versus Microformats2 and Schema.org
- Microformats2 marks structure in HTML content (entries, authors, dates, relationships).
- Schema.org provides a broad typed vocabulary, often serialized as JSON-LD.
- Open Graph focuses on the object associated with a page for compatible graph/preview consumers.
The same article can use all three when titles, authors, dates, and URLs stay aligned.
Open Graph isn’t the only preview system
Some services consume Open Graph; others also recognize platform-specific cards. X (Twitter) Cards are not part of the Open Graph Protocol. Properties such as twitter:card, twitter:title, twitter:description, and twitter:image are vendor metadata that can coexist with og:* tags. Fallback behavior differs by platform—do not assume one mapping.
<meta property="og:title" content="Notes from the lab">
<meta property="og:description" content="Rebuilding a workbench.">
<meta property="og:image" content="https://joshua.example/images/workbench.jpg">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Notes from the lab">
<meta name="twitter:image" content="https://joshua.example/images/workbench.jpg">
Making previews reliable
- Public HTTPS page and image URLs
- Successful HTTP status codes
- Reachable images with correct MIME types and accurate dimensions
- Sensible aspect ratios for your audience’s common consumers
- Clear redirect chains that land on the intended resource
- Open Graph tags present in the server-delivered HTML
- Canonical /
og:urlconsistency - Robots rules that allow intended fetches
- Awareness that preview caches refresh on consumer schedules
An image that loads in your browser can still fail for a preview bot blocked by hotlink rules, auth walls, or redirects. Updating a page does not always update a cached preview immediately.
Open Graph and independent publishing
Open Graph lets independently hosted articles, photographs, projects, music, and videos present informative link previews in directories, chats, and social environments—without uploading the originals to a central platform. Metadata stays on the publisher-controlled site. An account on the consuming service is not required to publish the tags.
Security and privacy considerations
Metadata is public. Avoid leaking unpublished drafts, sensitive images, profile attributes you did not intend to share, URLs with secrets or tokens, private images referenced from public pages, or metadata that contradicts access controls. Escape attribute values safely. Review Open Graph with the same care as visible content.
Check how your page is represented
Inspect the published HTML
View Source and confirm og:* properties appear in the delivered head—not only in a client-rendered shell.
Verify HTTP responses
curl -i https://joshua.example/notes/lab/
curl -I https://joshua.example/images/workbench.jpg
Inspect metadata and images
Confirm property values, absolute image URLs, content types, and dimensions.
Check canonical URLs
Compare og:url, rel="canonical", and the live address.
Test previews
Use current platform debuggers where available (for example Facebook’s sharing debugger and other vendor tools). Requirements change—verify the tool you use still applies.
Cached results and HTML validation
Expect stale previews until a consumer refreshes. The Nu HTML Checker catches document errors; it does not fully validate the Open Graph object model.
Common mistakes
| Mistake | Consequence | Correction |
|---|---|---|
| Missing core properties | Weak or empty object representation | Set title, type, image, and url |
Invented og:type values |
Consumers ignore or misclassify | Use documented types |
Relative og:image |
Broken previews | Use absolute HTTPS URLs |
| Inaccessible images / wrong MIME | Preview fails | Fix hosting and types |
| Wrong dimensions | Misleading layout hints | Match real pixel size |
Missing og:image:alt |
Weaker accessibility for the image object | Describe the image content |
Conflicting canonical and og:url |
Ambiguous identity | Align permanent URLs |
| Generic metadata on every page | Previews look identical | Per-page titles and descriptions |
| Mis-ordered multi-image structured props | Dimensions attach to the wrong image | Group fields under each root |
| Invalid dates | Time parsing fails | Use ISO 8601 |
article:tag as slash-page names |
Wrong layer for site sections | Use tags for topics; OPML for slash conventions |
name="og:title" instead of property |
Many consumers miss the field | Use property="og:…" |
| Assuming all properties render | Surprise omissions | Treat display as consumer-specific |
| Expecting instant cache refresh | Old previews persist | Re-debug / wait for consumer refresh |
| Sensitive data in metadata | Unintended disclosure | Publish only intentional public facts |
| Treating Twitter Card tags as Open Graph | Spec confusion | Keep vendor tags separate |
Open Graph and the Joshternet
Accurate page metadata helps independent sites present recognizable titles, descriptions, and images across the open web—including surfaces that participate in Joshternet discovery.
Joshternet’s hub crawl consumes a subset of Open Graph signals (for example site/page titles and descriptions, selected images, limited type/url usage on creative indexes, and article:published_time when present). It is not a complete Open Graph protocol consumer. Properties such as og:locale, og:video, og:audio, and og:image:alt are not discovery drivers here today. See Reference. Markup does not guarantee indexing or featuring.
Continue through the handbook
- Semantic HTML
- SEO fundamentals
- Microformats2
- Schema.org and JSON-LD
- Creative media
- Feeds
- Links and relations
- Validation
- Reference
Handbook navigation below follows content_nav (previous: Microformats2; next: Schema.org and JSON-LD).
Specifications and references
| Reference | Authority |
|---|---|
| Open Graph Protocol | Protocol specification |
| Open Graph namespace | RDF schema for og: |
| HTML Living Standard | Document structure and metadata |
| RDFa Core 1.1 | RDFa foundations OG builds on |
| Schema.org | Broader typed vocabulary |
| JSON-LD 1.1 | Common Schema.org serialization |
| Microformats2 | In-HTML structured data |
| Nu HTML Checker | HTML conformance (not full OG validation) |
| X Cards documentation | Platform-specific preview metadata |