Link Search Menu Expand Document (external link)

Store post data as JF2

Date: 2021-01-10

Status

Accepted

Context

There are two formats for serializing post data:

  • mf2 is the standard JSON serialization of microformats2.

  • JF2 is a simpler JSON serialization of microformats2, intended to be easier to consume than the standard JSON representation.

Indiekit deals with both of these formats, often interchangeably:

Given the need to work with both formats, several options were considered for which format should be used when storing previously published posts.

Option 1: Store properties as MF2

Pros

  • Each post has a single canonical resource representing its properties.

  • mf2 is the serialization used by the Micropub protocol.

  • There are a lot of tools and parsers that work with this format (for example microformats-parser, post-type-discovery).

Cons

  • The verbosity of mf2 makes it difficult to work with. As every property is stored as an array, the existence of an array needs to be checked before checking for the existence of a value:
// mf2
if (mf2.properties.name && mf2.properties.name[0]) {  }

// JF2
if (jf2.name) {  }

This also means that any new value needs to be saved inside an array.

  • Static site generators tend to save post properties using front matter (typically YAML), a flatter data structure that is closer in design to that of JF2.

Option 2: Store properties as mf2 and JF2

Pros

  • Indiekit can use whichever serialization format is most suitable; mf2 for Micropub requests and responses, JF2 for populating templates.

Cons

  • Both serializations need to remain in sync.

  • Duplication of the same information.

  • Complexity; it’s proven difficult to know which serialization is being used by or within any given part of the application.

Option 3: Store properties as JF2

Pros

  • Each post has a single canonical resource representing its properties.

  • Given its flatter structure, it’s easier to test for the existence of property values and easier to inspect saved documents in MongoDB.

  • Establishes a direct relationship between properties stored in the database and those used to populate post and path templates.

  • JF2 was found to be the best format to share data about a publication’s recently published posts.

Cons

  • Need to convert incoming Micropub requests from mf2 to JF2, and convert queries for source content from JF2 to mf2.

  • Possible side-effects updating posts.

  • Need to write a native implementation of post type discovery that works with JF2.

Decision

Store properties as JF2.

Whatever choice is made, conversion between these two formats will always be necessary. Having tried options 1 and 2 (and experienced friction building the application with both approaches) option 3 is worth trying before considering more complex approaches.

Consequences

Post data will be stored exclusively using the JF2 serialization. Updating existing posts should not be affected, however, this has not been tested (backwards compatibility is not a concern at this early stage of development).