HyperToc

HyperToc is a pending CreativeWork subtype for a chapter-style table of contents attached to a complex media work (a long-form video, a podcast episode, an audio lecture). It adds 2 properties: tocEntry (an array of HyperTocEntry items, each with a time range and title) and associatedMedia (the MediaObject this TOC belongs to).

Full example of schema.org/HyperToc json-ld markup

The markup is verified as valid with Rich Results Test from Google.

Highlight legend:Required by GoogleRecommendedOptional

schema.org/HyperToc

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HyperToc",
  "name": "Chapter index - Debugging JSON-LD in production",
  "associatedMedia": {
    "@type": "VideoObject",
    "name": "Debugging JSON-LD in production",
    "contentUrl": "https://xoocode.com/videos/debug-jsonld.mp4",
    "duration": "PT54M12S"
  },
  "tocEntry": [
    { "@type": "HyperTocEntry", "name": "Introduction", "startOffset": 0, "endOffset": 122 },
    { "@type": "HyperTocEntry", "name": "Common parser errors", "startOffset": 122, "endOffset": 438 },
    { "@type": "HyperTocEntry", "name": "Missing required properties", "startOffset": 438, "endOffset": 812 },
    { "@type": "HyperTocEntry", "name": "Enum values that look right but aren't", "startOffset": 812, "endOffset": 1286 },
    { "@type": "HyperTocEntry", "name": "URL vs @id confusion", "startOffset": 1286, "endOffset": 1704 },
    { "@type": "HyperTocEntry", "name": "When rich results silently vanish", "startOffset": 1704, "endOffset": 2230 },
    { "@type": "HyperTocEntry", "name": "Debugging with XooStructured", "startOffset": 2230, "endOffset": 2890 },
    { "@type": "HyperTocEntry", "name": "Q&A and wrap-up", "startOffset": 2890, "endOffset": 3252 }
  ]
}
</script>

HyperToc vs VideoObject.hasPart

VideoObject.hasPart with Clip is Google's path for Key Moments in video search results. HyperToc is a more general, spec-level TOC structure that also works for audio, podcasts, and non-video media. Use Clip inside VideoObject for Google Key Moments; use HyperToc for the broader, machine-readable TOC on any media type.

Minimal valid version

The smallest markup that still produces a valid HyperToc entity. Use it as the floor. Reach for the advanced example above when you want search engines and AI agents to understand more about your content.

schema.org/HyperToc (minimal)

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HyperToc",
  "name": "Chapter index",
  "associatedMedia": { "@type": "VideoObject", "name": "Debugging JSON-LD in production" },
  "tocEntry": [
    { "@type": "HyperTocEntry", "name": "Introduction", "startOffset": 0, "endOffset": 122 }
  ]
}
</script>

Google rich results this unlocks

Markup matching this example makes your page eligible for the following Google Search rich results. The primary target drives the required / recommended property classification in the advanced code block above.

No dedicated rich result (Clip drives Google Key Moments)
Google docs

Common HyperToc mistakes

Mistakes that pass validation but silently fail to earn rich results or mislead consumers walking the graph. Avoid these and your markup will be ahead of most sites in the wild.

HyperToc without associatedMedia

Wrong

HyperToc as a floating TOC with no MediaObject link

Right

Always populate associatedMedia with the VideoObject / AudioObject the TOC describes

A TOC without its media is meaningless. associatedMedia is the mandatory anchor.

Schema properties in this example

HyperToc CreativeWork name associatedMedia VideoObject contentUrl duration tocEntry HyperTocEntry startOffset endOffset Clip hasPart

About the example data

The chapter table of contents for a 54-minute Xoo Code lecture video on JSON-LD debugging, with 8 timestamped chapters.

Comments

Loading comments...