Example

OpenPub is a way to represent content using JSON, XML, or any other serialized format.

An OpenPub story is comprised of a collection of cards, each providing a specific type of information.

{
  "type": "Story",
  "cards": [
    {
      "type": "Contributor",
      "label": "Brandon Diamond"
    },

    {
      "type": "Content",
      "title": "Hello World",
      "body": [
        {
          "type": "Section",
          "body": [{ "type": "Paragraph", "text": "**Hello, world!**" }]
        }
      ]
    }
  ]
}

Everything is a Card

Every type of information is associated with its own card. Individual cards share an organizational theme (such as “geographic metadata” or “article content”) and are versioned to track updates to the card’s structure.

All cards share certain common fields and almost every field has a default value. You can specify as much or as little detail as you like — defaults depend on where your content is displayed. Adding more data gives you more control.

To avoid duplicating effort, some cards can be embedded within other cards. For instance, the Geography card is used for geotagging content and for describing a map.

Some common fields are:

  • help — a pointer to the card’s documentation
  • version — the version of the card’s structure
  • revision — the version of the card’s content
  • name — an alias for the card’s content

New Cards

Anyone in the community is free to create and revise card types. Cards that are widely used are documented here and deemed “official”. Updates to a card’s structure must be reflected in the version field.

Official cards are more likely to be supported by helpers, which are discussed next.