Guides and Sample Code


Apple News Format: Design Tutorial

Article Structure

Apple News Format is the predetermined JSON structure for Apple News articles; it determines which properties you can use in which objects, and what the acceptable values are for each property. The properties that you use in your article.json file control the article’s content, metadata, style, and layout, by structuring this information in the format in which News needs to receive it, in order to lay out and render your article in iOS.

For a detailed guide to Apple News Format structure and properties, refer to the Apple News Format Reference.

JSON Example: Article Structure

The JSON skeleton below shows the structure of a typical article.json file. In this example, to make it easier to see the overall structure, properties have been omitted from some objects, and objects have been omitted from the array.

You don’t need to know the meaning of each of these properties yet. If you want to know the meaning of each of these properties, and how these properties affect the article, see Top-Level Properties.

  1. {
  2. "title": "Article Title",
  3. "metadata": {
  4. "thumbnailURL": "bundle://header.jpg",
  5. "excerpt": "Quia consequuntur magni accusantium doloremque eos qui ratione voluptatem sequi nesciunt?"
  6. },
  7. "version": "1.5",
  8. "identifier": "testArticle",
  9. "language": "en",
  10. "layout": {
  11. "columns": 10,
  12. "width": 1024,
  13. "margin": 85,
  14. "gutter": 20
  15. },
  16. "documentStyle": {
  17. "backgroundColor": "#F5F9FB"
  18. },
  19. "components": [],
  20. "textStyles": {},
  21. "componentLayouts": {},
  22. "componentStyles": {},
  23. "componentTextStyles": {}
  24. }

There are twelve top-level properties in this example. All twelve of these top-level properties have string, array, or object values:

  • Strings. The title, version, identifier, and language properties each have string values. You can tell because these properties’ values are enclosed in quotation marks.

  • Objects. The metadata, layout, and documentStyle properties each have object values. You can tell because the property values are enclosed in curly brackets: {}.

    Additionally, the textStyles, componentLayouts, componentStyles, and componentTextStyles properties have empty objects as their values; properties inside these objects have been omitted. You can tell these four properties are empty objects because the values are empty sets of curly brackets: {}. You’ll add properties to some of these objects later.

  • Array. The components property has an empty array as its value. You can tell because the value is an empty set of square brackets: []. You’ll fill this array later.

There are seven properties in this example that are not at the top level:

  • The thumbnailURL and excerpt properties are inside the top-level metadata object and have string values.

  • The columns, width, margin, and gutter properties are inside the top-level layout object and each have number values.

  • The backgroundColor property is inside the top-level documentStyle object and has a string value.

This example can’t be previewed in News Preview, because it doesn’t contain enough article content. In the next section, you’ll add some content and start previewing the article.