JSON-LD Schema.org: Structuring Multiple Media on a Single Page

Dealing with dynamic content, especially large lists like search results featuring multiple videos or images on one page, often confuses developers when applying structured data using JSON-LD and Schema.org. The core difficulty isn't defining a single item; it’s defining the relationship between the container (the page) and the many items within it.

The solution lies in understanding how Schema.org supports collections and arrays. You don't define each video or image individually as top-level entities if they all belong to a singular context. Instead, you use array notation to group related objects under a parent entity.

The Strategy: Utilizing Arrays for Collections

When you have 50 videos on a search results page, the primary @type should describe the page itself (e.g., WebPage or perhaps SearchResultsPage). Within that page object, you define properties that hold collections of related media. For example, instead of defining 50 separate VideoObject instances at the root level, you embed an array of these objects within a relevant property on your main page schema.

This approach maintains semantic accuracy while keeping the markup concise and highly readable for search engines.

Implementing Multiple Media with JSON-LD

Let’s look at how this translates into practice. If your goal is to mark up a results page that features multiple videos, you would define an array property within the main schema. This tells Google that these items are all components of the parent page context.

Consider a search results page. You want to indicate that this page contains a collection of video results.

Here is a conceptual example demonstrating how you would structure the JSON-LD:

{
    "@context": "https://schema.org",
    "@type": "WebPage",
    "name": "Top 50 Search Results for Tech Videos",
    "description": "A collection of videos related to recent technology trends.",
    "mainVideoResults": {
      "@type": "ItemList",
      "name": "Video Search Results",
      "itemListElement": [
        {
          "@type": "VideoObject",
          "name": "Video Title 1",
          "thumbnailUrl": "https://example.com/video1_thumb.jpg",
          "duration": "120s",
          "url": "https://example.com/video1"
        },
        {
          "@type": "VideoObject",
          "name": "Video Title 2",
          "thumbnailUrl": "https://example.com/video2_thumb.jpg",
          "duration": "95s",
          "url": "https://example.com/video2"
        }
        // ... up to 50 entries here
      ]
    }
  }
  

In this structure, the mainVideoResults property acts as a container. It uses the ItemList type, which is designed specifically for listing items. The actual videos are then placed inside the itemListElement array. This pattern allows you to scale indefinitely—whether you have 5 or 500 results, the structure remains valid and highly informative for crawlers.

Developer Best Practices and Scalability

From a development standpoint, handling this dynamically requires careful consideration of your backend logic. When working with frameworks like Laravel, where you are generating content based on database queries, ensuring that your Eloquent models correctly map to these complex JSON structures is crucial. You should avoid hardcoding large arrays directly into static files; instead, generate the JSON-LD payload dynamically during the rendering process.

For instance, when fetching results from a database, you would iterate through the result set and construct an array of video objects before serializing it into your final output. This keeps the data source (your database) separate from the structured markup generation. If you are building complex API endpoints or content management systems, leveraging robust tools—perhaps by using packages that streamline schema generation within Laravel applications—can significantly reduce the chance of structural errors when dealing with large, repetitive datasets.

The key takeaway is to think hierarchically: define what the page is, then define what collections exist on that page, and finally, define the individual items within those collections. This nested approach is how Schema.org is designed to handle complex, relational data effectively across large-scale content.

Stefan

SEO engineer and Laravel developer. Building tools to help Laravel applications rank higher in search results.