DOCSEARCHbyAlgolia
Submit Docs

Open Graph Protocol (OGP)

repository·master·Indexed 19 days ago

https://github.com/facebook/open-graph-protocol

Documentation for the Open Graph Protocol used to turn web pages into rich objects in a social graph. Includes specifications for required and optional <meta> tags, structured properties for images, video, and audio, and detailed references for object types across verticals such as music, video, articles, books, and profiles.

Tokens
2.9K
Snippets
6
Records
10
Agent score
16%

What's inside Open Graph Protocol

  1. How to implement arrays in Open Graph

    master

    To represent a list of values (an array) in Open Graph, use multiple <meta> tags with the same property name. The first tag encountered (from top to bottom) takes precedence in case of conflicts.

    When using structured properties, place them immediately after the root tag they belong to. A new root element signals the end of the previous structured property set and the start of a new one.

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

  2. How to specify object types using og:type

    master

    To represent an object within the Open Graph graph, you must specify its type using the og:type property.

    For global types, use the type name directly:

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

    For custom or user-defined types, use CURIEs (Compact URI) with a namespace prefix and a colon:

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

    Note: Global types belonging to a specific vertical (namespace) are prefixed with the namespace and a period (e.g., music.song) to distinguish them from user-defined namespaced types that use colons.

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

  3. Implement basic Open Graph metadata

    master

    To turn a web page into a rich object in a social graph, you must add specific <meta> tags to the <head> of your HTML. The protocol is based on RDFa, so you should include the prefix="og: https://ogp.me/ns#" attribute in your <html> tag.

    Every page requires these four properties:

    • og:title: The title of your object.
    • og:type: The type of your object (e.g., video.movie). Note that certain types may require additional specific properties.
    • og:image: A URL to an image representing the object.
    • og:url: The canonical URL of the object, used as its permanent ID in the graph.
    <html prefix="og: https://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="https://www.imdb.com/title/tt0117500/" />
<meta property="og:image" content="https://ia.media-imdb.com/images/rock.jpg" />
</head>
</html>

  4. Use structured properties for images, videos, and audio

    master

    Some properties allow for extra metadata via structured properties using a colon syntax (e.g., og:image:width).

    Image Structured Properties

    • og:image:url: Identical to og:image.
    • og:image:secure_url: An alternate HTTPS URL.
    • og:image:type: The MIME type of the image.
    • og:image:width: Width in pixels.
    • og:image:height: Height in pixels.
    • og:image:alt: A description of the image content.

    Video Structured Properties

    Identical to og:image properties.

    Audio Structured Properties

    Only supports the first three properties:

    • og:audio:url (via root og:audio)
    • og:audio:secure_url
    • og:audio:type (MIME type)
    <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" />
<meta property="og:image:alt" content="A shiny red apple with a bite taken out" />

  5. Reference of Video object types and properties

    master

    The Video vertical uses the namespace https://ogp.me/ns/video#. Available og:type values and their properties include:

    video.movie

    • video:actor (array of profile): Actors in the movie.
    • video:actor:role (string): The role they played.
    • video:director (array of profile): Directors of the movie.
    • video:writer (array of profile): Writers of the movie.
    • video:duration (integer >= 1): The movie's length in seconds.
    • video:release_date (datetime): The date the movie was released.
    • video:tag (array of string): Tag words associated with this movie.

    video.episode

    • Identical to video.movie properties, plus:
    • video:series (video.tv_show): Which series this episode belongs to.

    video.tv_show

    • A multi-episode TV show. Metadata is identical to video.movie.

    video.other

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

  6. Reference of Music object types and properties

    master

    The Music vertical uses the namespace https://ogp.me/ns/music#. Available og:type values and their properties include:

    music.song

    • music:duration (integer >= 1): The song's length in seconds.
    • music:album (array of music.album): The album this song is from.
    • music:album:disc (integer >= 1): Which disc of the album this song is on.
    • music:album:track (integer >= 1): Which track this song is.
    • music:musician (array of profile): The musician that made this song.

    music.album

    • music:song (music.song): The song on this album.
    • music:song:disc (integer >= 1): Disc number (reverse of music:album:disc).
    • music:song:track (integer >= 1): Track number (reverse of music:album:track).
    • music:musician (profile): The musician that made this album.
    • music:release_date (datetime): The date the album was released.

    music.playlist

    • music:song (Identical to music.album properties)
    • music:song:disc
    • music:song:track
    • music:creator (profile): The creator of this playlist.

    music.radio_station

    • music:creator (profile): The creator of this station.

  7. Use optional Open Graph metadata properties

    master

    The following properties are optional but recommended to provide more context about your object:

    • og:audio: URL to an audio file.
    • og:description: A 1-2 sentence description.
    • og:determiner: The word appearing before the title (e.g., "a", "an", "the", "", "auto"). Default is "".
    • og:locale: The locale of the tags (format: language_TERRITORY, e.g., en_GB). Default is en_US.
    • og:locale:alternate: An array of other available locales.
    • og:site_name: The name of the overall website (e.g., "IMDb").
    • og:video: URL to a video file.
    <meta property="og:audio" content="https://example.com/bond/theme.mp3" />
