microformats2-json

microformats2 JSON is the canonical output format of the microformats2 parsing algorithm. As such it can be used to compare parsers and create test suites. It is also used as the official serialisation format of microformats objects, and relied upon by specifications such as Micropub.

⚠️ The JSON format used is not pinned to a specific JSON specification. See issue #23 for a discussion on the subject.

Parsed Document Format

Parsers collect not only microformats2 objects, but also link relationships. Parsing an entire document will result in an outer object with 3 members named items, rels, and rel-urls:

{
  "items": [],
  "rels": {},
  "rel-urls": {}
}

1. items is an array of microformats2 objects, ordered according to their order in the source document.
2. rels is an object where the member names reflect all rel-values found in the source document.
3. rel-urls is an object where the member names reflect all URLs found in the source document with rel-values attached.

microformat2 Objects

The microformats2 object is an object with 2 required members named type and properties, as well as an optional member named children:

{ 
  "type": [],
  "properties": {},
  "children": []
}

1. type is an array of the types that identify the microformat, ordered alphabetically.
2. properties is an object where the member names reflect all properties found for the microformat.
3. The optional member children is an array of other microformats2 objects that were found nested in the current one.

type

ℹ️ This section is a stub. It needs an example of a microformats2 object that uses multiple types.

The type member contains an alphabetically sorted array of root class names. These names express what the microformat is expressing, and are often coupled to which properties to expect through documented conventions.

The root class names are individual strings that match the pattern h-([0-9a-z]+-)?[a-z]+.

The following example contains an h-entry type microformats2 object, with a single property attached. The h-entry type is documented on the wiki, this way types point towards documented conventions that hold true no matter what the source document was.

{ 
  "type": ["h-entry"],
  "properties": {
    "summary": "A short published note."
  }
}

properties

The properties member contains an object where every member name is a microformats2 property name, and every member value is an array of the found microformats2 values. Even when only one value is given, it will be inside an array.

Valid values in the value array are one of the following:

1. a string value, the most common value,
2. an embedded markup object, containing both a plain string value and the verbatim mark-up from the source document, or
3. another microformat2 object.

If a microformat2 object is used as the value of a property, it will gain the additional member value to express a plain string representation. If a consuming application does not understand the nested microformat2 object, it can opt to treat it as that string.

If a microformat2 object is used as the value of a property, when the parser is also instructed to return it as an embedded markup object, it will gain the additional member html.

The following example contains an h-entry type microformats2 object, with 3 properties to show the 3 different types of properties. The name is a single string, the content contains verbatim HTML from the source document, and the author is a nested microformat2 h-card object. The in-reply-to property has been added to show how one property may contain multiple valid values.

To see what these properties mean in the context of an h-entry type, see the Core Properties section on the type’s wiki page.

{
  "type": ["h-entry"],
  "properties": {
    "name": ["An example entry"],
    "content": [
      {
        "html": "<p>Ut non sit saepe porro porro est aut. Dicta ut repellat quisquam repellendus et iste consequatur.</p>\n<p>Consequuntur repellat sed aut in et dolores. Consequatur amet quo enim.</p>",
        "value": "Ut non sit saepe porro porro est aut. Dicta ut repellat quisquam repellendus et iste consequatur.\nConsequuntur repellat sed aut in et dolores. Consequatur amet quo enim."
      }
    ],
    "author": [
      {
        "type": ["h-card"],
        "properties": {
          "name": ["Mx Example"],
          "url": ["https://example.com/"]
        },
        "value": "Mx Example"
      }
    ],
    "in-reply-to": [
      {
        "type": ["h-cite"],
        "properties": {
          "name": ["Example Domain"],
          "author": ["IANA"],
          "url": ["https://example.org/"]
        },
        "value": "https://example.org/"
      },
      "https://example.net/"
    ]
  }
}

rels Object

ℹ️ This section is a stub. You can help the microformats.org wiki by expanding it.

rel-urls Object

ℹ️ This section is a stub. You can help the microformats.org wiki by expanding it.