AppleNewsFormat
Sample JSON for Apple News Format
To preview Apple News Format files install News Preview.
Note: You'll also need Xcode installed for it to work because it borrows the iOS simulators.
Presented here are a range of stripped back JSON files that should assist you in constructing your own.
Basic
A JSON file with the minimum required properties. The components array should have at least one component to be valid but the componentTextStyles dictionary can be left empty.
Component Text Styles
You can add text styles by first referencing them with a textStyle key inside a component and then adding a componentTextStyle of the same name to the componentTextStyles dictionary. Think of component text styles as paragraph styles for your text, they can be reused time and again.
Note: The fonts you employ can be chosen from the entire list of iOS fonts. Although it is possible to include custom fonts there don't appear to be any guidelines on whether you should.
Markdown
Once you have the basic structure in place for your Apple News Format article, and the component text styles for your paragraph style formatting, you can then use either markdown or inline text styles for local formatting. To use markdown in any of your components simply add a format key with the value markdown.
Note: markdown is only applied to components that have a component text style and when you have markdown applied all inline text styles are ignored for that component.
Inline Text Styles
You can use either markdown or inline text styles for local formatting. To use markdown in any of your components simply add a format key with the value markdown. To use inline text styles add an inlineTextStyles key to your text component, the value of which will be an array of inline text styles.
Note: local styles are only applied to components that have a component text style and when you have markdown applied all inline text styles are ignored for that component.
Text Styles
In order to separate out and repeat text styles, as you would with character styles in a word processor or typesetting app, you can use a textStyles key in the top level of your dictionary, the value of which is a dictionary holding a list of styles in a similar way to the componentTextStyles key.
Once you have a list of text styles these can be referenced by replacing the textStyle dictionary within you inline styles with a string referencing a key within the textStyles dictionary.
Note: local styles are only applied to components that have a component text style and when you have markdown applied all inline text styles are ignored for that component.
Document Style
Document Style is an top-level optional property. At present a document style has only one option and that is to set the background colour using a hexadecimal string.
Note: documentStyle is a top-level key with a value that is a dictionary.
Metadata
Metadata has 13 different keys. Aside from the important ones like author and date, thumbnailURL and canonicalURL are of particular importance when your article is being shared through social media and excerpt is also highly recommended for where a synopsis of your article will appear.
Note: The thumbnailURL must point to a file contained within the same folder as your article json when previewing through News Preview. And an excerpt must not contain markdown.
Embed a tweet
You can embed a tweet in your article by simply adding it to the components. Two properties are required: role and URL and there are five optional properties: anchor, behavior, identifier, layout and style.
The role should be given as tweet and the URL is the tweet's link location from twitter. Similarly, you can embed an Instagram post by simply using instagram in place of tweet and referencing an Instagram URL.
Link Addition
A Link Addition is the only type of addition thus far in the Apple News Format. An array of additions is inserted inside a component in the same way as an array of inline text styles is.
A personal hope is that additions are added for pop-up notes and also index entries. This way we could move to make Apple News Format a great way to present journal articles and even construct books.
Note: Thanks go to an answer I received to a question posted on StackOverflow.
Mosaic and Gallery Images
You can add images to it in a static mosaic or scrollable gallery form. Both are objects placed within the components array and contain an array of gallery items. These gallery items can each include a URL that references an image (JPEG, PNG or GIF) inside the same folder as the article.json file, along with caption and voiceover information (accessibility caption), as well as an explicit content flag. (A Gallery Item has no required properties, only optional ones.)
There are a list of optional properties identical for mosaic and gallery: anchor, animation, behavior, identifier, layout and style. These are inherited from Text(Abstract) and Component(Abstract).
Tapping on an image expands it and displays the caption when inside Apple News.
Column Layout
You can explore laying out your components in columns. In order to do this you need to define a layout at the top level and a layout within the body of components. By default components span all columns.
Scalable Images and Component Animations
The role for a scalable image is the type of image: Figure, Photo, or Portrait. There is also an Image component of which the only supported role is currently logo. As with Gallery and Mosaic images, all images must be contained within the same folder as the article.json file and must be JPEG, PNG or GIF format. They are referenced as being in the bundle, e.g. "URL": "bundle://image2.jpg"
There are four types of Component Animations: Appear, Fade-in, Move-in, Scale Fade.
Custom Fonts
From a technical point of view custom fonts work, but there is currently no mention in the Apple docs to confirm that you are allowed to use them. For safety only use those fonts listed at iOSFonts.com and avoid the San Francisco font.
Parallax Header
A parallax header can be achieved by adding a behavior key to a Header component with a value that is an object containing the key/value pair type and parallax. To adjust the speed of the Parallax add a factor value between 0.5 (slowest) to 2.0 (fastest).
Animated Parallax Header
A Parallax Scale Header is more sophisticated than a normal parallax header. Its size scales at the same time as it moves. The header must however be placed within a Section or Chapter for it to be of this type.