HVML

Hypervideo Markup Language

Specification

Last updated:

Rationale

Rationale

The Elements of HVML

The hvml Element

Contexts

  • Documents

Content Attributes

  • XML Root Node Attributes (e.g. xmlns)
  • XML Global Attributes (e.g. xml:id)

Definition

This is the root node. Limit one per document. Required.

Authoring

When using the XML serialization of HVML, one and only one XML prolog—e.g. <?xml version="1.0" encoding="UTF-8"?>—SHOULD be specified before the root node, for the benefit of XML parsers. If an HVML document omits the prolog, or omits either of the two prolog attributes, the document will be assumed to be an XML 1.0 document, and/or encoded using UTF-8, respectively.

Examples

  1. A barebones configuration.

    Note: Although an attribute-less root element is conforming, this does not provide much context for the document’s contents, and is not recommended in most cases.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml></hvml>

  2. A configuration setting document language to English.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xml:lang="en"></hvml>

  3. A configuration specifying the HVML namespace, and setting document language to French.

    Note: This is the recommended minimum configuration (with document language set appropriately).

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="fr"></hvml>

The title Element

Contexts

  • As a child of video
  • As a child of venue

Definition

Represents the canonical title for a given video or other creative work.

A canonical title SHOULD be what the resource in question has been named by its author, without any additional information that might be present upon displaying it to a user.

For example, a video appearing in the search results of a video portal site might have the presentational title “Last Day of Summer ’16 | Hugh’s Vlog”. The canonical title would be “Last Day of Summer ’16”. The text after the spacer “ | ” denotes the name of the series, and should not be included in an episode’s <title>, as it can usually be inferred from the context of the larger document, if authored correctly. To illustrate:

<?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
  <group xml:id="hughs-vlog" type="series">
    <title>Hugh’s Vlog</title>
    <!-- … -->
    <group xml:id="season-02" type="series">
      <!-- … -->
      <video xml:id="ep-15">
        <title>Last Day of Summer ’16</title>
      </video>
    </group>
  </group>
</hvml>

Given this markup, an HVML-aware CMS could automatically generate the display title “Last Day of Summer ’16 | Hugh’s Vlog”, or alternatively display titles such “Hugh’s Vlog #15: Last Day of Summer ’16”.

However, in the case where one is simply archiving the data of a non-HVML-aware site, which does not have a separate metadata field for series titles, it would be appropriate to include the entire presentational title in a <title>.

These two use cases can even be covered in the same document without conflict:

<?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
  <group xml:id="hughs-vlog" type="series">
    <title>Hugh’s Vlog</title>
    <!-- … -->
    <group xml:id="season-02" type="series">
      <!-- … -->
      <video xml:id="ep-15">
        <title>Last Day of Summer ’16</title>
        <showing scope="release" datetime="2016-09-10">
          <venue type="site" datetime="04:28:03.000Z">
            <entity site="https://www.youtube.com/">YouTube</entity>
            <uri>https://www.youtube.com/watch?v=YvP_2qi5XuA</uri>
            <title>Last Day of Summer ’16 | Hugh’s Vlog</title>
          </venue>
        </showing>
      </video>
    </group>
  </group>
</hvml>

The video Element

Contexts

  • As a child of hvml

Content Attributes

  • XML Global Attributes (e.g. xml:id)

  • type

    Required:
    No
    Type:
    xs:string
    Values:
    narrative
    ad
    personal
    historical

Definition

Represents a single theatrical film, TV show episode, advertisement, home movie, news segment, piece of archival footage, animated GIF, or any other motion picture (i.e., visual media with fixed changes along a temporal axis).

Authoring

The type attribute accepts one or more of the following values as a space-separated list:

  • narrative, indicating that the video in question is a fictional film, usually with a distinct story arc, of any length;
  • documentary, indicating that the video in question is an investigative, introspective, contemplative, or otherwise educational film of any length;
  • ad, indicating that the video in question is primarily an advertisement for a product, service, company, or individual, i.e. a commercial. This designation alone is not suitable for videos that merely feature embedded advertisements such as product placement, paid reviews, “ad reads”, or other sponsorships, but are otherwise noncommercial in nature;
  • personal, indicating that the video in question is primarily from the perspective of an individual, family, friend group, or other close association, and may lack serious artistic direction, such as home movies, or “user-generated content” uploaded to a third-party website;
  • historical, indicating that the video in question is pertinent to some aspect of history, such as a news program or segment, or miscellaneous footage belonging to a library, archive, or personal collection.

