Skip to main content
English (US) Nederlands

The JSON Digital article format specification in Studio

  • Updated

This article describes the JSON Digital article format version 2 as used by Studio.

Use this for importing content from external sources or exporting content to external sources, such as:

  • Importing from a wire feed
  • Publishing to custom channels
  • Integration of translation memory systems

For information about how the Studio Server API can be used by 3rd-party integrations for creating Digital articles, see Creating Digital articles using the API of Studio.

Info: Use the filter to only show information for one topic:

Sample files

The following file contains a description of the fields for each component type that is discussed in this article:

The following is a sample Digital story containing most of the available components and properties that are discussed in this article:

Root level members

On root level, the file can have the following members:

Member Description
content An ordered list of components.

Example:

{ 
    // The version of the Digital Article format. 
    // The version is defined using a major and minor version.
    "version": "2.2",
    // Object containing the content of the article. 
    // Currently has one member, content, which is an ordered list of components
    "data":{ 
        // Ordered list of components
        "content":[ 
            { 
                // first component data...
            },
            { 
                // second component data...
            }
        ]
    },
    // Object containing the content of the comments in the article. Key of every object is the id of the comment applied as an attribute to the text.
    "comments":{
        "unique_key": {
            // content of a comment
        }
    }
}

Components

The members that components can have are listed in the following table:

Member Description
identifier Contains the component type.
id A randomly generated unique ID.
content

Contains the data for directives in the HTML template of the component.

The structure of the content object depends on the fields available in the component type. The fields for each component type are described in the Digital components definition file (see above).
containers For nesting another ordered list of components.
styles Contains the value of a component property that is added as a CSS style class to the component HTML element.
inlineStyles Contains inline CSS styles added to the HTML element of the component.
data Contains data for component properties that do not fit into any of the other categories.

Example:

{ 
    // The identifier contains the component type, linking it to the definition 
    // in the component set.
    // No assumptions can be made about the component type without the component 
    // set information!
    "identifier": "title",
    // A randomly generated unique ID.
    "id": "doc-1bpqed8bn0",
    // Contains the data for directives in the component's html template.
    "content": {},
    // Nests another ordered list of components
    "containers": {}
    // Contains the value of a component property that's added as a css style class 
    // to the component html element.
    "styles": {},
    // Contains inline css styles added to the component html element.
    "inlineStyles": {},
    // Contains data for component properties that do not fit into any of the other 
    // categories
    "data": {}
}

Text

Text is stored in a format suitable for Operational Transformation (OT), using the rich-text library.

Text of a component is stored in the content object and may have multiple text fields. The digital components definition file (see above) describes this data with the field type 'editable'.

The format in which it stores text changes represents the text as a series of inserts with attributes:

// Object containing the data of a component
{
    "content": {
       "<content-key>": [
           {"insert": "Text"},
           {"insert": "here", {"attributes": {"bold": "true"}}}
       ]
    }
}

The text formatting options of the Digital article are represented in the following table:

Format option Remarks
Bold

Since version: 

2.0

Model data:

{'insert': 'text', 'attributes': {'bold': true}}

Rendered HTML in the Digital editor:

<b>text</b>
Italic

Since version: 

2.0

Model data:

{'insert': 'text', 'attributes': {'italic': true}}

Rendered HTML in the Digital editor:

<i>text</i>
Strikethrough

Since version: 

2.0

Model data:

{'insert': 'text', 'attributes': {'strike': true}}

Rendered HTML in the Digital editor:

<span style="text-decoration: line-through;">text</span>
Underline

Since version: 

2.0

Model data:

{'insert': 'text', 'attributes': {'underline': true}}

Rendered HTML in the Digital editor:

<span style="text-decoration: underline;">text</span>
Super script

Since version: 

2.1

Model data:

{'insert': 'text', 'attributes': {'super': true}}

Rendered HTML in the Digital editor:

<sup>text</sup>
Sub script

Since version: 

2.1

Model data:

{'insert': 'text', 'attributes': {'sub': true}}

Rendered HTML in the Digital editor:

<sub>text</sub>
Soft breaks

Since version: 

2.0

Model data:

{'insert': 'te\nxt'}

Rendered HTML in the Digital editor:

te<br>xt
Hyperlinks

Since version: 

2.0

Model data:

{'insert': 'text', 'attributes': {'href': 'http://woodwing.com/'}}

Rendered HTML in the Digital editor:

<a href="http://woodwing.com/">text</a>
Color

Since version: 

2.0

Model data:

{'insert': 'text', 'attributes': {'color': '#00ff00'}}

Rendered HTML in the Digital editor:

<span style="color: #00ff00">text</span>
Size

Since version: 

2.0

Model data:

{'insert': 'text', 'attributes': {'size': '1.5em'}}

Rendered HTML in the Digital editor:

<span style="font-size: 1.5em">text</span>
Fonts

Since version: 

2.0

Model data:

{'insert': 'text', 'attributes': {'font': 'fontName'}}

Rendered HTML in the Digital editor:

<span style="font-family: fontName">text</span>
Shadow color

Since version: 

2.0

Model data:

{'insert': 'text', 'attributes': { 'text-shadow': { blur: 1, color: '#ff0000', x: 1, y: 1 } } }

Rendered HTML in the Digital editor:

<span style="text-shadow: rgb(255, 0, 0) 1px 1px 1px;">text</span>
Comment

Since version: 

2.2

Model data:

{'insert': 'text', 'attributes': {'comment': 'my comment'}}

Rendered HTML in the Digital editor:

<span data-text-comment="my comment">text</span>
Character styles

Since version: 

2.3

Model data:

{'insert': 'text', 'attributes': {'character-style': 'cs-emphasize'}}

Rendered HTML in the Digital editor:

<span class="cs-emphasize" data-text-character-style>text</span>
Anchors

Since version:

2.4

Anchors anchor other components (the origin) to a range of text (the target).

Note: Anchors are used by Apple News publishing. An Apple News Component set is planned to be made available in the near future.

Model data:

{'insert': 'text', 'attributes': {'anchor': 'doc-1fqtu7m3i0'}}

Rendered HTML in the Digital editor:

<span data-anchor="doc-1fqtu7m3i0">text</span>

Images

The data of images is also stored in the content object and may have multiple images depending on the component type. The Digital components definition file (see above) describes this data with the field type 'image'.

// Object containing the data of a component
{
    "content": {
        "<content-key>": {
            // Focus point of image using a normalized range of 0 to 1.
            // [0.5, 0.5] would be the center.
            "focuspoint": {
                "x": 0.5,
                "y": 0.5
            },
            // Cropped area of the image.
            // null or false when no crop is applied.
            cropper: {
                "x": 0.5,
                "y": 0.5,
                "width": "500px",
                "height": "500px",
            },
            // ID of Enterprise object
            "id": "634"
        }
    }
}

Containers

A container nests an ordered list of components.

The Digital components definition file (see above) describes this data with the field type 'container'.

// Object containing the data of a component with container data
{
    // Object storing data for containers
    "containers": { 
        // Key name of container data. For the container component type this is "main"
        "<content-key>": [ 
            {
                // Object containing the data of a nested component
            },
            {
                // Object containing the data of a second nested component
            }
        ]
    }
}

Slideshow

Slideshow data is stored the same way as containers, but can only contain components of the type 'image'.

The Digital components definition file (see above) describes this data with the field type 'container'.

// Object containing the data of a slideshow component with container data
{
    "containers": { 
        "<content-key>": [ 
            {
                // Object containing the data of an image component
            },
            {
                // Object containing the data of a second image component
            }
        ]
    }
}

HTML

This primarily exists for the embed component and stores the raw HTML string inside the JSON data.

The Digital components definition file (see above) describes this data with the field type 'html'.

// Object containing the data of an embed component
{
    "content": {
        // Raw HTML string
        "<content-key>": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/qJ2_--dpg1o\" frameborder=\"0\" allowfullscreen></iframe>"
    }
}

Links

This primarily exists for the image component, to turn the image into a link that can be clicked.

The Digital components definition file (see above) describes this data with the field type 'link'.

// Object containing the data of a component
{
    "content":{
        "<content-key>": "https://woodwing.com/"
    }
}

Social media and video

These separate components are used for showing embedded content from a supported platform.

The Digital components definition file (see above) describes this data with the field type 'video' or 'social-media'.

// Object containing the data of a component
{
    "content": {
        "<content-key>": {
            "url": "https://twitter.com/woodwingsoft/status/951098126831706112",
            "properties": {
                "include-media": true // Given properties differ per provider
            },
            "provider": "Twitter" // Instagram or Twitter for social, YouTube for video
        },
    },
    "identifier": "social-media", // Or video
    ...
}

Interactive

Info: Available since version 2.1.

Separate components used for showing interactive components in the published output.

The Digital Components definition file describes this data with the field type 'interactive'.