<meta property="og:description" content="Sean Connery found fame and fortune..." />
<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="https://example.com/bond/trailer.swf" />

  8. Reference of Global (No Vertical) object types

    master

    These are broadly used objects that do not belong to a specific vertical.

    article (Namespace: https://ogp.me/ns/article#)

    • article:published_time (datetime): When the article was first published.
    • article:modified_time (datetime): When the article was last changed.
    • article:expiration_time (datetime): When the article is out of date.
    • article:author (array of profile): Writers of the article.
    • article:section (string): A high-level section name (e.g., Technology).
    • article:tag (array of string): Tag words associated with this article.

    book (Namespace: https://ogp.me/ns/book#)

    • book:author (array of profile): Who wrote this book.
    • book:isbn (string): The ISBN.
    • book:release_date (datetime): The date the book was released.
    • book:tag (array of string): Tag words associated with this book.

    payment.link (Namespace: https://ogp.me/ns/payment#) 🚧 Beta only

    • payment:description (string): Description about the payment link.
    • payment:currency (string): The ISO 4217 currency code.
    • payment:amount (float): Amount requested in decimal format.
    • payment:expires_at (datetime): Expiration date and time.
    • payment:status (enum): PENDING, PAID, FAILED, EXPIRED.
    • payment:id (string): Unique identifier for the payment gateway.
    • payment:success_url (url): Redirect URL upon successful payment.

    profile (Namespace: http://ogp.me/ns/profile#)

    • profile:first_name (string): Given name.
    • profile:last_name (string): Family/married name.
    • profile:username (string): Unique identifier string.
    • profile:gender (enum): male, female.

    website (Namespace: https://ogp.me/ns/website#)

    • No additional properties beyond basic ones. Use for any non-marked up webpage.

  9. Reference of Open Graph data types

    master

    The following data types are used when defining attributes in the Open Graph protocol:

    TypeDescriptionLiterals
    BooleanA true or false valuetrue, false, 1, 0
    DateTimeTemporal value (year, month, day + optional time)ISO 8601
    EnumBounded set of constant string valuesA string value that is a member of the enumeration
    FloatA 64-bit signed floating point number1.234, -1.234, 1.2e3, -1.2e3, 7E-10
    IntegerA 32-bit signed integer1234, -123
    StringA sequence of Unicode charactersUnicode characters with no escape characters
    URLIdentifies an Internet resourceValid URLs utilizing http:// or https://

  10. Retrieve the Open Graph Protocol schema via Content Negotiation

    master

    The ogp.me endpoint supports content negotiation via the HTTP_ACCEPT header to serve the protocol schema in different formats. You can programmatically request the schema by setting your request headers accordingly:

    • To receive the schema in Turtle format, set Accept: text/turtle.
    • To receive the schema in RDF/XML format, set Accept: application/rdf+xml.

    Additionally, a direct request from http://ogp.me/ (via the Referer header) will default to the Turtle format.

    # Example: Requesting Turtle format
GET / HTTP/1.1
Host: ogp.me
Accept: text/turtle

# Example: Requesting RDF/XML format
GET / HTTP/1.1
Host: ogp.me
Accept: application/rdf+xml