These values can be combined, in any order, in the following ways to derive additional meanings:

  • narrative documentary: a documentary with fictionalized elements. This does not refer to disputed or exaggerated claims made in investigative journalism, but rather to hybrid fiction–nonfiction, such as a biopic portrayed by actors that also includes interviews with real-life people relating to the story;
  • personal documentary: a self-authored vlog (video blog) episode;
  • personal ad: an advertisement for oneself, such as a political campaign commercial, or a video job application;
  • documentary ad: an advertisement presented as educational content about a particular topic, e.g. “native advertising”;
  • historical ad: a commercial for a defunct product or service, or a commercial that is no longer running;
  • historical personal: a personal video that one has “archived” in order to exclude it or separate it from a list of their recent content in some interface.

When using HVML’s XML serialization in an HTML context, be aware that the User-agent, typically a Web browser, will interpret un-namespaced <video>s to be instances of HTML’s embedded video player element of the same name. This may result in the browser performing unnecessary work, such as populating the tag with extraneous DOM properties.

To minimize the potential for unwanted browser behavior, HTML’s media-specific attributes (as defined by the WHATWG Living Standard) are reserved attributes in HVML, and will throw errors in conformance checkers if present: autoplay, buffered, controls, crossorigin, height, loop, muted, preload, poster, src, width, playsinline, or any other attribute defined therein.

When using HVML’s XML serialization in an XHTML context (i.e., served with Content-Type: application/xhtml+xml), unwanted browser behavior can be avoided merely by setting the appropriate namespace, as in one of the following configurations:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="UTF-8" />
  </head>
  <body>
    <video>
      <!-- HTML video definition -->
    </video>
    <hvml xmlns="https://hypervideo.tech/hvml#">
      <video>
        <!-- HVML video definition -->
      </video>
    </hvml>
  </body>
</html>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:hvml="https://hypervideo.tech/hvml#">
  <head>
    <meta charset="UTF-8" />
  </head>
  <body>
    <video>
      <!-- HTML video definition -->
    </video>
    <hvml:hvml>
      <hvml:video>
        <!-- HVML video definition -->
      </hvml:video>
    </hvml:hvml>
  </body>
</html>

The series Element

Contexts

  • As a child of hvml
  • As a child of series

Content Attributes

  • XML Global Attributes (e.g. xml:id)

  • order

    Required:
    No
    Type:
    xs:string
    Values:
    ascending
    descending
    custom

Definition

  • As a child of hvml: Denotes an episodic story, such as a [Web] television show, miniseries, or theatrical anthology.
  • As a child of another series: Denotes a distinct arc of an episodic story, such as a “season” (US parlance) or “series” (UK parlance). Throughout this specification, the term “season” will be used for this use case to avoid ambiguity.

series is for grouping works that canonically relate to one another, as set forth by their author(s). It is not appropriate for marking up independent curation, i.e. putting together an array of standalone works. For that, see group [standalone]

Examples

  1. Marking up a show with three episodes.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <series xml:id="hughs-vlog">
   <title>Hugh’s Vlog</title>
   <video xml:id="episode-01"></video>
   <video xml:id="episode-02"></video>
   <video xml:id="episode-03"></video>
 </series>
</hvml>

    Note that the <video>s’ xml:id attributes are just for human-readability. They are optional and do not have to specify episode numbers. Because this <series> omits the order attribute, its <video>s are understood to be in ascending chronological order, and can be numbered automatically by a User-agent.

  2. Marking up a show with three episodes, in reverse chronological order.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
  <series xml:id="hughs-vlog" order="descending">
    <title>Hugh’s Vlog</title>
    <video xml:id="episode-03"></video>
    <video xml:id="episode-02"></video>
    <video xml:id="episode-01"></video>
  </series>
</hvml>

  3. Marking up a show with six episodes, spread out over two seasons.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <series xml:id="hughs-vlog">
   <title>Hugh’s Vlog</title>
   <series xml:id="season-01">
     <video xml:id="episode-01"></video>
     <video xml:id="episode-02"></video>
     <video xml:id="episode-03"></video>
   </series>
   <series xml:id="season-02">
     <video xml:id="episode-04"></video>
     <video xml:id="episode-05"></video>
     <video xml:id="episode-06"></video>
   </series>
 </series>
</hvml>

    Note that a User-agent might choose to list the episodes in Season 2 as “Episode 4”, “Episode 5”, and “Episode 6”, respectively; or “Season 2: Episode 1”, “Season 2: Episode 2”, and “Season 2: Episode 3” respectively, depending on design decisions.