// Object containing the data of a component
{
    content: { 
        "<content-key>": {
            variant: "d7913fb9-48f5-4af9-8933-26bf894348b5",
            json-config: null // Or a JSON string when set
        },
    },
    identifier: "interactive",
    ...
},

Style component properties

Note: All properties described here should be seen as examples. A detailed description can be found in the Digital editor components boilerplate.

Values of style component properties are applied as CSS classes to the component HTML element.

// Object containing the data of a component
{
    // Object containing data for inline style component properties
    "styles":{
        // Adjusts the position of the component in the text
        // Possible values: ["_left", "_right"]
        "position": "_left",
  
        // Defines the caption position of an image
        // Not set means the caption is outside the image at the bottom.
        "inside-caption": "_caption-inside",
  
        // Controls Hero component image behavior.
        // When not set the Hero image is fixed with regard to the view port.
        // When set to _fixed-background it will scroll with the page.
        "fixed-background": "_fixed-background",
  
        // Controls the alignment of text. Applies to all text fields within the component.
        "text-align": "_align-middle",
  
        // Generic option to apply different style variants to the component
        // The possible values range from "_option1" to "_option20".
        "style": "_option1",
  
        // Defines the fitting behavior for an image in a component
        // Not set: Fits content to frame
        // "_fit-frame-to-content": Fits frame to content
        // "_fit-frame-height-to-content": Fits frame height to content
        "fitting": "_fit-frame-to-content",
  
        // Changes the slideshow play orientation to vertical. 
        // Defaults to horizontal when not present.
        "slideshow-play-orientation": "_vertical",
  
        // Enables/disables the slideshow auto-play
        "slideshow-autoplay": "_auto-play",
  
        // Enables/disables showing the filmstrip of the slideshow
        "slideshow-filmstrip": "_filmstrip",
    }
}

Inline Style component properties

Note: All properties described here should be seen as examples. A detailed description can be found in the Digital editor components boilerplate.

Inline style component properties are applied as inline CSS to the components main HTML element.

The available inline style component properties are listed in the following table:

Member Description
letter-spacing Overrides the spacing behavior between text characters
line-height Sets the amount of space between lines.
background-color Overrides the background color of the component element. 
// Object containing the data of a component
{
    // Object containing data for inline style component properties
    "inlineStyles":{
        // Overrides the spacing behavior between text characters
        // https://developer.mozilla.org/en-US/docs/Web/CSS/letter-spacing
        // This property is generally available for components with text
        "letter-spacing": "2",
  
        // Sets the amount of space between lines
        // https://developer.mozilla.org/en-US/docs/Web/CSS/line-height
        // This property is generally available for components with text
        "line-height": "1.5",
  
        // Overrides the background color of the component element
        // https://developer.mozilla.org/en-US/docs/Web/CSS/background-color
        // This property is currently only available for the container component
        "background-color": "rgba(53,103,255,1)"
    }
}

Comments

Info: Available since version 2.2.

Comments can be added to selected text. This text gets an attribute 'comment' which is an unique attribute that corresponds to an object in the comments object. This 'comments` object may not exist when there are no comments in the article.

// Object containing the data of the comments
{
    "unique_key": {
        "id": "unique_key",
        // The Enterprise User ID
        "userId": "edwin",
        "created": "2019-03-29T13:22:34.433Z",
        "modified": "2019-03-29T13:22:35.512Z",
        "text": "1",
        "replies": [
            {
                "id": "unique_key",
                "userId": "woodwing",
                "created": "2019-04-01T07:38:45.354Z",
                "modified": "2019-04-01T07:38:45.354Z",
                "text": "first reply",
            },
            {
                "id": "unique_key",
                "userId": "edwin",
                "created": "2019-04-01T07:39:13.419Z",
                "modified": "2019-04-01T07:39:13.419Z",
                "text": "second reply",
            }
        ]
    }
}

Character styles

Info: Available since version 2.3.

Character styles can be applied to selected text. This text then gets an attribute 'character-style' assigned which can be configured through either Component Sets or Look and Feel Styles. The attribute value of the character style can be used as a CSS selector or mapped to another format.

Other component properties

A number of component properties do not fit into the above categories and are put in the data object. These are listed in the following table:

Member Description
drop-capital Data for the Drop cap component property, available for a number of text components.
parallax Component property specific to Apple News. Available for every component.

Related articles

Comment

Do you have corrections or additional information about this article? Leave a comment!
Do you have a question about what is described in this article? Please contact Support.


0 comments

Please sign in to leave a comment.