opencomic should be easy to understand and create for. It shouldn’t restrict authors, and it should be easy to develop parsers for. It aims to support:
A opencomic feed should contain some information about the comic it contains.
| key | required | type | description |
|---|---|---|---|
version |
yes | string | This should be the version of opencomic the feed is using. |
title |
yes | string | This should be the name of the feed, which usually will represent the name of the webcomic. |
home_url |
no | string | The home page of the webcomic. |
feed_url |
no | string | The URL of the opencomic feed. This can be used as a unique identifier for the feed in a parser. |
description |
no | string | A webcomic’s slogan (E.g. XKCD’s “A webcomic of romance, sarcasm, math, and language.”) |
icon |
no | string | A square image containing an icon or logo. Minimum recommended size of 512 x 512 px. |
authors |
no | array | See authors. |
language |
no | string | The primary language of the comic, in RFC 5646 format. |
expired |
no | boolean | This should indicate if the feed is expired, I.e. if it will ever be updated again. |
next_url |
no | string | The URL of the next document in the event of pagination. |
When specifying authors of a feed at least one of the following fields must be specified:
| key | required | type | description |
|---|---|---|---|
name |
no | string | The name of the author. |
url |
no | string | The author’s URL (I.e personal website, twitter, etc). |
avatar |
no | string | A square image containing an avatar. Minimum recommended size of 512 x 512 px. |
pages is an array of pages in the webcomic. It is required to contain at least one element.
| key | required | type | description |
|---|---|---|---|
id |
yes | string | A unique identifier for the page. It should never change, even if the page is updated. New pages should never use the same ID. You may use the page’s permalink as its ID. |
url |
no | string | The URL of the page. It should be a permalink. It may be the same as id. |
title |
no | string | The title of the page. Different than the tooltip text. |
title_text |
no | string | The tooltip text of the page (E.g. the text that appears when you hover over an XKCD comic with your mouse). |
panels |
yes | array | See panels. |
date_published |
no | string | The date the page was published in RFC 3339 format. |
authors |
no | array | This follows the same format as the top-level authors, and if not specified will use the top-level authors. |
panels is an array of panels in a page. You must at least specify an image URL, but alternate text is heavily recommended.
| key | required | type | description |
|---|---|---|---|
image_url |
yes | string | The URL of the image for the panel. |
alt_text |
no | string | Text describing the contents of the panel for those using screen readers. |
url |
no | string | An external URL that the image may link to. |
opencomic files should be served using the MIME type application/opencomic+json. Many feeds will still use the more general MIME type application/json, which is common wherever JSON is served. When discovering a feed, apps should prefer application/opencomic+json, but should fall back to accepting application/json if no feeds using application/opencomic+json are available.
The number of pages in a comic and panels in a page is theoretically unlimited, but practical limits should be observed. A 1MB feed places a burden on parsers, especially if there are many such feeds. Under 100K is ideal, and 250K is fine. Consider using pagination and next_url should you exceed a reasonable limit.
If a feed contains invalid JSON, do not attempt to parse it.
Some keys may be present but can be ignored if they are not available or malformed. date_published is an example of a nonessential element that should simply not be displayed.
A webcomic’s homepage may contain a <link> tag indicating the presence and location of an opencomic feed.
<link rel="alternate" title="My Feed" type="application/opencomic+json" href="https://example.org/opencomic.json" />
A feed should, when possible, be placed at example.com/opencomic.json. This allows for manual and fallback discovery in the event that a <link> tag is not present.