Technical Requirements

FlatPlan handles the distribution and display of your content. All we need from you is the content delivered via an RSS/Atom feed.

The feed that comes as standard with your CMS will be a sufficient basis on which to build your FlatPlan specific feed. See below for a breakdown of our feed requirements.

Top level standards

We need your feed to be valid, well-structured and contain everything we need. By this, we mean:

• Valid: confirmed by W3C validator as ‘valid’
• Well-structured: following the guidance below
• Everything we need:
  • a feed containing content in the language defined in the <channel> element
  • a single feed which includes only the stories you wish to appear on Apple News
  • contains article data in full — i.e. the complete body content along with related text and media
  • all article body elements — e.g. paragraphs, headings and media (visual and social)
  • all metadata as outlined below

NB — custom blocks (e.g. “read next”), unrelated to article content can be supported — please get in touch for their specification.

Feed details and structure

Format

FlatPlan supports RSS 2.0 or Atom

Items

We fetch your feed regularly to check for new and updated content — to help facilitate this we require a minimum of 40 items (articles) per page.

Character encoding

All content, whether plain text or html, should be encoded using UTF-8 character encoding.

Namespaces

FlatPlan requires the following namespaces

Elements(RSS 2.0)

<xml>

Specifies XML document version and character code

<?xml version="1.0" encoding="utf-8" ?>

<rss>

Specifies RSS version and namespaces.

<rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/" xmlns:flatplan="https://wearemathematics.co.uk/flatplan-feedspec/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" > ... </rss>

<channel>

A description of your website

<title>

<link>

<pubDate>

<lastBuildDate>

<language>

<item>

<item>

Describes each article

<guid>

<title>

<link>

<pubDate>

<media:thumbnail>

<dc:creator>

<content:encoded>

<description>

<category>

<flatplan:template>

<flatplan:sponsor>

<figure class="flatplan-gallery">

Article body

<content:encoded>

We require the feed to contain the full body of the article including all content types. Our system will parse all article related content modules providing they are wrapped in the appropriate tags. This includes paragraph styles, images, video (youtube, vimeo or native palyer) and social media embeds. The feed sample holds examples of these.

Please note, all “class” and “style” data is ignored as templating is handled within our system and takes no cues for the alignments or layout of the content that may apply to your website.

It is also possible to pass gallery content via a custom tag found in the feed sample.

Ensure the following:

• All text data should be encoded as character data with UTF-8 encoding.
• All inline elements are presented with appropriate HTML tags at the root level i.e — do not wrap a <figure> tag inside a <p> tag.
• All metadata included that precedes <content:encoded> and is used to describe the article is not also included in <content:encoded>(e.g. do not add the image contained in <media:thumbnail> )
• All URL paths are absolute. This includes those used for media assets and article links.

View a sample RSS document on Github

Content formats

Disallowed Characters

If characters which are not allowed by XML specification are included in a document, we can not parse them correctly. For more information about XML specification, please see http://www.w3.org/XML/Core/#Publications.

Date Format of <pubDate>

The value of <pubDate> must be specified in accordance with RFC822 (https://www.ietf.org/rfc/rfc0822.txt).

Timezones

Please specify a timezone using one of the following notations:

• Greenwich Mean Time (GMT or +0000)
• Timezone to which the website belongs (eg. PST or -0800 for New York)

For example, the following are correct notation to express “May 1, 2019 15:00:00 (PST)“:

• Wed, 1 May 2019 23:00:00 GMT
• Wed, 1 May 2019 15:00:00 -0800

Language

For language settings follow these guidelines for support codes

http://www.rssboard.org/rss-language-codes

Images

Supported image types are JPEG (.jpeg or .jpg) GIF, or PNG.

The minimum size of the image must be 300 px wide x 300 px high.

The aspect ratio (width ÷ height) must be between 0.5 and 3.0.

Server side requirements

Ensure your servers can accept “get” and “head” requests. We use these to pull the article data and check for updates.