Story Schema

Mango Storytelling JSON Schema

Mango Storytelling enables narrating a series of IIIF resources. The Story object is serialized as a JSON document containing chapters, coordinates, layer opacities, and voice narrations.

---

1. Story Schema Overview

A Story JSON contains top-level metadata, optional global narration tracks, and an array of sequential chapters.

{
  "version": "1.0",
  "type": "story",
  "title": {
    "en": "Story Title Example",
    "cy": "Enghraifft Teitl Stori"
  },
  "narration": {
    "tracks": {
      "en": { "src": "https://example.com/audio/en-narration.mp3" }
    }
  },
  "chapters": [
    {
      "id": "chapter-1-id",
      "title": { "en": "Chapter One" },
      "manifest": "https://example.com/iiif/manifest.json",
      "canvasIndex": 0,
      "viewBox": { "x": 100, "y": 100, "w": 400, "h": 300 },
      "advance": { "mode": "auto", "delayMs": 5000 }
    }
  ]
}

---

2. Interface Definitions

Story (Root Object)

• version: Must be "1.0".
• type: Must be "story".
• title: A multi-language localized map (LanguageMap).
• narration: Optional audio files mapped to languages for voiceover playback.
• chapters: An array of Chapter elements.

Chapter

• id: Unique string identifier.
• title & description: Localized maps (LanguageMap).
• manifest: The IIIF Manifest URL this chapter belongs to.
• canvasIndex: The target canvas page index (0-indexed).
• viewBox: Optional 2D coordinates defining what zoom/pan to apply when opening the chapter.
• model: Optional 3D Camera pose coordinates if the canvas is a 3D model.
• media: Optional start and end times (in seconds) if the canvas is a video or audio clip.
• narrationSegment: Dict mapping locale tags to start/end times inside the narration track.
• layerOpacities: Dict mapping IIIF Image layer IDs to opacity thresholds (0.0 - 1.0).
• advance: Transition behavior rules:
  • mode: 'manual' (waits for click) | 'auto' (advances after delay) | 'both'.
  • delayMs: Wait time before moving to the next chapter.