Parsing

A series’ children SHOULD be ordered chronologically, so that simply retrieving a list of them would not require additional computation to sort in the majority of use cases. This is referred to as pre-ordering on behalf of the document author.

If the order attribute is present and set to the exact string ascending, then the series’ children MUST be understood as pre-ordered from the earliest date of publication to the latest date of publication.

If the order attribute is present and set to the exact string descending, then the series’ children MUST be understood as pre-ordered from the latest date of publication to the earliest date of publication.

If the order attribute is present and set to the exact string custom, then the series’ children SHOULD NOT be understood as pre-ordered in a consistently linear fashion. User-agents wanting to sort a series’ children by date anyway in this case should look for grandchild published elements. If a given child has no published child, its place in a sort is left to the User-agent.

If the order attribute is present but set to a non-empty string that the User-agent doesn’t recognize, the pre-order defaults to custom to gracefully degrade in the event of future permissible values.

If the order attribute is not present, or is present but empty, the pre-order defaults to ascending.

The group Element

Contexts

  • As a child of series
  • As a child of group

Content Attributes

  • XML Global Attributes (e.g. xml:id)

  • type

    Required:
    No
    Type:
    xs:string
    Values:
    curation

Definition

An arbitrary grouping.

Examples

  1. Marking up a curated list of episodes.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <series xml:id="hughs-vlog">
   <title>Hugh’s Vlog</title>
   <group xml:id="best-of-hughs-vlog" type="curation">
     <video xml:id="episode-01"></video>
     <video xml:id="episode-03"></video>
     <video xml:id="episode-05"></video>
   </group>
 </series>
</hvml>

  2. Marking up a curated list of episodes from a previously-defined set of episodes.

    For this we must import the xlink namespace on the root node, in order to use xlink:href to target specific xml:ids.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml
 xmlns="https://hypervideo.tech/hvml#"
 xmlns:xlink="http://www.w3.org/1999/xlink"
 xml:lang="en"
>
 <series xml:id="hughs-vlog">
   <title>Hugh’s Vlog</title>
   <series xml:id="season-01">
     <video xml:id="episode-01"></video>
     <video xml:id="episode-02"></video>
     <video xml:id="episode-03"></video>
     <video xml:id="episode-04"></video>
     <video xml:id="episode-05"></video>
   </series>
   <group xml:id="best-of-hughs-vlog" type="curation">
     <video xml:id="best-of-01" xlink:href="#episode-01"></video>
     <video xml:id="best-of-02" xlink:href="#episode-03"></video>
     <video xml:id="best-of-03" xlink:href="#episode-05"></video>
   </group>
 </series>
</hvml>

The rating Element

Contexts

  • As a child of glossary
  • As a child of rating

Content Attributes

  • XML Global Attributes (e.g. xml:id)

  • type

    Required:
    Maybe
    Type:
    xs:string
    Values:
    drugs
    nudity
    profanity
    sex
    suggestive-dialogue
    violence
    custom

  • code

    Required:
    No
    Type:
    xs:string
    Purpose:
    Sets a locally-unique identifier for the rating definition or one of its components.

  • maturity

    Required:
    No
    Type:
    xs:nonNegativeInteger
    Values:
    Range: 0–1 inclusive
    Purpose:
    Sets the relative maturity level of a rating definition.

  • color

    Required:
    No
    Type:
    xs:string
    Values:
    Any valid CSS color value
    Purpose:
    Sets the canonical color representation for the rating level, typically indicating “severity” by way of color warmth. Does not guarantee faithful rendering by a User-agent, which may decide on other design treatments such as monochrome or high-contrast.

Definition

A content rating with which an Author can classify a piece of content.

Authoring

The type attribute accepts one or more values as a space-separated list. When it contains a list, any or all of the values may apply to the definition, depending on the rules of the rating system.

If the type attribute is not present, or is present but empty, any or all of the <rating>’s possible types, excluding custom, may apply.

If a rating element has another <rating> as its parent, and the parent has a type attribute, then the child’s type attribute is inherited from the parent and is optional. Otherwise, it is required.

If both the parent and the child <rating>s have types that don’t match, then the child <rating>’s type takes precedence.

The maturity attribute defines the rating level relative to other ratings on a scale from 0 to 1 inclusive, 0 meaning “little to no maturity required” to safely consume a piece of content (however that is defined by the rating system); 1 meaning “a lot of maturity required”.

