Concepts

Here we describe general concepts and introduce terms that we will use freely in other documentation.

Federation

The federated wiki is a collection of federated wiki servers that can share pages encoded in page json. Servers are expected to respond to requests of the form:

• example.com -- retrieve the server's home page as html
• example.com/somepage.html -- retrieve somepage as html
• example.com/somepage.json -- retrieve somepage as json
• example.com/favicon.png -- an identifying image, conventionally a 32x32px color gradient.

Note: servers can participate in the federation returning only json and the favicon. However, the html versions offer a compatibility with the traditional web. Minimally paragraph items and image items should be rendered by the sever so that this content can be indexed by search engines.

Interaction

The html version of pages usually cite client javascript that offer various interactive capabilities:

• retrieve and render the json version of the page
• retrieve and render json cited by internal links
• extend the repertoire of renderable item types by consulting a plugin library
• associate data sources and possible renderings on available pages
• perform actions that modify pages.

These interactions will often involve ajax requests. This client/server division of responsibility is between a particular server and the client javascript it offers for interaction. The sharing within federated wiki depends only on the read-only retrieval of json encoded pages.

Representation

The page json must parse as legal JSON and adhere to some conventions.

• top level is object with members: title, story and journal.
• the title is a plain-text string describing the page in five to fifteen words.
• the story is array of items, each an object with members: type and id.
• the journal is array of actions, each an object with members: type and id.

There are a few universal story item types that every federated wiki server is expected to render. Unrecognized types should be ignored, possibly rendering with a notice.

• Items of type paragraph include a text member subjected to link rendering.
• Items of type image include a caption member link rendered and a url member used to retrieve the image.

There are a small number of journal action types that every federated wiki server is expected to render. These are move, add, remove, edit and fork.

Links

Links are encoded in plain text using a subset of the Mediawiki notation.

• external links are enclosed in single square brackets and consist of an external url and external link text.
• internal links are enclosed in double square brackets and consists of internal link text which can be compressed into a url-safe link slug.

Markup

It is not yet determined what additional markup will be universally accepted. Likely it will be some small set of safe html tags. Note that complex page rendering has been pushed into the variety of item types. Tables, for example, are expected to be represented in a semantically useful form that can be viewed, edited and still feed associated items.