Guides and Sample Code

Developer

Apple News Format Reference

On This Page

Top-Level Properties

An Apple News Format document—like any JSON document—consists of several key-value pairs. Each pair is a property. The following properties apply to the entire document.

Required Properties

Every Apple News Format document must contain the properties described in this section. Omissions will result in errors in the Apple News API and News Preview.

Property and type

Description

Version

version

String

The version of Apple News Format used in this JSON document. In the future, as new features are added, your document’s version will need to align with the latest version of any component or property it contains. The documentation notes the version of each property.

The current version of Apple News Format is 1.7.

1.0

identifier

String

A 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

1.0

title

String

The article title or headline.

Note that you should not use HTML tags or Markdown syntax for this property.

1.0

language

String

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_GB for English (U.K.) or en_US for English (U.S.).

1.0

layout

Layout

The article’s column system. Apple News Format layouts make it possible to re-create print design on iPad and iPhone.

Layout information is also used to calculate relative positioning and size for these devices.

For more details, see the Layout definition.

1.0

components

Array of Component

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

1.0

Optional Properties

The properties defined in this section are optional, but they're useful in most Apple News Format documents.

Property and type

Description

Version

advertisingSettings

Advertising Settings

Allows 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.

For more information, see Advertising Settings.

1.1

subtitle

String

An article subtitle.

Note that you should not use HTML tags or Markdown syntax for this property.

1.0

metadata

Article Metadata

Article metadata, such as publication date, ad campaign data, and other information that is not part of the core article content. For more details, see Article Metadata.

1.0

documentStyle

Document Style

The setting for the background color of the article.

1.0

textStyles

Text Style

The inline text styles that are available for reference from other components within this document.

Note that this is not the same as the textStyle property that that is part of many components.

1.0

componentLayouts

Component Layout

Document-level component layout objects that can be referenced by their key within the componentLayouts object.

1.0

componentStyles

Component Style

The component styles that can be referenced by components within this document. For more details, see the Component Style definition.

1.0

componentTextStyles

Component Text Style

The component text styles that can be referenced by other components in this document. Each article.json document must have, at minimum, a default component text style named default.

Components without an explicitly referenced text style will use the text style called default-<role> in the componentTextStyles section, where <role> matches the component's role. For example, Title components without an explicit textStyle will use the default-title in the componentTextStyles. When no default-<role> style is available, the default text style is applied.

1.0

Document Properties Example

  1. {
  2. "version": "1.7",
  3. "identifier": "SampleArticle",
  4. "language": "en",
  5. "title": "Apple News App",
  6. "subtitle": "A look at the features of the News iOS app",
  7. "layout": {
  8. "columns": 7,
  9. "width": 1024,
  10. "margin": 75,
  11. "gutter": 20
  12. },
  13. "components": [
  14. {
  15. "role": "title",
  16. "text": "Apple News App",
  17. "textStyle": "title"
  18. },
  19. {
  20. "role": "body",
  21. "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."
  22. },
  23. {
  24. "role": "photo",
  25. "URL": "bundle://image.jpg"
  26. }
  27. ],
  28. "documentStyle": {
  29. "backgroundColor": "#F7F7F7"
  30. },
  31. "componentTextStyles": {
  32. "default": {
  33. "fontName": "Helvetica",
  34. "fontSize": 13,
  35. "linkStyle": {
  36. "textColor": "#428bca"
  37. }
  38. },
  39. "title": {
  40. "fontName": "Helvetica-Bold",
  41. "fontSize": 30,
  42. "hyphenation": false
  43. },
  44. "default-body": {
  45. "fontName": "Helvetica",
  46. "fontSize": 13
  47. }
  48. }
  49. }