JSON-LD Structure - Documentation

This documentation describes the JSON-LD data structure compliant with Schema.org that will be returned in the jsonLd key.

Overview

The main structure is an ItemList object that contains a list of videos (VideoObject). Each video can be divided into multiple clips (Clip), and each clip can be associated with products (Product) or contain a redirect URL.

Main Structure

{
  "jsonLd": {
    "@context": "https://schema.org",
    "@type": "ItemList",
    "name": "string",
    "numberOfItems": number,
    "itemListElement": [...]
  }
}

Data Types

ItemList

The root structure that contains the list of videos.

Property	Type	Required	Description
`@context`	`string`	✅	JSON-LD Schema.org context (always `"https://schema.org"`)
`@type`	`string`	✅	Schema.org type (always `"ItemList"`)
`name`	`string`	✅	Name of the video list
`numberOfItems`	`number`	✅	Total number of videos in the list
`itemListElement`	`ListItem[]`	✅	Array containing the list items

ListItem

Represents an item in the list (a video).

Property	Type	Required	Description
`@type`	`string`	✅	Schema.org type (always `"ListItem"`)
`position`	`number`	✅	Position of the item in the list (starts at 1)
`item`	`VideoObject`	✅	The associated video object

VideoObject

Represents a complete video with its metadata.

Property	Type	Required	Description
`@type`	`string`	✅	Schema.org type (always `"VideoObject"`)
`name`	`string`	✅	Video title
`description`	`string`	✅	Detailed description of the video
`contentUrl`	`string`	✅	URL of the video file (URI format)
`encodingFormat`	`string`	✅	Encoding format (e.g., `"video/mp4"`)
`inLanguage`	`string`	✅	Language code (e.g., `"fr"`, `"en"`)
`thumbnailUrl`	`string`	✅	URL of the thumbnail image (URI format)
`duration`	`string`	✅	Duration in ISO 8601 format (e.g., `"PT5M30S"` for 5 minutes 30 seconds)
`uploadDate`	`string`	✅	Upload date in ISO 8601 format (e.g., `"2025-01-15T10:30:00Z"`)
`transcript`	`string`	❌	Text transcript of the video
`hasPart`	`Clip[]`	✅	Array of clips that compose the video

ISO 8601 Duration Format:

PT2M30S = 2 minutes 30 seconds
PT1H15M = 1 hour 15 minutes
PT45S = 45 seconds

Clip

Represents a segment or clip of a video.

Property	Type	Required	Description
`@type`	`string`	✅	Schema.org type (always `"Clip"`)
`name`	`string`	✅	Name of the clip
`startOffset`	`number`	✅	Start point of the clip in seconds
`endOffset`	`number`	✅	End point of the clip in seconds
`author`	`Person \| Organization`	❌	Author of the clip (see sections below)
`url`	`string`	❌	Redirect URL to content related to the video (URI format)
`subjectOf`	`Product[]`	❌	List of products associated with the clip

Note: A clip can have an author, a url, subjectOf, a combination of these elements, or none of them.

Person

Represents a person (used for clips from Instagram).

Property	Type	Required	Description
`@type`	`string`	✅	Schema.org type (always `"Person"`)
`name`	`string`	✅	Name of the person
`sameAs`	`string`	❌	Instagram profile URL (URI format)

Organization

Represents an organization or company (used for non-Instagram clips).

Property	Type	Required	Description
`@type`	`string`	✅	Schema.org type (always `"Organization"`)
`name`	`string`	✅	Name of the organization
`url`	`string`	❌	Company website URL (URI format)

Product

Represents a product associated with a clip.

Property	Type	Required	Description
`@type`	`string`	✅	Schema.org type (always `"Product"`)
`name`	`string`	✅	Product name
`description`	`string`	❌	Detailed product description
`url`	`string`	❌	Product page URL (URI format)
`image`	`string`	❌	Product image URL (URI format)
`gtin`	`string`	❌	Global Trade Item Number (GTIN-8, GTIN-12, GTIN-13, or GTIN-14)
`offers`	`Offer`	❌	Product offer/price information

