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 @context MUST be set to https://schema.org.
• The type MUST be set to CompleteDataFeed.
• The provider property MUST contain a Organization that is a valid publishing web site.
• The dataFeedElement property supports multiple values and if present it MUST contain valid media feed items or media feed broadcast events.
• The additionalProperty property supports multiple values and if present it MUST contain valid media feed properties.

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

• The type MUST be set to PropertyValue.
• The name property MUST be present and contain a valid non-empty string.
• The value property MUST be present
• If the name name property contains cookieNameFilter then the user agent MUST run the following steps:
  • The value property MUST contain a valid non-empty string that will be set as the cookie name filter.

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

• The type MUST be set to Organization.
• The name property MUST contain a valid non-empty string.
• The logo property supports multiple values and MUST contain a maximum of 5 different media logos.
• The member property is optional. If present, it MUST contain a valid currently logged in user.

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

• The type MUST be set to Person.
• The name property MUST contain a valid non-empty string.
• The image property is optional. If present, it MUST contain a valid media image.
• The email property is optional. If present, it MUST contain a valid email address.

          
            {
              "@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:

• Thing > CreativeWork > MediaObject > VideoObject
• Thing > CreativeWork > Movie
• Thing > CreativeWork > CreativeWorkSeries > TVSeries

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:

• The type MUST be set to a valid media item type.
• The @id property MUST be set and contain a valid media item ID.
• The name property MUST contain a valid non-empty string.
• The datePublished property MUST contain a string that is valid date or date time in ISO8601 format.
• The image property supports multiple values and MUST contain a maximum of 5 different media content images.
• The potentialAction property MUST be a valid media item action unless the object has an embedded watch action OR the item is embedded in a media feed broadcast event.
• The interactionStatistic property supports multiple values and if present it MUST contain a maximum of 3 media item interaction statistics.
• The contentRating property supports multiple values and if present it MUST contain a maximum of 3 valid media item content ratings.
• The isFamilyFriendly property MAY be present. If present it MUST contain a schema.org boolean property.
• The genre property supports multiple values and if present it MUST contain a maximum of 5 non-empty strings.
• The identifier property supports multiple values and if present it MUST contain a valid media item third party identifier set.
• If the media item type is a Movie then the user agent MUST also do the following:
  • The duration property MUST contain a string that is valid duration in ISO8601 format.
• If the media item type is a VideoObject then the user agent MUST also do the following:
  • The author property MUST contain a valid media item author.
  • The duration property is only required if the item is embedded in a media feed broadcast event otherwise it is optional. If present, it MUST contain a string that is valid duration in ISO8601 format.
• If the media item type is a TVSeries then the user agent MUST also do the following:
  • The episode property supports multiple values and if present it MUST contain valid media item episodes.
  • The containsSeason property supports multiple values and if present it MUST contain valid media item seasons.

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.

The user agent MUST validate every media feed broadcast event using the following steps:
• The type MUST be set to BroadcastEvent.
• The @id property MUST be set and contain a valid media item ID.
• The isLiveBroadcast property MUST contain a schema.org boolean property.
• The workPerformed property MUST contain a valid media feed item.
• The potentialAction property MUST be a valid media item action unless the object has an embedded watch action.
• The startDate property MUST contain a string that is valid date or date time in ISO8601 format.
• The endDate property MAY be present. If it is, it MUST contain a string that is valid date or date time in ISO8601 format.

          
            {
              "@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.

• The type MUST be set to WatchAction.
• The actionStatus property MAY be present. If present it MUST be one of the following:
  • https://schema.org/ActiveActionStatus for when the action is in progress.
  • https://schema.org/PotentialActionStatus for when the action has not been started.
  • https://schema.org/CompletedActionStatus for when the action is finished.
• If the actionStatus property is set to https://schema.org/ActiveActionStatus, then the startTime property MUST contain a valid time.
• The target property MUST contain a valid URL.

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:

• The type MUST be set to Rating.
• The author property MUST contain a valid non-empty string. This is the agency that issued the rating (e.g. MPAA). A list of known content rating agencies is available here.
• The ratingValue property MUST contain a valid non-empty string. This is the content rating that was issued.

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:

• The type MUST be set to InteractionCounter.
• The interactionType property MUST be unique within a media feed item and be one of the following:
  • https://schema.org/WatchAction for how many views this media feed item has.
  • https://schema.org/LikeAction for how many likes this media feed item has.
  • https://schema.org/DislikeAction for how many dislikes this media feed item has.
• The userInteractionCount property MUST contain a number. This can be either a JSON number or a string. This is the count of the interactions that happened.

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:

• The type MUST be set to Person.
• The name property MUST contain a valid non-empty string.
• The url property MAY be present If present, it MUST contain a valid URL.

Media Item Season

The media item season represents a season of TV episodes.

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

• The type MUST be set to TVSeason.
• The seasonNumber property MUST be a positive integer.
• The numberOfEpisodes property MUST be a positive integer.
• The episode property supports multiple values and if present it MUST contain valid media item episodes.

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:

• The type MUST be set to TVEpisode.
• The episodeNumber property MUST be a positive integer.
• The duration property MUST contain a string that is a valid duration in ISO8601 format.
• The name property MAY be present. If present, it MUST contain a valid non-empty string.
• The identifier property supports multiple values and if present it MUST contain a valid media item third party identifier set.
• The image property supports multiple values and if present it MUST contain a maximum of 5 valid media content images.
• The potentialAction property MUST contain a valid media item action.

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:

• The type MUST be set to ImageObject.
• The width property MUST contain a positive integer that is the width of the image in pixels.
• The height property MUST contain a positive integer that is the height of the image in pixels.
• The embedUrl property or url property MUST contain a valid URL.
• The additionalProperty property MAY be present. If present, it must contain a PropertyValue object and the user agent MUST use the following steps to validate it:
  • The type MUST be set to PropertyValue.
  • The name property MUST contain contentAttributes.
  • The value property supports multiple values and if present it MUST contain non empty strings. These are the content attributes for the media image.

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:

• One background suitability attribute.
• One title attribute.
• Optionally, a predominant figure position attribute.
• Optionally, the transparent background attribute.

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:

• Optionally, a content type attribute.
• Optionally, a recommended use attribute.
• Optionally, a title attribute.
• Optionally, a background suitability attribute.
• Optionally, a predominant figure position attribute.
• Optionally, the transparent background attribute.

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:

• iconic: The image is an artistic render of the show. This is usually a poster or banner.
• sceneStill: The image is a still/framegrab from the media item.

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:

• poster: The image is a poster image for the show.
• background: This image is suitable for being used as a background and does not contain text.

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:

• forDarkBackground: The image is suitable for use on a dark background.
• forLightBackground: The image is suitable for use on a light background.

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:

• hasTitle: The image includes the title of the media item or website.
• noTitle: The image does not include the title.

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:

• centered: The predominant figure is positioned at the center of the image.
• rightCentered: The predominant figure is positioned to the right of the image and the left side is empty and can be used for text overlays.
• leftCentered: The predominant figure is positioned to the left of the image and the left side is empty and can be used for text overlays.

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:

• The type MUST be set to PropertyValue.
• The propertyID property contains the third party identifier name which MUST be a non-empty string.
• The value property MUST contain a non-empty string.

Boolean

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

• If the property is a JSON boolean type, then return the value
• If the property is a JSON string type then:
  • If the string value equals https://schema.org/True, then return true
  • If the string value equals https://schema.org/False, then return false
• Otherwise, return an error

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.

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

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

              ...
            }
          
        

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

              "genre": "Action",

              ...
            }
          
        

Type

The type property MUST be stored using @type for the key and it MUST store a single non-empty string.