<!--
{
  "availability" : [
    "Apple News Format: 1.7.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AppleNews",
  "identifier" : "/documentation/AppleNewsFormat/ArticleDocument",
  "metadataVersion" : "0.1.0",
  "role" : "Object",
  "symbol" : {
    "kind" : "Object",
    "modules" : [
      "Apple News Format"
    ],
    "preciseIdentifier" : "data:news_format:ArticleDocument"
  },
  "title" : "ArticleDocument"
}
-->

# ArticleDocument

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

```
object ArticleDocument
```

## 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`](/documentation/AppleNewsAPI/POST-channels-_channelId_-articles) and [`Update an Article`](/documentation/AppleNewsAPI/POST-articles-_articleId_) requests.

> Warning:
> Every Apple News Format document must contain all items marked as required in the preceding Properties list. Apple News API and [News Preview](https://developer.apple.com/news-preview/) display errors if you omit any required properties. See ``doc://com.apple.applenews/documentation/AppleNewsAPI/POST-channels-_channelId_-articles`` and ``doc://com.apple.applenews/documentation/AppleNewsAPI/POST-articles-_articleId_``.

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

```json
{
 "version": "1.7",
 "identifier": "SampleArticle",
 "language": "en",
 "title": "Apple News",
 "layout": {
   "columns": 20,
   "width": 1024,
   "margin": 60,
   "gutter": 20
 },
 "documentStyle": {
   "backgroundColor": "#F7F7F7"
 },
 "textFormat": "none",
 "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"
   }
 ],
 "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

[`ArticleDocument.componentLayouts`](/documentation/AppleNewsFormat/ArticleDocument/componentLayouts-data.dictionary)

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

[`ArticleDocument.componentStyles`](/documentation/AppleNewsFormat/ArticleDocument/componentStyles-data.dictionary)

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

[`ArticleDocument.componentTextStyles`](/documentation/AppleNewsFormat/ArticleDocument/componentTextStyles-data.dictionary)

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

[`ArticleDocument.textStyles`](/documentation/AppleNewsFormat/ArticleDocument/textStyles-data.dictionary)

An object containing text style objects that components within this document can refer to inline in text.

[`ArticleDocument.colorScheme`](/documentation/AppleNewsFormat/ArticleDocument/colorScheme-data.dictionary)

The object that contains information about the color scheme of the document, including Dark Mode behavior.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)