Rich Content Media

Resource descriptions, service descriptions, and legal document content are stored as HTML strings produced by the TipTap editor. Native apps must not treat these fields as plain text or as a generic WebView dump — images and videos use custom nodes with data-* attributes. This guide is the contract for rendering that HTML in iOS, Android, and other non-web clients.

Where this HTML appears

JSON:API type	Attribute	i18n attribute	Typical use
`resources`	`description`	`description_i18n`	Resource detail
`services`	`description`	`description_i18n`	Service / booking-option detail
`legal-documents`	`content`	`content_i18n`	Checkout, check-in, public legal page, signed PDF

Locale selection follows Accept-Language. The flat attribute is the resolved translation; *_i18n is the full map (admin only).

The same HTML shape is used in all three places. Implement one renderer and reuse it.

Storage format

Content is HTML, not TipTap JSON. Custom nodes serialize to semantic tags plus data-* attributes so non-JS clients still have a fallback. Allowed tags after server sanitization include h1–h3, p, br, strong, b, em, i, u, s, ul, ol, li, table, thead/tbody/tr/th/td, a, img, div, and iframe (video hosts only). script, style, and javascript: URLs are stripped on save.

Images

Images persist as a normal <img> with extra metadata:

<img
  class="tiptap-image"
  src="https://cdn.example.com/storage/images/description-images/original/abc.jpg"
  alt="Meeting room"
  loading="lazy"
  data-image-id="123"
  data-width="50%"
  data-align="center"
/>

Attribute	Required	Meaning
`src`	Yes	Absolute or root-relative URL of the uploaded image
`alt`	No	Accessible label
`data-image-id`	Yes for uploaded images	Internal `images` resource id
`data-width`	No	Display width: `25%`, `50%`, `75%`, `100%`, or a pixel value
`data-align`	No	`left`, `center`, or `right`

Native rendering

Render src with an image view. If src is root-relative (/storage/...), prefix the API origin.
Honor data-width: treat percentages as a fraction of the content column, not the device width if you have padded margins.
Apply data-align as horizontal alignment of the image block.
Use alt for VoiceOver / TalkBack.
Do not require data-image-id to display the image. It is for lifecycle tracking on the backend.

Prefer the src already present in the HTML. You do not need a second request to /api/v1/images/{id} just to show the picture.

Videos

Videos are not stored as <video> or as a live iframe. The editor persists a fallback link:

<a
  class="video-embed"
  data-video-embed="true"
  data-platform="youtube"
  data-video-id="dQw4w9WgXcQ"
  data-src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  data-embed-url="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
  data-thumbnail-url="https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
  data-width="640"
  data-height="360"
  data-aspect-ratio="16/9"
  title="Safety briefing"
  href="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  target="_blank"
  rel="noopener noreferrer"
>Link to video</a>

Older or sanitized content may instead look like:

<div class="video-embed" data-video-embed="true">
  <iframe
    src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
    width="640"
    height="360"
    allowfullscreen
    sandbox="allow-same-origin allow-scripts allow-presentation"
    referrerpolicy="no-referrer"
  ></iframe>
</div>

Detect a video node if any of these are true:

a[data-video-embed] or *[data-video-embed]
a.video-embed / div.video-embed
iframe whose src host is an allowed provider (see below)

Attributes

Attribute	Meaning
`data-platform`	`youtube`, `vimeo`, or `loom`
`data-video-id`	Provider video id
`data-src` / `href`	Canonical watch URL (open this in the system browser or in-app player)
`data-embed-url`	Iframe embed URL, already parameterized
`data-thumbnail-url`	Poster image, when the editor could resolve one
`data-aspect-ratio`	Usually `16/9`
`title`	Video title, when fetched

Supported providers

Platform	Watch URL examples	Embed host
YouTube	`youtube.com/watch?v=`, `youtu.be/`, `/shorts/`, `/embed/`	`www.youtube-nocookie.com`, `www.youtube.com`
Vimeo	`vimeo.com/{id}`, `player.vimeo.com/video/{id}`	`player.vimeo.com`
Loom	`loom.com/share/{id}`, `loom.com/embed/{id}`	`www.loom.com`

