JSON Concepts and Article Structure

Understand basic JSON concepts and become familiar with the structure of an Apple News Format article.


Before you start creating articles in Apple News Format, you’ll want to make sure that you’re familiar with basic JSON concepts (including the use of objects, properties, and arrays) and that you understand how they relate to the JSON file you’re creating.

In this section you’ll learn about:

  • How JSON uses name-value pairs to structure data

  • The various types of values for properties

  • The correct use of punctuation in a JSON file

  • The structure of an Apple News Format article document file

You’ll also find information about the character sets supported by Apple News Format.

Understand the Basic JSON Concepts Used in an Article Document File

You start an Apple News Format article by creating a JSON article document file with the name article.json. This file—along with images and other resource files—contains the information needed by the Apple News app to process and render your article.

An Article Is a JSON Object

At the most basic level, an article.json file contains a single JSON object—the ArticleDocument object. Like all JSON objects, the article document object begins and ends with curly brackets ({}) and is made up of properties.

An Object Has Properties Structured as Name-Value Pairs

Each property in a JSON object is a name-value pair (sometimes called a key-value pair). The name in a name-value pair is always enclosed in straight quotation marks, with a colon (:) separating the name from its value. For example, in the name-value pair for the following property, the name is columns and the value is 10.

"columns": 10

Values in Name-Value Pairs Can Take Many Forms

In JSON, the values in name-value pairs can be of various types, including:

  • A string (enclosed in straight quotation marks)

  • An integer or floating point number (as shown in the previous example)

  • A Boolean (true or false) value

  • An object (a list of properties enclosed in curly brackets)

  • An array (a list of items enclosed in square brackets)

You’re probably familiar with string, integer, and boolean as types of values, but the concept of using objects and arrays as values may be new to you. Compare the following examples.

The first example shows the name-value pair for a property whose name is "title" and whose value is a string ("Article Title").

In the second example, the name-value pair is for a property called "layout" and the value is an object with four properties of its own. The object is enclosed in curly brackets and has commas separating the four properties. (Note that there is no comma after the last property).

The third example shows the name-value pair for a property called "colorStops" whose value is an array. The list of items in the array is enclosed in square brackets ([]) with commas separating the items. In this example, the items in the array are objects—each is enclosed in curly brackets and each has a single property named "color". (Note that there is no comma after the last item.)

Properties Can Be Nested

Because the value of a property can be an object or an array, properties are often nested inside other properties. For example, the following code shows a heading1Layout object with three properties (named "columnStart", "columnSpan", and "margin"). The value for the "margin" property is another object with two properties ("top" and "bottom").

"heading1Layout": {
	"columnStart": 0,
	"columnSpan": 7,
	"margin": {
	    "top": 24,
	    "bottom": 3

Some Properties Are Optional

Not all properties associated with an object are required. For example, the Layout component object has four properties (columns, gutter, margin, and width), but only two properties (columns and width) are required.

Punctuation Is Critical

Incorrect punctuation in your article.json file—even a misplaced comma or a curly quotation mark instead of a straight quote—will generate an error when you try to preview your article. You must fix all errors before you can preview your article.

To avoid errors, make sure you follow these rules throughout your JSON code:

  • The name in a name-value pair must be enclosed in straight quotation marks; put a colon (:) before the value.

  • The list of properties in an object is enclosed in curly brackets ({}). Properties are separated by commas; do not put a comma after the last property in the list.

  • The list of items in an array is enclosed in square brackets ([]). Items are separated by commas; do not put a comma after the last item in the list.

  • All values in name-value pairs have a data type. Values with a string data type must be enclosed by straight quotation marks. Don’t use quotation marks with integer or Boolean data types. When a value is an object, use curly brackets and separate the object properties with commas; values that are arrays use square brackets.

The Structure of article.json

Further Reading

To learn more about general JSON concepts, see

Use HTML and Markdown in Your Code

In addition to the Apple News Format objects and properties, you can use a subset of HTML tags and Markdown syntax in your JSON document. For example, you can use HTML tags to create a list or use Markdown to specify a link.

Not all HTML tags and Markdown syntax are supported. For details, see Using HTML with Apple News Format and Using Markdown with Apple News Format.

Use the Supported Character Sets

Apple News Format supports both ASCII and Unicode character sets. Characters may be included directly or referenced by their Unicode value. For example, the following examples will display the same thing: the words “Lorem ipsum” surrounded by curly quotation marks.

"text": "“Lorem ipsum”"
"text": "\u201cLorem ipsum\u201d"

See Also

First Steps

Creating an Article: Main Steps

Plan the design for your article and create it in Apple News Format.

object ArticleDocument

The root object of an Apple News article, containing required properties, metadata, content, layout, and styles.