XooCode(){

MediaObject

MediaObject is a CreativeWork subtype for any media file: video, audio, image, PDF, spreadsheet, or any downloadable/streamable file. With 20 properties of its own, it covers the technical details of a media file: contentUrl (where to download it), encodingFormat (MIME type), contentSize (file size), duration (for audio/video), width/height (for images/video), and uploadDate.

The type hierarchy is Thing → CreativeWork → MediaObject. Most of the time, use a specific subtype: VideoObject for video, AudioObject for audio, ImageObject for images. Use generic MediaObject for files that are not video, audio, or images: PDFs, spreadsheets, ZIP archives, 3D models.

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

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

Highlight legend:Required by GoogleRecommendedOptional
schema.org/MediaObject
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "MediaObject",
  "name": "The ROI of Structured Data (PDF)",
  "description": "Downloadable PDF version of the Xoo Code whitepaper on structured data ROI.",
  "contentUrl": "https://xoocode.com/reports/roi-structured-data.pdf",
  "encodingFormat": "application/pdf",
  "contentSize": "2.4 MB",
  "uploadDate": "2026-03-01",
  "width": { "@type": "QuantitativeValue", "value": "612", "unitCode": "E37" },
  "height": { "@type": "QuantitativeValue", "value": "792", "unitCode": "E37" },
  "inLanguage": "en",
  "requiresSubscription": false,
  "encodesCreativeWork": {
    "@type": "DigitalDocument",
    "name": "The ROI of Structured Data",
    "url": "https://xoocode.com/reports/roi-structured-data"
  },
  "author": { "@id": "https://xoocode.com#organization" }
}
</script>

contentUrl and encodingFormat

contentUrl is the direct URL to the file itself (not the page about the file). encodingFormat is the MIME type: "application/pdf", "video/mp4", "audio/mpeg", "image/jpeg". Google needs both to verify the file exists and determine how to handle it.

requiresSubscription

requiresSubscription takes a Boolean or MediaSubscription object. Set it to true (or a MediaSubscription with details) if the file is behind a paywall or requires a login. Google reads this to determine whether to show a "free" or "subscription required" indicator.

MediaObject vs CreativeWork

CreativeWork describes what the content IS (a report, a paper, a presentation). MediaObject describes the file that contains it (a PDF, a PPTX, an MP4). A research paper (ScholarlyArticle) might have a MediaObject for its PDF download. Both can exist: the article entity describes the content, the MediaObject describes the downloadable file.

Minimal valid version

The smallest markup that still produces a valid MediaObject 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/MediaObject (minimal)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "MediaObject",
  "name": "The ROI of Structured Data (PDF)",
  "contentUrl": "https://xoocode.com/reports/roi-structured-data.pdf",
  "encodingFormat": "application/pdf",
  "contentSize": "2.4 MB",
  "description": "PDF whitepaper on structured data ROI."
}
</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 (use subtypes for media-specific results)
    Google docs

Common MediaObject 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.

  1. 01

    Using MediaObject for a video or audio file

    Wrong
    "@type": "MediaObject" for an MP4 video
    Right
    "@type": "VideoObject" for video, "AudioObject" for audio, "ImageObject" for images

    The subtypes trigger specific rich results: VideoObject gets the video thumbnail, AudioObject gets the podcast result. Generic MediaObject does not. Use it only for non-media files like PDFs and documents.

  2. 02

    contentUrl pointing to the page, not the file

    Wrong
    "contentUrl": "https://xoocode.com/reports/roi-structured-data" (the HTML page)
    Right
    "contentUrl": "https://xoocode.com/reports/roi-structured-data.pdf" (the actual file)

    contentUrl is the direct URL to the file itself, not the page that hosts or describes it. The page URL goes in the url property. contentUrl is what a download link would point to.

Schema properties in this example

MediaObjectCreativeWorknamedescriptioncontentUrlencodingFormatcontentSizeuploadDatewidthheightQuantitativeValueinLanguagerequiresSubscriptionencodesCreativeWorkDigitalDocumentauthor

About the example data

The downloadable PDF of the ROI of Structured Data whitepaper, the media file for the DigitalDocument.

Comments

Loading comments...

Leave a comment