Guides and Sample Code

Developer

Apple News Format: Design Tutorial

On This Page

JSON Concepts

If you have never used JSON before, read these basic concepts before you get started.

An Apple News Format Article Is a JSON Object

At its most basic level, an Apple News Format article.json file contains a single JSON object that represents an article. You can tell it’s an object because the text in the article.json file begins and ends with curly brackets: {}.

A JSON Object Has Properties

A JSON object can have one or more properties, each of which is a pairing that includes a name and a value.

In the example above, the property's name is title; the name of a property is always a string. The property’s value is "The Wizard of Oz"—in this case, the value is a string, too.

Notice how punctuation is used in the example above:

  • The property’s name (in this case, title) must be enclosed in quotation marks and followed by a colon. These quotation marks must be straight quotes ("). Using curly quotes (“”) for this will break your JSON and make your article impossible to preview. Therefore, make sure to disable smart quotes in your text editor—or even better, choose a text editor intended for code.

  • The property’s value (in this case, "The Wizard of Oz") comes after the colon. When the value is a string, it must begin and end with straight quotation marks.

  • Conventionally, a space is used after the colon. The purpose of this space is to make your code easy for people to read. Although including the space is a best practice, omitting the space or using more spacing will not break your JSON.

The Value of a Property Can Be an Object

As you work in Apple News Format, some of the data types you encounter might be familiar to you: for example, a property’s value might be a number, a string, or a boolean value (true or false). On the other hand, one data type that might be new to you is the object.

In JSON, an object is a list of properties separated by commas, with the whole list enclosed in curly brackets: {}. The order of properties in an object doesn’t matter.

In the example above, the property is named film. The value of the film property is an object that consists of an opening curly bracket, two of its own properties (named title and year), and a closing curly bracket. Notice how objects allow you to create a hierarchy of information, in the form of nested properties.

The example above illustrates some additional punctuation rules:

  • An object begins and ends with curly brackets: {}.

  • Properties of an object must be separated by commas (as in line 2 above). There must be no comma after the last property of an object (as in line 3 above). Misuse of commas will break your JSON and make your article impossible to preview.

  • Conventionally, properties of an object are set off using line breaks after the opening curly bracket, after each property, and after the closing curly bracket. Additionally, properties inside an object are indented using either tabs or spaces. The line breaks and indentation make it easy to see which properties are associated to which object. It’s a good idea to write your code this way so that you can read it more easily later, but you can’t break your JSON by changing the number or location of spaces, tabs, and line breaks.

Tutorial Tip: Adding Properties to Objects in article.json

You’ll sometimes either copy a property from this tutorial and paste it inside an object in article.json, or add a new property manually.

Typically, if this tutorial says, “copy the property,” you’ll copy the whole thing: the property name (including the quotation marks), the colon, the property value (including quotation marks, if any), and the comma, if any. If this tutorial says “paste the property inside the object,” you’ll place your insertion point after a property, type a comma and a line break, indent as appropriate, and then paste the property. You’ll then need to make sure there is a comma after each name/value pair except the final one. Again, the order of the properties in an object doesn’t matter.

Similarly, if this tutorial says “add a [name] property with a value of [value],” you’ll place your insertion point after one of the properties in the list, type a comma, type a line break, indent as appropriate, and then type the new property using the appropriate punctuation rules.

Arrays

Another data type that might be new to you is the array.

An array is a list of values separated by commas, with the whole list enclosed in square brackets: []. In Apple News Format, arrays tend to be composed of objects.

In JSON, the order of values in an array matters. Later in this tutorial, you’ll learn more about the meaning of this order as it relates to Apple News Format components, galleries, and mosaics.

In the example above, the property is named selections. The value of the selections property is an array that consists of an opening square bracket, two values (each of which is an object with two properties of its own), and a closing square bracket.

Notice the additional punctuation rules illustrated by this example:

  • An array begins and ends with square brackets: [].

  • Values in an array must be separated by commas (as in line 5 above). There must be no comma after the last value in an array (as in line 9 above).

  • Conventionally, objects in an array are set off using line breaks after each opening bracket, property, or closing bracket; if a property or closing bracket is followed by a comma, the line break should be after the comma. Additionally, each object is indented within the array, and each object’s properties are further indented within that object. The line breaks and indentation make the information hierarchy clear in your JSON. It’s a good idea to write your code this way so that you can read it more easily later, but you can’t break your JSON by changing the number or location of spaces, tabs, and line breaks.

Tutorial Tip: Adding Objects to Arrays in article.json

You’ll sometimes copy an object and paste it inside an array in article.json.

Typically, if this tutorial says “copy the object,” you’ll copy the whole thing: the opening curly bracket, the list of properties, the closing curly bracket, and then the comma, if any. If this tutorial says “paste inside the array,” you can place your insertion point after an object’s closing curly bracket, type a comma and a line break, indent as appropriate, and then paste. You’ll then need to make sure there is a comma after each object except the final one. Because the order of objects in an array has meaning, you’ll have to pay attention to where you paste.

Like objects, arrays allow you to create hierarchies of information in JSON.

Further Reading

You won’t need these concepts for this tutorial, but they’re useful when you create your own articles.

JSON Naming Requirements and Conventions

You won’t need to create names for objects in this tutorial, but it’s useful to know some naming conventions when you create your own articles.

You’ll add objects to article.json that affect the layout and style of the article; these objects will often require names. For example, within this tutorial, you’ll use object names that have already been created for the tutorial, such as fullMarginAboveHalfBelowLayout and bodyFirstDropCap.

Later, when you are creating your own content, follow these naming requirements and conventions:

  • Spaces are not allowed.

  • Names are case-sensitive.

  • Conventionally, names should use camel case (such as heading1Layout) rather than hyphenation (such as heading-1-layout). This will help you tell the difference between names you’ve created and names of default styles, which are hyphenated (such as default-body).

JSON Reserved Characters and Line Breaks

This won’t come up in this tutorial, but it’s useful to know when you create your own articles.

Within a JSON string value, certain characters, known as reserved characters, can be used only if they’re preceded by a backslash (\). JSON reserved characters are straight quotation marks (") and backslashes (\). To include a straight quotation mark (") or backslash (\) in the string value rather than in the JSON code, escape the reserved character with a preceding backslash (\), as in the example below. Whenever you escape a backslash (\), you will have a double backslash character in your code.

You do not need to escape curly quotation marks (“”).

If your text is not HTML-formatted, you can use the backslash character to create a line break inside a string value, by using a backslash together with an n character: \n. Within article body text, News renders two consecutive line breaks (\n\n) as a paragraph break, using any style rules you have set for paragraph breaks.