If maturity is omitted and there is more than one <rating> for a given <glossary>, then maturity is calculated automatically as an even distribution according to the top-down source order starting at 0. So, for a set of five <rating>s without maturitys set, their maturitys would be calculated by a User-agent as 0, 0.25, 0.5, 0.75, and 1 respectively. This is referred to as pre-ordering on behalf of the Author.

If maturity is omitted on the only <rating> for a given <glossary>, then the <rating> represents a binary rating rating and its maturity is equal to 1.

Examples

  1. Defining the content rating for a video.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <video type="feature" xml:id="drive-2011">
   <title>Drive</title>
   <published>2011-05-20</published>
   <rating code="R" />
 </video>
</hvml>

    On its own, all this says is that someone has used the letter “R” to indicate the recommended maturity level for the video’s audience. While most US moviegoers might understand this to be an abbreviation for “Restricted” as assigned by the MPAA, its meaning and origin may not be clear to non-US audiences or robots.

  2. In order to provide better context, the previous example can be expanded to:

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <video type="feature" xml:id="drive-2011">
   <title>Drive</title>
   <published>2011-05-20</published>
   <rating code="R" maturity="0.75">
     <entity>
       <name>Motion Picture Association of America</name>
       <nickname>MPAA</nickname>
       <site title="MPAA.org">https://www.mpaa.org</site>
     </entity>
     <title>Restricted</title>
     <subtitle>Children Under 17 Require Accompanying Parent or Adult Guardian</subtitle>
     <description>An R-rated motion picture, in the view of the Rating Board, contains some adult material. An R-rated motion picture may include adult themes, adult activity, hard language, intense or persistent violence, sexually-oriented nudity, drug abuse or other elements, so that parents are counseled to take this rating very seriously. Children under 17 are not allowed to attend R-rated motion pictures unaccompanied by a parent or adult guardian. Parents are strongly urged to find out more about R-rated motion pictures in determining their suitability for their children. Generally, it is not appropriate for parents to bring their young children with them to R-rated motion pictures.</description>
     <reason type="violence profanity nudity">strong brutal bloody violence, language and some nudity</reason>
   </rating>
 </video>
</hvml>

    However, this would be a lot to include in a document or database describing multiple “R”-rated movies, so it is usually more economical to outsource most of the definition to a glossary, and link to that from the video’s local rating.

  3. By linking via code, the applied rating references all of the glossary rating’s data, as if it were contained inline.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <meta>
   <glossary xml:id="mpaa" for="rating" party="3rd">
     <title>MPAA Ratings</title>
     <scheme>https://filmratings.com/Content/Downloads/rating_rules.pdf</scheme>
     <rating xml:id="mpaa-g" code="G" maturity="0">
       <title>General Audiences</title>
       <subtitle>General Audiences</subtitle>
     </rating>
     <!-- … -->
     <rating xml:id="mpaa-r" code="R" maturity="0.75">
       <title>Restricted</title>
       <subtitle>Children Under 17 Require Accompanying Parent or Adult Guardian</subtitle>
     </rating>
   </glossary>
 </meta>
 <video type="feature" xml:id="drive-2011">
   <title>Drive</title>
   <published>2011-05-20</published>
   <rating code="R">
     <reason type="violence profanity nudity">strong brutal bloody violence, language and some nudity</reason>
   </rating>
 </video>
</hvml>

  4. To disambiguate between clashing codes, the applied rating uses glossary scoping.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <meta>
   <glossary xml:id="mpaa" for="rating" party="3rd">
     <title>MPAA Ratings</title>
     <scheme>https://filmratings.com/Content/Downloads/rating_rules.pdf</scheme>
     <rating xml:id="mpaa-r" code="R" maturity="0.75">
       <title>Restricted</title>
       <subtitle>Children Under 17 Require Accompanying Parent or Adult Guardian</subtitle>
     </rating>
   </glossary>
   <glossary xml:id="joe-cool" for="rating" party="3rd">
     <title>Joe Cool’s Ratings</title>
     <scheme>http://peanuts.wikia.com/wiki/Joe_Cool</scheme>
     <rating xml:id="joe-cool-r" code="R" maturity="0">
       <title>Really Cool</title>
       <subtitle>Children Under 17 Don’t Require Jack, Man.</subtitle>
     </rating>
   </glossary>
 </meta>
 <video type="feature" xml:id="drive-2011">
   <title>Drive</title>
   <published>2011-05-20</published>
   <rating glossary="#mpaa" code="R">
     <reason type="violence profanity nudity">strong brutal bloody violence, language and some nudity</reason>
   </rating>
 </video>