Only HTTPS embed hosts from that list are accepted by the API. Reject any other iframe host. YouTube thumbnail fallback when data-thumbnail-url is missing:

https://i.ytimg.com/vi/{videoId}/hqdefault.jpg

Vimeo and Loom thumbnails are only available when data-thumbnail-url is present (resolved via oEmbed at edit time).

How to render videos in a native app

Match the web TipTap renderer: thumbnail + play button first, load the player only after a tap.

Parse the node

Read data-src / href as the watch URL, data-embed-url as the player URL, and data-thumbnail-url as the poster. If you only have an iframe, derive the watch URL from the embed src.

Draw the poster

Show the thumbnail as a 16:9 cover image. If no thumbnail is available, use a neutral grey background (#6B7280). Center a circular play control (dark translucent disc, white triangle) on top.

Handle the tap

Preferred: replace the poster with an in-app player / WKWebView / WebView loaded with data-embed-url (add autoplay=1 after the user gesture). Fallback: open the watch URL in the system browser or YouTube / Vimeo / Loom app.

Always keep the plain URL

Under the poster, render the watch URL as a tappable text link. Signed PDFs do the same. This keeps the video reachable when embeds are blocked, offline, or inaccessible.

Layout

Default aspect ratio: 16:9 (data-aspect-ratio wins when present).
Width: fill the content column; do not exceed it.
The play control should stay visually centered on the poster.
Use title (or “YouTube / Vimeo / Loom video”) as the accessibility label of the play control.

Do not

Autoplay or preload the iframe on bind. That wastes bandwidth and breaks data-saving modes.
Execute arbitrary iframe hosts. Stick to the allow-list above.
Treat the anchor text (Link to video) as the only UI. Replace the node with the poster + URL treatment.

Files and entity links

Rich content may also include:

<a class="tiptap-file" data-type="file" data-file-id="{uuid}" href="https://.../files/{uuid}">filename.pdf</a>

<a class="entity-link" data-entity-model="resources" data-entity-id="meeting-room" href="/resources/meeting-room">Meeting room</a>

Render files as a download / preview row. Render entity links as in-app navigation to the referenced resource, service, plan, or bundle using data-entity-model + data-entity-id (slug).

PDF rendering

Signed legal-document PDFs cannot play video. The backend transforms TipTap HTML before TCPDF:

Images are embedded (resolved from data-image-id when the file is available).
Videos become a static 16:9 poster (thumbnail + play button, or grey if no thumbnail) and the plain watch URL as a clickable link under it.

Native print / share flows should follow the same rule if they generate their own PDF.

Minimal detection cheat sheet

function isVideoNode(el: Element): boolean {
  return el.getAttribute('data-video-embed') === 'true'
    || el.classList.contains('video-embed')
    || (el.tagName === 'IFRAME' && isAllowedVideoHost(el.getAttribute('src')))
}

function isImageNode(el: Element): boolean {
  return el.tagName === 'IMG' && !el.closest('[data-video-embed]')
}

Parse with a real HTML parser (NSAttributedString + custom HTML, Android Html is not enough). Walk the DOM, swap image/video nodes for native views, and render the remaining safe tags as text.

JSON-API Conventions — locale headers and sparse fieldsets
Authentication — tokens for fetching resources and legal documents

​Where this HTML appears

​Storage format

​Images

​Native rendering

​Videos

​Attributes

​Supported providers

​How to render videos in a native app

​Layout

​Do not

​Files and entity links

​PDF rendering

​Minimal detection cheat sheet

​Related

Where this HTML appears

Storage format

Images

Native rendering

Videos

Attributes

Supported providers

How to render videos in a native app

Layout

Do not

Files and entity links

PDF rendering

Minimal detection cheat sheet

Related