story-json v1.0.0

story-json

story-json is a JavaScript Object Notation (JSON) platform-agnostic document format that describes interactive content that user can "tap" through. This is an interactive storytelling format, optimized for quick consumption on a smartphone or tablet. See an example here.

A "Story" consists of a set of pages (or slides). Each page can contain various kinds of content. In most cases a page will have an image or short video as a background, with elements overlayed on top. Story-JSON documents can be created once and then transformed into any supported target format. This is based on the AMP Project's design system for Stories, which you can find here.

Story-JSON exists because we expect the Story format will be adopted by more and more platforms over time. Story-JSON serves as a convenient base format from which multi-platform distribution can happen automatically. Our main inspiration for this project was the Article-JSON format we developed to solve an analogous problem for articles.

Target formats

These are currently supported target formats:

AMP story

Video

Layout and styles

story-json uses Flexbox layout and styles that in most cases match CSS (camelCase notation, e.g. justifyContent). Since we want to support platforms other than the web, the list of styles is limited. Our current video implementation uses Yoga, a cross-platform layout engine made by Facebook, used in React Native.

The default value for flexDirection is row.

Validator

This repository includes story-json validator based on JSON Schema.

Install using npm:

npm i story-json -g

Usage:

story-json-validate <story.json>

Format structure

"Hello World" example, one page with "Hello World" text in the center:

{
  "version": 1,
  "title": "Hello World",
  "pages": [
    {
      "layers": [
        {
          "type": "container",
          "styles": {
            "backgroundColor": "#87d687"
          }
        },
        {
          "type": "container",
          "styles": {
            "flexDirection": "column",
            "justifyContent": "center",
            "alignItems": "center",
            "textAlign": "center"
          },
          "elements": [
            {
              "type": "heading",
              "text": "Hello World"
            }
          ]
        }
      ]
    }
  ],
  "defaultStyles": {
    "heading": {
      "fontFamily": "sans-serif"
    }
  }
}

story-json document format example:

{
  "version": 1,
  "title": "Story Title",
  "canonicalUrl": "https://example.com/story",
  "meta": {
    "datePublished": "2017-02-05T22:00:00.000Z",
    "dateModified": "2017-02-05T22:00:00.000Z",
    "author": "John Doe",
    "publisher": {
      "name": "Publisher Name",
      "logo": {
        "url": "https://example.com/publisher-logo",
        "width": 100,
        "height": 100
      }
    },
    "description": "Story description"
  },
  "pages": [
    {
      "annotation": "Page Annotation",
      "autoAdvanceAfter": 5,
      "layers": [
        {
          "type": "video",
          "annotation": "Video Annotation",
          "sources": [
            {
              "source": "https://example.com/video.m3u8",
              "type": "application/x-mpegURL"
            }
          ],
          "width": 1900,
          "height": 600,
          "layout": "responsive",
          "poster": "https://example.com/poster.jpg",
          "loop": true,
          "autoplay": true
        }
      ]
    },
    {
      "type": "container",
      "styles": {
        "justifyContent": "flex-end",
        "alignItems": "flex-end"
      },
      "elements": [
        {
          "type": "heading",
          "text": "This is a heading",
          "styles": {
            "width": 10,
            "height": 10,
            "border": {
              "width": 1,
              "color": "#000000",
              "style": "dashed"
            },
            "borderRadius": 10,
            "boxShadow": {
              "offset": {
                "x": 5,
                "y": 5
              },
              "blurRadius": 5,
              "spread": 10,
              "color": "#000000"
            },
            "textShadow": [
              {
                "offset": {
                  "x": 5,
                  "y": 5
                },
                "blurRadius": 5,
                "color": "#000000"
              }
            ],
            "transform": [
              {
                "rotate": "90deg"
              },
              {
                "translateX": "50%"
              },
              {
                "translateY": 50
              },
              {
                "scale": 2
              }
            ],
            "filter": [
              {
                "blur": 3
              },
              {
                "grayscale": "30%"
              }
            ],
            "backdropFilter": [
              {
                "blur": 3
              },
              {
                "grayscale": "30%"
              }
            ],
            "backgroundLinearGradient": {
              "direction": "50deg",
              "stops": [
                {
                  "color": "red",
                  "distance": 30
                },
                {
                  "color": "blue",
                  "distance": "50%"
                },
                {
                  "color": "black"
                }
              ]
            },
            "fontSize": 500,
            "paddingTop": 500
          }
        }
      ]
    } 
  ]
}

See more examples

Document properties

Top level

Story metadata

Publisher metadata

Publisher metadata logo

Page

Element

Styles

Styles are very similar to CSS styles, but are intended to be usable and easy to reason about on platforms that don't use an HTML renderer; for example, via React Native. Depending on the chosen platform's capabilities, some properties may be ignored.

Distance Style

Distance - absolute number or percentage string (for example, 10 or '10%')

Border Style

Linear Gradient

Linear Gradient Stop

Shadow and Box Shadow

Transform

Transform object contains one of the following properties:

Filter

Filter object contains one of the following properties: