Define JSON Schema $refs for linking/embedding videos and linking documents

Created on 13 May 2025, 21 days ago

Overview

XB already has

  1. json-schema-definitions://experience_builder.module/image, which allows rendering an image
  2. json-schema-definitions://experience_builder.module/image-uri, which allows linking an image

The 3 missing $refs to use in SDCs' schemas:

  1. linking a video
  2. rendering ("embedding") a video
  3. linking a document
  4. 👈 (most) browsers can only natively render PDFs, all other document types require specialized embedding widgets — tackling that seems out of scope here?

Note that in core, the:

  • "document" media type allows txt rtf doc docx ppt pptx xls xlsx pdf odf odg odp ods odt fodt fods fodp fodg key numbers pages
  • "video" media type allows mp4
  • "remote video" media type allows YouTube + Vimeo

Proposed resolution

For the 3 missing concepts:

  1. Challenge: more often than not, you wouldn't link to a .mp4, .webm … URL, but you'd link to YouTube or Vimeo or …. How do we express that? 🤔 Seems like we'd need to draw inspiration from core's \Drupal\media\OEmbed\Resource, which has ::TYPE_LINK, ::TYPE_PHOTO, ::TYPE_RICH and ::TYPE_VIDEO.
  2. This pretty much requires an oembed URL, and then the oembed fetching to happen … inside the SDC itself? 🤔
  3. Linking to a document seems simple enough:
        "document-uri": {
          "title": "Document URL",
          "type": "string",
          "format": "uri-reference",
          "pattern": "^(/|https?://)?.*\\.(txt|rtf|doc|docx|ppt|pptx|xls|xlsx|pdf|odf|odg|odp|ods|odt|fodt|fods|fodp|fodg|key|numbers|pages)(\\?.*)?(#.*)?$"
        },
    

User interface changes

TBD

Feature request
Status

Active

Version

0.0

Component

Shape matching

Created by

🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @wim leers
  • 🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺

    @lauriii, do you agree that does not make sense to support, and the 3 remaining missing $refs in the issue summary would address all needs?

  • 🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺
  • 🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺

    @lauriii, also see the issue summary: do you want only (oEmbed) remote video, or also local video URLs?

    Added more detail to the oEmbed video proposal.

  • 🇫🇮Finland lauriii Finland

    I think we should express the uploaded videos as follows in schema.json:

    {
      "video": {
        "title": "video",
        "type": "object",
        "required": ["src"],
        "properties": {
          "src": {
            "title": "Video URL",
            "type": "string",
            "format": "uri"
          },
          "poster": {
            "title": "Poster image URL",
            "$ref": "json-schema-definitions://experience_builder.module/image-uri"
          },
          "width": {
            "title": "Video width",
            "type": "integer"
          },
          "height": {
            "title": "Video height",
            "type": "integer"
          },
          "autoplay": {
            "title": "Autoplay",
            "type": "boolean"
          },
          "loop": {
            "title": "Loop",
            "type": "boolean"
          },
          "muted": {
            "title": "Muted",
            "type": "boolean"
          },
          "controls": {
            "title": "Show controls",
            "type": "boolean"
          }
        }
      }
    }
    

    For oEmbed, I'm not sure we need the max width / max height here. It seems something that the component itself should handle? We may need to expose the height / width of the resource, as well as title which would make this shape as follows in schema.json:

    {
      "oembed_video": {
        "title": "oembed_video",
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": {
            "title": "oEmbed URL",
            "type": "string",
            "format": "uri",
            "contentMediaType": "application/oembed+json",
            "x-oembed-type": "video"
          },
          "width": {
            "title": "Video width",
            "type": "integer"
          },
          "height": {
            "title": "Video height",
            "type": "integer"
          },
          "title": {
            "title": "Video title",
            "type": "string"
          }
        }
      }
    }
    

    For documents, to display a link, we'd need a bit more than just the URI in the schema.json:

    {
      "document": {
        "title": "document",
        "type": "object",
        "required": ["src"],
        "properties": {
          "src": {
            "title": "Document URL",
            "$ref": "json-schema-definitions://experience_builder.module/document-uri"
          },
          "title": {
            "title": "Document title",
            "type": "string"
          },
          "description": {
            "title": "Document description",
            "type": "string"
          },
          "filename": {
            "title": "Filename",
            "type": "string"
          },
          "filesize": {
            "title": "File size",
            "type": "integer",
            "description": "File size in bytes"
          },
          "mimetype": {
            "title": "MIME type",
            "type": "string"
          }
        },
        "document-uri": {
          "title": "Document URL",
          "type": "string",
          "format": "uri-reference",
          "pattern": "^(/|https?://)?.*\\.(txt|rtf|doc|docx|ppt|pptx|xls|xlsx|pdf|odf|odg|odp|ods|odt|fodt|fods|fodp|fodg|key|numbers|pages)(\\?.*)?(#.*)?$"
        }
      },
    }
    
Production build 0.71.5 2024