Object

ArticleDocument

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

Properties

components
(Required)

An array of components that form the content of this article. Components have different roles and types, such as Photo and Music.

(Required)

The component text styles that can be referred to by components in this document. Each article.json file must have, at minimum, a default component text style named default. Defaults by component role can also be set. See Defining and Applying Text Styles.

identifier
string
(Required)

An unique, publisher-provided identifier for this article. This identifier must remain constant; it cannot change when the article is updated.

This identifier can include the following:

  • Up to 64 characters

  • Uppercase and lowercase letters

  • Numbers

  • Hyphens

  • Underscores

language
string
(Required)

A code that indicates the language of the article. Use the IANA.org language subtag registry to find the appropriate code; e.g., en for English, or the more specific en_UK for English (U.K.) or en_US for English (U.S.).

layout
(Required)

The article’s column system. Apple News Format layouts make it possible to recreate print design on iPhone, iPad, iPod touch and Mac. Layout information is also used to calculate relative positioning and size for these devices. See Planning the Layout for Your Article.

title
string
(Required)

The article title or headline. Should be plain text; formatted text (HTML or Markdown) is not supported.

version
string
(Required)

The version of Apple News Format used in the JSON document.

The value of the version property must not be earlier than the version number of any property that is used anywhere in the article.

The current version of Apple News Format is 1.10.1.

advertisingSettings
Deprecated

An advertisement to be inserted at a position that is both possible and optimal. You can specify what bannerType you want to have automatically inserted.

Note. This property is deprecated. Use the AdvertisementAutoPlacement object instead.

autoplacement

The metadata, appearance, and placement of advertising and related content components within Apple News Format articles.

The article-level ComponentLayout objects that can be referred to by their key within the ComponentLayouts object. See Positioning the Content in Your Article.

The component styles that can be referred to by components within this document. See Enhancing Your Articles with Styles.

documentStyle

An object containing the background color of the article.

metadata

The article's metadata, such as publication date, ad campaign data, and other information that is not part of the core article content.

subtitle
string

The article subtitle. Should be plain text; formatted text (HTML or Markdown) is not supported.

The TextStyle objects available to use inline for text in Text components. See Using HTML with Apple News Format, Using Markdown with Apple News Format, and InlineTextStyle.

Discussion

Every Apple News Format document must have the same filename: article.json. An article.json file must contain the ArticleDocument object. This is the object that is sent in Create an Article and Update an Article requests.

In JSON, the order of properties in an object is not important; however, as you create your JSON document, you may find it useful to follow the order shown in the example that follows.

To view this example in News Preview, copy the example code to a file named article.json and put a file named image.jpg in the same folder. (You can use any JPEG, GIF, or PNG file.)

Example

{ "version": "1.7", "identifier": "SampleArticle", "language": "en", "title": "Apple News App", "subtitle": "A look at the features of the News iOS app", "layout": { "columns": 7, "width": 1024, "margin": 75, "gutter": 20 }, "components": [ { "role": "title", "text": "Apple News App", "textStyle": "title" }, { "role": "body", "text": "The Apple News Format allows publishers to craft beautiful editorial layouts. Galleries, audio, video, and fun interactions like animation make stories spring to life." }, { "role": "photo", "URL": "bundle://image.jpg" } ], "documentStyle": { "backgroundColor": "#F7F7F7" }, "componentTextStyles": { "default": { "fontName": "Helvetica", "fontSize": 13, "linkStyle": { "textColor": "#428bca" } }, "title": { "fontName": "Helvetica-Bold", "fontSize": 30, "hyphenation": false }, "default-body": { "fontName": "Helvetica", "fontSize": 13 } }}

Topics

Objects

object ArticleDocument.componentLayouts

An object containing component layout objects that components in the article can refer to.

object ArticleDocument.componentStyles

An object containing component style objects that components in the article can refer to.

object ArticleDocument.componentTextStyles

An object containing component text style defaults as well as component text styles that components in the article can use.

object ArticleDocument.textStyles

An object containing text style objects that can be referred to inline in text.

See Also

First Steps

JSON Concepts and Article Structure

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

Creating an Article: Main Steps

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