microformats2-json - Revision history

Tantek: note abbreviation mf2json e.g. https://indieweb.org/mf2json

2026-03-10T21:11:47Z

note abbreviation mf2json e.g. https://indieweb.org/mf2json

← Older revision		Revision as of 21:11, 10 March 2026
Line 1:		Line 1:
	This page contains an informative description of <dfn style="font-style:normal;font-weight:bold">microformats2 JSON</dfn>, the canonical output format of the [[microformats2-parsing\|microformats2 parsing]] algorithm. Note that the [[microformats2-parsing\|microformats2 parsing specification]] is the only authoritative source for its own output.		This page contains an informative description of <dfn style="font-style:normal;font-weight:bold">microformats2 JSON</dfn> (<abbr><dfn>mf2json</dfn></abbr>), the canonical output format of the [[microformats2-parsing\|microformats2 parsing]] algorithm. Note that the [[microformats2-parsing\|microformats2 parsing specification]] is the only authoritative source for its own output.

	'''Goal:''' Document possible values – with examples – of the official serialisation format of microformats generated by [[microformats2#Parsers\|microformats2 parsers]]. This format can be used to compare parsers and create [[test-suite\|test suites]]. It also clarifies the format for other specifications that rely on the serialisation, such as [https://micropub.net/ Micropub].		'''Goal:''' Document possible values – with examples – of the official serialisation format of microformats generated by [[microformats2#Parsers\|microformats2 parsers]]. This format can be used to compare parsers and create [[test-suite\|test suites]]. It also clarifies the format for other specifications that rely on the serialisation, such as [https://micropub.net/ Micropub].

Zegnat: JSON Schema has moved to its own repository with automated testing

2021-12-25T22:38:08Z

JSON Schema has moved to its own repository with automated testing

← Older revision		Revision as of 22:38, 25 December 2021
Line 234:		Line 234:

	* [https://tools.ietf.org/html/rfc8259 RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format]		* [https://tools.ietf.org/html/rfc8259 RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format]
	* [https://~~gist.~~github.com/Zegnat/~~65ed9a9fb0546fb8c4aa0c0b790b8a40~~ JSON Schema for microformats2 objects], by [https://vanderven.se/martijn/ Martijn van der Ven]		* [https://github.com/Zegnat/microformats2-json-schema JSON Schema for microformats2 objects], by [https://vanderven.se/martijn/ Martijn van der Ven]
	* [https://github.com/cleverdevil/microformats2 Type- and vocabulary-aware microformats2 JSON validator in Python], by [https://cleverdevil.io/ Jonathan LaCour]		* [https://github.com/cleverdevil/microformats2 Type- and vocabulary-aware microformats2 JSON validator in Python], by [https://cleverdevil.io/ Jonathan LaCour]

Zegnat: Add a more complete document preface

2019-03-09T22:07:40Z

Add a more complete document preface

← Older revision		Revision as of 22:07, 9 March 2019
Line 1:		Line 1:
	<dfn style="font-style:normal;font-weight:bold">microformats2 JSON</dfn> is the canonical output format of the [[microformats2-parsing\|microformats2 parsing]] algorithm. ~~As such it~~ can be used to compare parsers and create [[test-suite\|test suites]]. It is also ~~used as~~ the ~~official~~ serialisation ~~format of microformats objects~~, ~~and relied upon by specifications~~ such as [https://micropub.net/ Micropub].		This page contains an informative description of <dfn style="font-style:normal;font-weight:bold">microformats2 JSON</dfn>, the canonical output format of the [[microformats2-parsing\|microformats2 parsing]] algorithm. Note that the [[microformats2-parsing\|microformats2 parsing specification]] is the only authoritative source for its own output.

			'''Goal:''' Document possible values – with examples – of the official serialisation format of microformats generated by [[microformats2#Parsers\|microformats2 parsers]]. This format can be used to compare parsers and create [[test-suite\|test suites]]. It also clarifies the format for other specifications that rely on the serialisation, such as [https://micropub.net/ Micropub].

			'''Audience:''' Parser authors, parser users, web developers. This document is written for anyone working with microformats2 in their serialised form, so they can read about the format generated by the parsing algorithm without having to understand the actual parsing itself.

			'''Author(s):''' [[User:Zegnat\|Martijn van der Ven]]

	<div style="margin:1em;padding:1em;background:#FFDC00;font-size:smaller">⚠️ The JSON format used is not pinned to a specific [https://indieweb.org/JSON#Specs JSON specification]. See [https://github.com/microformats/microformats2-parsing/issues/23 issue #23] for a discussion on the subject.</div>		<div style="margin:1em;padding:1em;background:#FFDC00;font-size:smaller">⚠️ The JSON format used is not pinned to a specific [https://indieweb.org/JSON#Specs JSON specification]. See [https://github.com/microformats/microformats2-parsing/issues/23 issue #23] for a discussion on the subject.</div>

Zegnat: /* properties */ Outdated: image value (featuring alt) is not documented

2019-03-09T19:48:44Z

properties: Outdated: image value (featuring alt) is not documented

← Older revision		Revision as of 19:48, 9 March 2019
Line 51:		Line 51:

	=== properties ===		=== properties ===

			<div style="margin:1em;padding:1em;background:#F8F7EC;font-size:smaller">🕰️ '''This section is outdated.''' A new [[microformats2-parsing#parse_an_img_element_for_src_and_alt\|valid value for images]] was [http://microformats.org/wiki/index.php?title=microformats2-parsing&diff=66969&oldid=66967 added in January].</div>

	The <code>properties</code> 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.		The <code>properties</code> 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.

Zegnat: /* microformat2 Objects */ Sneaking in some outdated warnings.

2019-03-09T19:41:10Z

microformat2 Objects: Sneaking in some outdated warnings.

← Older revision		Revision as of 19:41, 9 March 2019
Line 18:		Line 18:

	== microformat2 Objects ==		== microformat2 Objects ==

			<div style="margin:1em;padding:1em;background:#F8F7EC;font-size:smaller">🕰️ '''This section is outdated.''' An extra optional member called <code>id</code> was [http://microformats.org/wiki/index.php?title=microformats2-parsing&diff=66967&oldid=66966 added in December].</div>

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

Zegnat: /* See Also */ Remove link, now mentioned in the rel-urls object write-up

2018-04-24T09:40:29Z

See Also: Remove link, now mentioned in the rel-urls object write-up

← Older revision		Revision as of 09:40, 24 April 2018
Line 226:		Line 226:
	* [https://gist.github.com/Zegnat/65ed9a9fb0546fb8c4aa0c0b790b8a40 JSON Schema for microformats2 objects], by [https://vanderven.se/martijn/ Martijn van der Ven]		* [https://gist.github.com/Zegnat/65ed9a9fb0546fb8c4aa0c0b790b8a40 JSON Schema for microformats2 objects], by [https://vanderven.se/martijn/ Martijn van der Ven]
	* [https://github.com/cleverdevil/microformats2 Type- and vocabulary-aware microformats2 JSON validator in Python], by [https://cleverdevil.io/ Jonathan LaCour]		* [https://github.com/cleverdevil/microformats2 Type- and vocabulary-aware microformats2 JSON validator in Python], by [https://cleverdevil.io/ Jonathan LaCour]
	* [[microformats2-parsing-brainstorming#more_information_for_rel-based_formats\|Background behind the included rels and rel-urls objects]]

Zegnat: /* rel-urls Object */ Finish this up

2018-04-24T09:40:01Z

rel-urls Object: Finish this up

← Older revision		Revision as of 09:40, 24 April 2018
Line 181:		Line 181:
	== rel-urls Object ==		== rel-urls Object ==

	~~<div style="margin:1em;padding:1em;background:#7FDBFF;font~~-~~size:smaller">ℹ️~~ '''~~This section~~ is a ~~stub~~.~~''' You can help~~ the ~~microformats~~.~~org wiki by expanding it~~.</~~div~~>		The '''rel-urls object''' is an object with any amount of members, where every member name is a URL and every member value is an object.

			The value object will always contain a member with the name <code>rels</code>. That member’s value will be an array of alphabeticall sorted link relationships applicable to the URL.

			The value object may additionally contain any members with the following names:

			* <code>hreflang</code>
			* <code>media</code>
			* <code>title</code>
			* <code>type</code>

			The values of these members are always a single string. The value is taken from the link’s attribute in the source document matching the member name. E.g. in HTML the value of an <code><a></code> element’s <code>hreflang</code> attribute will be the value of the URL’s <code>hreflang</code> member in the rel-urls object.

			In addition the optional member named <code>text</code> is added if any text is associated with the URL in the source document. E.g. in HTML the text within an <code><a></code> element will be used.

	The ~~'''~~rel-urls object~~''' is an~~ object ~~with any amount~~ of ~~members, where every member name~~ is ~~a URL~~ and ~~every member value is an object~~.		The following example shows what the companion rel-urls object to the above rels object might look like. It shows the text that was used to link to the authors, giving us more context of who they are. It also makes clear that the alternative version of the home page is in fact in French and meant for handheld devices.

	<source lang=javascript>{		<source lang=javascript>{
Line 201:		Line 214:
	"rels": ["alternate", "home"],		"rels": ["alternate", "home"],
	"hreflang": "fr",		"hreflang": "fr",
			"media": "handheld",
	"text": "Example page d’accueil"		"text": "Example page d’accueil"
	}		}
	}</source>		}</source>

			The rel-urls object was a later addition to the specification. It exists because so much information was lost when only the rels object was created. The discussion that shaped it [[microformats2-parsing-brainstorming#more_information_for_rel-based_formats\|can be read on the brainstorming page]].

	== See Also ==		== See Also ==

Zegnat: Use source javascript instead of pre for syntax highlighting

2018-04-24T08:48:17Z

Use source javascript instead of pre for syntax highlighting

← Older revision		Revision as of 08:48, 24 April 2018
Line 7:		Line 7:
	Parsers collect not only microformats2 objects, but also [[rel\|link relationships]]. Parsing an entire document will result in an outer object with 3 members named <code>items</code>, <code>rels</code>, and <code>rel-urls</code>:		Parsers collect not only microformats2 objects, but also [[rel\|link relationships]]. Parsing an entire document will result in an outer object with 3 members named <code>items</code>, <code>rels</code>, and <code>rel-urls</code>:

	<~~pre~~>{		<source lang=javascript>{
	"items": [],		"items": [],
	"rels": {},		"rels": {},
	"rel-urls": {}		"rel-urls": {}
	}</~~pre~~>		}</source>

	# <code>items</code> is an array of [[microformats2-json#microformat2_Objects\|microformats2 objects]], ordered according to their order in the source document.		# <code>items</code> is an array of [[microformats2-json#microformat2_Objects\|microformats2 objects]], ordered according to their order in the source document.
Line 21:		Line 21:
	The '''microformats2 object''' is an object with 2 required members named <code>type</code> and <code>properties</code>, as well as an optional member named <code>children</code>:		The '''microformats2 object''' is an object with 2 required members named <code>type</code> and <code>properties</code>, as well as an optional member named <code>children</code>:

	<~~pre~~>{		<source lang=javascript>{
	"type": [],		"type": [],
	"properties": {},		"properties": {},
	"children": []		"children": []
	}</~~pre~~>		}</source>

	# <code>type</code> is an array of the types that identify the microformat, ordered alphabetically.		# <code>type</code> is an array of the types that identify the microformat, ordered alphabetically.
Line 41:		Line 41:
	The following example shows an <code>h-entry</code> type microformats2 object, with a single property attached. The <code>h-entry</code> type is [[h-entry\|documented on the wiki]], this way types point towards documented conventions that hold true no matter what the source document was.		The following example shows an <code>h-entry</code> type microformats2 object, with a single property attached. The <code>h-entry</code> type is [[h-entry\|documented on the wiki]], this way types point towards documented conventions that hold true no matter what the source document was.

	<~~pre~~>{		<source lang=javascript>{
	"type": ["h-entry"],		"type": ["h-entry"],
	"properties": {		"properties": {
	"summary": ["A short published note."]		"summary": ["A short published note."]
	}		}
	}</~~pre~~>		}</source>

	=== properties ===		=== properties ===
Line 66:		Line 66:
	To see what these properties mean in the context of an <code>h-entry</code> type, see [[h-entry#Core_Properties\|the Core Properties section on the type’s wiki page]].		To see what these properties mean in the context of an <code>h-entry</code> type, see [[h-entry#Core_Properties\|the Core Properties section on the type’s wiki page]].

	<~~pre~~>{		<source lang=javascript>{
	"type": ["h-entry"],		"type": ["h-entry"],
	"properties": {		"properties": {
Line 99:		Line 99:
	]		]
	}		}
	}</~~pre~~>		}</source>

	=== children ===		=== children ===
Line 109:		Line 109:
	The following example shows an <code>h-feed</code> type microformats2 object with a few properties that describe the feed, and an array of <code>h-entry</code> objects as its children.		The following example shows an <code>h-feed</code> type microformats2 object with a few properties that describe the feed, and an array of <code>h-entry</code> objects as its children.

	<~~pre~~>{		<source lang=javascript>{
	"type": ["h-feed"],		"type": ["h-feed"],
	"properties": {		"properties": {
Line 153:		Line 153:
	}		}
	]		]
	}</~~pre~~>		}</source>

	== rels Object ==		== rels Object ==
Line 167:		Line 167:
	* <code><nowiki>https://example.com/a</nowiki></code> and <code><nowiki>https://example.com/b</nowiki></code> both identify an author of the current page using [[rel-author\|the <code>author</code> relationship value]].		* <code><nowiki>https://example.com/a</nowiki></code> and <code><nowiki>https://example.com/b</nowiki></code> both identify an author of the current page using [[rel-author\|the <code>author</code> relationship value]].

	<~~pre~~>{		<source lang=javascript>{
	"home": [		"home": [
	"https://example.com/",		"https://example.com/",
Line 177:		Line 177:
	],		],
	"alternate": ["https://example.com/fr/"]		"alternate": ["https://example.com/fr/"]
	}</~~pre~~>		}</source>

	== rel-urls Object ==		== rel-urls Object ==
Line 185:		Line 185:
	The '''rel-urls object''' is an object with any amount of members, where every member name is a URL and every member value is an object.		The '''rel-urls object''' is an object with any amount of members, where every member name is a URL and every member value is an object.

	<~~pre~~>{		<source lang=javascript>{
	"https://example.com/": {		"https://example.com/": {
	"rels": ["home"],		"rels": ["home"],
Line 203:		Line 203:
	"text": "Example page d’accueil"		"text": "Example page d’accueil"
	}		}
	}</~~pre~~>		}</source>

	== See Also ==		== See Also ==

Zegnat: Stubs aren’t so much stubs when they need only a single specific expension, update rels with a multi-rel URL, start the rel-urls documentation

2018-04-23T19:56:04Z

Stubs aren’t so much stubs when they need only a single specific expension, update rels with a multi-rel URL, start the rel-urls documentation

← Older revision		Revision as of 19:56, 23 April 2018
Line 33:		Line 33:
	=== type ===		=== type ===

	<div style="margin:1em;padding:1em;background:#7FDBFF;font-size:smaller">ℹ️ '''This section ~~is a stub~~.''' It needs an example of a microformats2 object that uses multiple types.</div>		<div style="margin:1em;padding:1em;background:#7FDBFF;font-size:smaller">ℹ️ '''This section needs expanding.''' It needs an example of a microformats2 object that uses multiple types and still makes sense.</div>

	The <code>type</code> 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 <code>type</code> 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.
Line 161:		Line 161:
	Any relationship can have 1 or more URLs in its matching array. And any URL can be in several arrays, if it has several relationships associated with it.		Any relationship can have 1 or more URLs in its matching array. And any URL can be in several arrays, if it has several relationships associated with it.

	The following example shows a rels object where 3 URLs were found in the source document: ~~1 URL points to the root domain and~~ identifies the homepage using [[rel-home\|the <code>home</code> relationship value]], and ~~2 URLs point to two separate pages that each~~ identify an author of the current page using [[rel-author\|the <code>author</code> relationship value]].		The following example shows a rels object where 4 URLs were found in the source document:

			* <code><nowiki>https://example.com/</nowiki></code> identifies the homepage using [[rel-home\|the <code>home</code> relationship value]],
			* <code><nowiki>https://example.com/fr/</nowiki></code> identifies an alternative version of the home page, combining the <code>home</code> and [[rel-alternate\|<code>alternate</code> relationship]] values,
			* <code><nowiki>https://example.com/a</nowiki></code> and <code><nowiki>https://example.com/b</nowiki></code> both identify an author of the current page using [[rel-author\|the <code>author</code> relationship value]].

	<pre>{		<pre>{
	"home": ["https://example.com/"],		"home": [
			"https://example.com/",
			"https://example.com/fr/"
			],
	"author": [		"author": [
	"https://example.com/a",		"https://example.com/a",
	"https://example.com/b"		"https://example.com/b"
	]		],
			"alternate": ["https://example.com/fr/"]
	}</pre>		}</pre>

Line 174:		Line 182:

	<div style="margin:1em;padding:1em;background:#7FDBFF;font-size:smaller">ℹ️ '''This section is a stub.''' You can help the microformats.org wiki by expanding it.</div>		<div style="margin:1em;padding:1em;background:#7FDBFF;font-size:smaller">ℹ️ '''This section is a stub.''' You can help the microformats.org wiki by expanding it.</div>

			The '''rel-urls object''' is an object with any amount of members, where every member name is a URL and every member value is an object.

			<pre>{
			"https://example.com/": {
			"rels": ["home"],
			"text": "Example Homepage"
			},
			"https://example.com/a": {
			"rels": ["author"],
			"text": "Mx Adam"
			},
			"https://example.com/b": {
			"rels": ["author"],
			"text": "Mx Baker"
			},
			"https://example.com/fr/": {
			"rels": ["alternate", "home"],
			"hreflang": "fr",
			"text": "Example page d’accueil"
			}
			}</pre>

	== See Also ==		== See Also ==

Zegnat: /* See Also */ Always check previews before saving, Martijn.

2018-04-23T19:22:45Z

See Also: Always check previews before saving, Martijn.

← Older revision		Revision as of 19:22, 23 April 2018
Line 180:		Line 180:
	* [https://gist.github.com/Zegnat/65ed9a9fb0546fb8c4aa0c0b790b8a40 JSON Schema for microformats2 objects], by [https://vanderven.se/martijn/ Martijn van der Ven]		* [https://gist.github.com/Zegnat/65ed9a9fb0546fb8c4aa0c0b790b8a40 JSON Schema for microformats2 objects], by [https://vanderven.se/martijn/ Martijn van der Ven]
	* [https://github.com/cleverdevil/microformats2 Type- and vocabulary-aware microformats2 JSON validator in Python], by [https://cleverdevil.io/ Jonathan LaCour]		* [https://github.com/cleverdevil/microformats2 Type- and vocabulary-aware microformats2 JSON validator in Python], by [https://cleverdevil.io/ Jonathan LaCour]
	* [[microformats2-parsing-brainstorming#more_information_for_rel-based_formats Background behind the included rels and rel-urls objects]]		* [[microformats2-parsing-brainstorming#more_information_for_rel-based_formats\|Background behind the included rels and rel-urls objects]]