Offer

Represents a commercial offer for a product.

Property	Type	Required	Description
`@type`	`string`	✅	Schema.org type (always `"Offer"`)
`priceCurrency`	`string`	❌	ISO currency code (e.g., `"EUR"`, `"USD"`)
`price`	`string \| number`	❌	Product price (can be a string or a number)
`url`	`string`	❌	Purchase page URL (URI format)

Complete Example

{
  "jsonLd": {
    "@context": "https://schema.org",
    "@type": "ItemList",
    "name": "Video Gallery",
    "numberOfItems": 1,
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "item": {
          "@type": "VideoObject",
          "name": "Makeup Tutorial",
          "description": "Learn the basics",
          "contentUrl": "https://example.com/video.mp4",
          "encodingFormat": "video/mp4",
          "inLanguage": "fr",
          "thumbnailUrl": "https://example.com/thumbnail.jpg",
          "duration": "PT5M30S",
          "uploadDate": "2025-01-15T10:30:00Z",
          "transcript": "Hello and welcome...",
          "hasPart": [
            {
              "@type": "Clip",
              "name": "Introduction",
              "startOffset": 0,
              "endOffset": 30,
              "author": {
                "@type": "Person",
                "name": "Marie Dubois",
                "sameAs": "https://www.instagram.com/marie_beauty"
              },
              "url": "https://example.com/articles/intro",
              "subjectOf": [
                {
                  "@type": "Product",
                  "name": "Moisturizing Cream",
                  "description": "Face cream",
                  "url": "https://example.com/products/cream",
                  "image": "https://example.com/images/cream.jpg",
                  "gtin": "3614272049499",
                  "offers": {
                    "@type": "Offer",
                    "priceCurrency": "EUR",
                    "price": "24.99",
                    "url": "https://example.com/products/cream"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Use Cases

Clip with Person Author (Instagram)

{
  "@type": "Clip",
  "name": "Segment 1",
  "startOffset": 0,
  "endOffset": 30,
  "author": {
    "@type": "Person",
    "name": "John Doe",
    "sameAs": "https://www.instagram.com/johndoe"
  }
}

Clip with Organization Author (Company)

{
  "@type": "Clip",
  "name": "Segment 1",
  "startOffset": 0,
  "endOffset": 30,
  "author": {
    "@type": "Organization",
    "name": "My Company",
    "url": "https://www.my-company.com"
  }
}

Clip with Redirect URL

{
  "@type": "Clip",
  "name": "Segment 1",
  "startOffset": 0,
  "endOffset": 30,
  "url": "https://example.com/related-content"
}

Clip with Products

{
  "@type": "Clip",
  "name": "Segment 1",
  "startOffset": 0,
  "endOffset": 30,
  "subjectOf": [
    {
      "@type": "Product",
      "name": "Product 1",
      "description": "Product description",
      "url": "https://example.com/product1",
      "image": "https://example.com/image1.jpg",
      "gtin": "3614272049499",
      "offers": {
        "@type": "Offer",
        "priceCurrency": "EUR",
        "price": "99.99",
        "url": "https://example.com/product1"
      }
    }
  ]
}

Important Notes

Schema.org Compliance: This structure is compliant with Schema.org specifications, which enables better indexing by search engines.
Date Format: Dates must be in ISO 8601 format with timezone (e.g., "2025-01-15T10:30:00Z").
Duration Format: Durations must be in ISO 8601 format (e.g., "PT5M30S").
URLs: All URLs must be valid URIs (starting with http:// or https://).
Optional Properties: Properties marked as optional (❌) can be omitted if they are not available.
Clip Author: A clip can have an author of type Person (for Instagram) or Organization (for companies), but not both.
Multiple Products: A clip can be associated with multiple products via the subjectOf array.