</hvml>

  5. Alternatively, ratings can link to glossary definitions by ID. This requires importing the xlink namespace on the root node.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml
 xmlns="https://hypervideo.tech/hvml#"
 xmlns:xlink="http://www.w3.org/1999/xlink"
 xml:lang="en"
>
 <meta>
   <glossary xml:id="mpaa" for="rating" party="3rd">
     <title>MPAA Ratings</title>
     <scheme>https://filmratings.com/Content/Downloads/rating_rules.pdf</scheme>
     <rating xml:id="mpaa-g" code="G" maturity="0">
       <title>General Audiences</title>
       <subtitle>General Audiences</subtitle>
     </rating>
     <!-- … -->
     <rating xml:id="mpaa-r" code="R" maturity="0.75">
       <title>Restricted</title>
       <subtitle>Children Under 17 Require Accompanying Parent or Adult Guardian</subtitle>
     </rating>
   </glossary>
 </meta>
 <video type="feature" xml:id="drive-2011">
   <title>Drive</title>
   <published>2011-05-20</published>
   <rating xlink:href="#mpaa-r">
     <reason type="violence profanity nudity">strong brutal bloody violence, language and some nudity</reason>
   </rating>
 </video>
</hvml>

  6. Defining a glossary of three profanity content ratings, on a scale from least profane to most profane.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <glossary xml:id="yt" for="ratings">
   <title>YouTube Content Rating</title>
   <scheme>https://support.google.com/youtube/answer/146399?hl=en</scheme>
   <rating type="profanity">
     <rating code="L-" color="green">
       <title>None</title>
     </rating>
     <rating code="L" color="yellow">
      <title>Strong language</title>
    </rating>
     <rating code="L+" color="red">
       <title>Explicit language</title>
     </rating>
   </rating>
 </glossary>
</hvml>

  7. Defining a glossary of three profanity content ratings, on a scale from least profane to most profane, with explicit maturity ranking.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <glossary xml:id="yt" for="ratings">
   <title>YouTube Content Rating</title>
   <scheme>https://support.google.com/youtube/answer/146399?hl=en</scheme>
   <rating type="profanity">
     <rating code="L-" maturity="0" color="green">
       <title>None</title>
     </rating>
     <rating code="L" maturity="0.5" color="yellow">
      <title>Strong language</title>
    </rating>
     <rating code="L+" maturity="1" color="red">
       <title>Explicit language</title>
     </rating>
   </rating>
 </glossary>
</hvml>

  8. Defining a binary content rating, with an implied maturity of 1.

    <?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
 <glossary xml:id="pal" for="ratings">
   <title>Parental Advisory Label</title>
   <scheme>https://www.riaa.com/resources-learning/pal-standards/</scheme>
   <rating type="profanity sex violence drugs" code="PAL">
     <title>Parental Advisory Label</title>
   </rating>
 </glossary>
</hvml>

Parsing

If the type attribute is present and set to an unrecognized, non-empty string, interpret the type as being set to the exact string custom, to gracefully degrade in the event of future permissible values.

If the type attribute is present and set to the exact string custom, then the <rating> has nonstandard semantics which the User-agent MAY infer from heuristics.

The verdict Element

Contexts

  • As a child of glossary
  • As a child of group

Content Attributes

  • XML Global Attributes (e.g. xml:id)

  • code

    Required:
    No
    Type:
    xs:string

  • rank

    Required:
    No
    Type:
    xs:nonNegativeInteger
    Values:
    Range: 0–1 inclusive

Definition

A predefined verdict with which a reviewer can rank a piece of content.

Examples

1.

<?xml version="1.0" encoding="UTF-8"?>
<hvml xmlns="https://hypervideo.tech/hvml#" xml:lang="en">
  <glossary xml:id="nstv" for="score" party="1st">
    <title>No Spoon TV Verdicts</title>
    <group>
      <verdict xml:id="nstv-u" code="U" rank="0">
        <title>Unwatchable</title>
      </verdict>
      <!-- … -->
      <verdict xml:id="nstv-ma" code="Ma" rank="1">
        <title>Masterpiece</title>
      </verdict>
    </group>
  </glossary>
</hvml>

Glossary of Terms

empty string
Any of NULL, the empty string, or pure whitespace
non-empty string
Any sequence of characters excluding NULL, the empty string, and pure whitespace
locally-unique identifier
A sequence of characters used to identify an element subtree that does not recur as an identifier within its nearest scoped ancestor, such as glossary, but may recur beyond that boundary.