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

| Property | Description | Type | Required | | ------------- | ------------- | ------------- | ------------- | | version | Format version (latest is 1). | number | yes | | title | Story title. | string | no | | canonicalUrl | Primary URL associated with the story. | string | no | | meta | Story metadata. | Story metadata | no | | canonicalUrl | URL that will point to the story's HTML file. | string | no | | pages | Array of pages in the story. | Array of pages | no | | defaultStyles | Default styles for each element. | Object with element type keys and style values | no |

Story metadata

| Property | Description | Type | Required | | ------------- | ------------- | ------------- | ------------- | | datePublished | Story publish date in UTC. | ISO 8601 Date | no | | dateModified | Story last modification date in UTC. | ISO 8601 Date | no | | author | Author name. | string | no | | publisher | Story publisher metadata. | Publisher metadata | no | | description | Story description. | string | no |

Publisher metadata

| Property | Description | Type | Required | | ------------- | ------------- | ------------- | ------------- | | name | Publisher name | string | yes | | logo | Publisher logo | Publisher metadata logo | no |

Publisher metadata logo

| Property | Description | Type | Required | | ------------- | ------------- | ------------- | ------------- | | url | Logo image URL. | string | yes | | width | Logo width in pixels. | number | yes | | height | Logo height in pixels. | number | yes |

Page

| Property | Description | Type | Required | Notes | | ------------- | ------------- | ------------- | ------------- | ------------- | | layers | Content of the page data | Array of elements | yes | | id | Unique page identifier. | string | no | | annotation | User-defined information associated with the page. | any | no | Will be removed in render. |

Element

| Property | Description | Type | Required | | ------------- | ------------- | ------------- | ------------- | | type | Element type. | 'container', 'image', 'video', 'paragraph', 'heading', 'heading1', 'heading2', 'heading3', 'heading4', 'heading5', or 'heading6' | yes | | id | Unique element identifier. | string | no | | styles | Element styles. | Styles object | no | | annotation | User-defined information associated with the element; will be removed in render. | any | no |

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.

| Property | Description | Type | Required | Notes | | ------------- | ------------- | ------------- | ------------- | ------------- | | position | Element position. | 'relative' or 'absolute' | no | | top | Top position | Distance | no | | bottom | Bottom position | Distance | no | | left | Left position | Distance | no | | right | Right position | Distance | no | | width | Element width | Distance | no | | height | Element height | Distance | no | | margin | Element margin (top, bottom, left and right) | Distance | no | Not currently supported by amp-story | | marginTop | Element margin top | Distance | no | Not currently supported by amp-story | | marginBottom | Element margin bottom | Distance | no | Not currently supported by amp-story | | marginLeft | Element margin left | Distance | no | Not currently supported by amp-story | | marginRight | Element margin right | Distance | no | Not currently supported by amp-story | | padding | Element padding (top, bottom, left and right) | Distance | no | | paddingTop | Element padding top | Distance | no | | paddingBottom | Element padding bottom | Distance | no | | paddingLeft | Element padding left | Distance | no | | paddingRight | Element padding right | Distance | no | | border | Element border (top, bottom, left and right) | Border | no | | borderTop | Element border top | Border | no | | borderBottom | Element border bottom | Border | no | | borderLeft | Element border left | Border | no | | borderRight | Element border right | Border | no | | borderRadius | Element border radius (top-left, top-right, bottom-left and bottom-right) | number | no | | borderTopLeftRadius | Element top-left border radius | number | no | | borderTopRightRadius | Element top-right border radius | number | no | | borderBottomLeftRadius | Element bottom-left border radius | number | no | | borderBottomRightRadius | Element bottom-right border radius | number | no | | display | Display type | 'flex', or 'none' | no | | flexDirection | 'row', 'row-reverse', 'column', or 'column-reverse' | string | no | | justifyContent | 'flex-start', 'center', 'flex-end', 'space-around', or 'space-between' | string | no | | alignItems | 'flex-start', 'center', 'flex-end', or 'stretch' | string | no | | textAlign | 'auto', 'left', 'right', 'center', or 'justify' | string | no | | backgroundColor | Background color | RGBA hex string, rgb(r,g,b), rgba(r,g,b,a) | no | | backgroundLinearGradient | Linear gradient | Linear Gradient | no | | color | Text color | RGBA hex string, rgb(r,g,b), rgba(r,g,b,a) | no | | boxShadow | Shadow effect | Box shadow or array of box shadows | no | | fontFamily | Text font | string | no | | fontSize | Text font size | number | no | | lineHeight | Text line height | number | no | | fontStyle | 'normal' or 'italic' | string | no | | textShadow | Shadow effect | Text shadow or array of text shadows | no | | opacity | Opacity | number | no | | transform | Transforms to apply to element | Array of transforms | no | | filter | Filters to apply to element | Array of filters | no | | backdropFilter | Backdrop filters to apply to element | Array of filters | no | https://developer.mozilla.org/en-US/docs/Web/CSS/backdrop-filter |

Distance Style

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

Border Style

| Property | Description | Type | Required | | ------------- | ------------- | ------------- | ------------- | | width | Border width | number | yes | | color | Border color | RGBA hex string, rgb(r,g,b), rgba(r,g,b,a) | yes | | style | Border style (solid, dotted, dashed) | string | yes |

Linear Gradient

| Property | Description | Type | Required | | ------------- | ------------- | ------------- | ------------- | | direction | Direction angle | angle string | yes | | stops | Gradient stops | Array of linear gradient stops | yes |

Linear Gradient Stop

| Property | Description | Type | Required | | ------------- | ------------- | ------------- | ------------- | | color | Gradient stop color | RGBA hex string, rgb(r,g,b), rgba(r,g,b,a) | yes | | distance | Gradient stop distance | Distance | no |

Shadow and Box Shadow

| Property | Description | Type | Required | | ------------- | ------------- | ------------- | ------------- | | offset | Shadow offsets | { x: number, y: number } | yes | | color | Shadow color | RGBA hex string, rgb(r,g,b), rgba(r,g,b,a) | no | | blurRadius | Shadow blur radius | number | no | | spread | Shadow spread (Box Shadow only) | number | no |

Transform

Transform object contains one of the following properties:

| Property | Type | | ------------- | ------------- | | perspective | number | | rotate | angle string | | rotateX | angle string | | rotateY | angle string | | rotateZ | angle string | | scale | number | | scaleX | number | | scaleY | number | | scaleZ | number | | translateX | Distance | | translateY | Distance | | skewX | angle string | | skewY | angle string |

Filter

Filter object contains one of the following properties:

| Property | Type | | ------------- | ------------- | | blur | Distance | | brightness | number | | grayscale | percentage string |