This specification enables web developers to show personalized media recommendations on the browser UI.

This is an unofficial proposal.

Introduction

This section is non-normative.

Media is used extensively today, and the Web is one of the primary means of consuming media content. Many browsers show content recommendations in their UI. This specification aims to enable web sites to specify a feed of personalized media recommendations that can be fetched by the browser and displayed in the browser UI. By improving media discovery this would improve the user experience as well as providing web sites with a new way of reaching users.

Unless otherwise stated, string comparisons are done in a case-sensitive manner.

In this document when we compare a string that starts with or equals https://schema.org then http://schema.org is valid too.

Security and Privacy Considerations

This section is non-normative.

The API introduced in this specification has very low impact with regards to security and privacy. The user agent should take care of fetching feeds based on heuristics. The site may also be able to see when their feed content is clicked by adding tracking to the media feed item url or to the media image url.

For privacy purposes, the user agent should disable the feature in incognito mode. This is because the lifetime of the incognito mode session is not long enough for this feature to be useful.

In order to not show a stale currently logged in user, the user agent should invalidate the contents of a feed in the following cases:

When the feed is invalidated it should clear the contents and trigger a fetch the next time the user agent fetches the feeds.

A cookie name filter is the name of a cookie that signals the user agent to invalidate the contents of the feed. It is intended for the website to provide the name of the login cookie so the user agent can invalidate the feed if the login session changes.

Periodic background fetching of media feeds carries the risk of exposing the list of the user's top media sites to network observers on any network the user connects to in the future. Therefore, the user agent MUST obtain consent for this feature.

Model

The media feed store stores media feeds that have been discovered. There can only be one media feed URL per-origin. If a user agent discovers a new media feed URL for an origin that already has a media feed URL then we will replace the existing one.

Discovery of Media Feeds

The site should advertise the Media Feed to the user agent by adding a link element to the head element, these are known as the eligible feed links. The href attribute contains the media feed URL.

Media Feeds are only discovered on top-level Documents that are a secure context.

The user agent MUST run the following steps for each eligible feed link when the Document is ready for post-load tasks:

Retrieval of Media Feeds

The user agent MUST initiate a fetch with the following request parameters:

The site will return the media feed document which MUST be valid JSON. The feed uses a restricted subset of JSON+LD as specified in this spec. This results in the feed being compatible with JSON+LD but not the other way around.

If the user agent recieves a 410 Gone status code from the site then it should remove the feed from the media feed store.

Media Feed Document

The media feed document should be a CompleteDataFeed. This has a provider property that contains an Organization to describe the publishing web site. The member field on Organization should contain a Person that contains the details about the currently logged in user. The user agent can show this to the user to identifier which account the recommendations are coming from. This is especially important if the media site supports multiple profiles.

The user agent MUST validate the media feed document using the following steps:

The user agent MUST validate the media feed property using the following steps:

The user agent MUST validate the publishing web site using the following steps:

The user agent MUST validate the currently logged in user using the following steps:

Example 1 : Sample Media Feed
          
            {
              "@context": "http://schema.org",
              "@type": "CompleteDataFeed",
              "dataFeedElement": [
                ...
              ]
              "provider": {
                "@type": "Organization",
                "member": {
                  "@type": "Person",
                  "email": "beccahughes@chromium.org",
                  "name": "Becca Hughes",
                  "image": "https://www.example.org/profile_pic.jpg"
                },
                "name": "Media Site",
                "logo": [
                  {
                    "@type": "ImageObject",
                    "width": 336,
                    "height": 188,
                    "url": "https://beccahughes.github.io/logo-dark-title-transparent.png",
                    "additionalProperty": {
                      "@type": "PropertyValue",
                      "name": "contentAttributes",
                      "value": ["forDarkBackground", "hasTitle", "transparentBackground"]
                    }
                  },
                  {
                    "@type": "ImageObject",
                    "width": 336,
                    "height": 188,
                    "url": "https://beccahughes.github.io/logo-light-title-transparent.png",
                    "additionalProperty": {
                      "@type": "PropertyValue",
                      "name": "contentAttributes",
                      "value": ["forLightBackground", "hasTitle", "transparentBackground"]
                    }
                  }
                ]
              },
              "additionalProperty": {
                "@type": "PropertyValue",
                "name": "cookieNameFilter",
                "value": "LOGIN"
              }
            }
          
        

Media Feed Item

A media feed document may contain multiple media feed items. Each item represents a single item of media to be recommended to the user. Each media feed item must be one of the following media item types:

Every media feed item MUST have a media item ID that is unique within the media feed document and is a valid URL.

The user agent MUST validate every media feed item using the following steps:

Media Feed Broadcast Event

The media feed broadcast event describes a media recommendation that could be the broadcasting schedule of a show or a live streaming event on the internet. It contains an embedded media feed item that is the media recommendation that is being broadcast.

Example 2 : Broadcast Event

Below is an example of a video that is being live streamed.

          
            {
              "@context": "https://schema.org/",
              "@type": "BroadcastEvent",
              "@id": "https://example.org/event",
              "isLiveBroadcast": "http://schema.org/True",
              "startDate": "2020-01-28T06:00:00+0000",
              "endDate": "2020-01-28T07:00:00+0000",
              "potentialAction": {
                "@type": "WatchAction",
                "target": "https://example.org/watch/video"
              },
              "workPerformed": {
                "@context": "https://schema.org/",
                "@type": "VideoObject",
                "@id": "https://example.org/video",
                "author": {
                  "@type": "Person",
                  "name": "Test User",
                  "url": "https://example.org/testuser"
                },
                "datePublished": "2020-01-27",
                "duration": "PT5M49S",
                "genre": "Animated Shorts",
                "image": {
                  "@type": "ImageObject",
                  "width": 360,
                  "height": 480,
                  "url": "https://example.org/video_thumbnail.png"
                },
                "interactionStatistic": {
                  "@type": "InteractionCounter",
                  "interactionType": "http://schema.org/WatchAction",
                  "userInteractionCount": "4356"
                },
                "isFamilyFriendly": "http://schema.org/True",
                "name": "Big Buck Bunny"
              }
            }
          
        

Media Item Action

The user agent MUST use the following steps to validate a media item action. The action contains the media feed item url which is used by the user agent to launch the media item.

Media Item Content Rating

The content rating rates the suitability of the media feed item to its audience. It is usually a category that tells which age group is suitable to view the media.

The media item content rating can be a non-empty string containing the content rating of the media item. It can also be a Rating. If it is a Rating then the user agent MUST use the following steps to validate it:

Media Item Interaction Statistic

The media item interaction statistic is a counter that counts how many interactions of a certain type (e.g. likes, views) that a media feed item has. There can be at most one media item interaction statistic for a certain type for a single media feed item.

The user agent MUST use the following steps to validate it:

Media Item Author

The media item author can be a non-empty string containing the name of the author. It can also be a Person. If it is a Person then the user agent MUST use the following steps to validate it:

Media Item Season

The media item season represents a season of TV episodes.

The user agent MUST use the following steps to validate it:

Media Item Episode

The media item episode represents a single TV episode. It contains an embedded watch action stored in the potentialAction property.

The user agent MUST use the following steps to validate it:

Media Image

The media image represents an image that can be a thumbnail that represents the content or it could be the logo for the feed. It has a number of content attributes that describe the image's type and defines its suggested usages. Depending on where the media image is embedded there are different requirements for content attributes.

The user agent MUST use the following steps to validate it:

A media logo is a media image that is the logo for the website providing the feed. The following content attributes are required for the logo to be valid:

A media content image is a media image that is the thumbnail or poster for the media. The media content image does not require any content attributes to be valid, but it does support the following:

A content type attribute indicates to the user agent what type of content the media image contains. There can only ever be one content type content attribute per image. The attributes are defined as the following:

A recommended use attribute indicates to the user agent where the media image can be used. There can only ever be one recommended use content attribute per image. The attributes are defined as the following:

The image on the left would have the iconic, poster and hasTitle attributes. The image on the right would have the sceneStill, background and noTitle attributes.

A background suitability attribute indicates to the user agent whether the media image is suitable for display on different backgrounds. This is important for images that have a transparent background. There can only ever be one background suitability content attribute per image. The attributes are defined as the following:

A title attribute indicates to the user agent whether the media image has a title included with the image. This is important for images that are logos that might be an icon or an icon with a title. There can only ever be one title content attribute per image. The attributes are defined as the following:

The transparent background attribute indicates to the user agent that the media image has a transparent background. This is usually used for images that are the logo of the website. If this is the case the transparentBackground content attribute should be present.

A predominant figure position attribute indicates to the user agent where the predominant figure of the image is positioned in the media image. There can only ever be one predominant figure position content attribute per image. The attributes are defined as the following:

Media Item Identifier

A media item third party identifier is an identifier for the media feed item in a third-party system. The user agent can use it to cross reference the media feed item with media data stored in other systems.

The third party identifier name identifies the type of the third-party identifier and these are left up to the implementation. A list of known identifiers is available here.

The media item third party identifier set is a set of media item third party identifiers that contain at most one identifier per third party identifier name for a single media feed item. Any duplicates MAY be ignored by the user agent.

The user agent MUST use the following steps to validate the media item third party identifier:

Retrieval of Common Properties

This section describes how a user agent MUST validate different schema.org property types.

Boolean

The user agent MUST use the following steps to convert a schema.org boolean property into a normal boolean:

Multiple Values

If the property supports multiple values then the values for the property MUST be wrapped in an array. If there is only one value then it MAY be embedded directly. If there is a maximum number of values supported by a multiple value property then these MAY be ignored by the user agent.

Example 3 : Multiple Values

If there are multiple values for a property then a JSON array can be used. For example with the genre property example below their are two genres specified:

          
            {
              "@context": "https://schema.org/",
              "@type": "VideoObject",
              ...

              "genre": {
                "Action",
                "Comedy"
              },

              ...
            }
          
        

If there is only one value it can be embedded directly in the property without needing an array.

          
            {
              "@context": "https://schema.org/",
              "@type": "VideoObject",
              ...

              "genre": "Action",

              ...
            }
          
        

Continue Watching

A user agent might want to display content for the user to continue watching. In this case the media item action can have the https://schema.org/ActiveActionStatus to indicate this.

Example 3 : Continue Watching
        
          {
            "@context": "https://schema.org/",
            "@type": "VideoObject",
            ...

            "potentialAction": {
              "@type": "WatchAction",
              "actionStatus": "http://schema.org/ActiveActionStatus",
              "startTime": "00:00:10",
              "target": "https://example.org/video?time=10s"
            },

            ...
          }
        
      

Play Next and TV Episodes

A media feed item that is a TV series can have up to two TV episodes embedded in it. These can be embedded directly in the media feed item or embedded within a media item season. If there are more than two episodes they will be ignored.

The user agent MUST use the following steps to calculate the main TV episode:

A user agent might want to display the next episode in a TV series to play next. In this case, the user agent should calculate the play next episode using the following algorithm:

IANA Considerations

This section provides the provisional registration of the media-feed link relation type in the link relation type registry in accordance with Web Linking.

Relation Name
media-feed
Description
Refers to a feed of personalised media recommendations relevant to the link context
Reference document(s)
https://wicg.github.io/media-feeds/#discovery-of-media-feeds
Related information
N/A