microformats2 parsing specification

(Difference between revisions)

Jump to: navigation, search
(note stability in status section and explicit strict change policy per issues filed in response to implementation experience)
(document change control process as we've been following for resolving issues and making substantive edits, resolved issue https://github.com/microformats/microformats2-parsing/issues/1)
Line 3: Line 3:
;Status
;Status
-
:This is a '''Living Specification''' with several interoperable [[#implementations|implementations]]. This specification is considered stable. It is a living specification only subject to change by issues and errata filed in response to implementation experience (since 2015-01-21). There are currently no draft or proposed new features in this specification, and if any were to be added, they would be explicitly labeled as such.
+
:This is a '''Living Specification''' with several interoperable [[#implementations|implementations]]. This specification is considered stable. It is a living specification only subject to change by issues and errata filed in response to implementation experience (since 2015-01-21). See [[#change_control|change control]] for how. There are currently no draft or proposed new features in this specification, and if any were to be added, they would be explicitly labeled as such.
;Participate
;Participate
:[https://github.com/microformats/microformats2-parsing/issues Open Issues]
:[https://github.com/microformats/microformats2-parsing/issues Open Issues]
Line 245: Line 245:
== test suite ==
== test suite ==
See:
See:
-
 
* https://github.com/microformats/tests
* https://github.com/microformats/tests
* https://github.com/indieweb/php-mf2/tree/master/tests/Mf2
* https://github.com/indieweb/php-mf2/tree/master/tests/Mf2
Ports to/for other languages encouraged.
Ports to/for other languages encouraged.
 +
 +
== change control ==
 +
Minor editorial changes (e.g. fixing minor typos or punctuation) that do not change and preferably clarify the structure and existing intended meaning may be done by anyone without filing issues, requiring only a sufficient "Summary" description field entry for the edit. More than minor but still purely editorial changes may be made by an editor. Questioning any such editorial change may be undone without filing an issue. Any further reversion or iteration on such an editorial change must be done by filing an issue.
 +
 +
Per the stable status of this document, substantive issue filing, resolution, and edits are done with the following change control steps, which may nearly all be done asynchronously once an issue is filed to reach the required state of "Resolve by implementation verified rough consensus". All steps should be openly documented (e.g. on this wiki or GitHub issues) such that others may later verify the history of an issue, and all steps are encouraged to be announced on #microformats [[IRC]] with a link to the issue.
 +
 +
* '''File an issue.''' Anyone may file a new [[microformats2-parsing-issues|issue]] and is encouraged to do so, with the caveat that per the stable status, only issues originating as a result of implementation experience are likely to have a substantive impact on this specification.
 +
* '''Propose a resolution.''' Anyone may propose resolutions to existing issues, and should encourage others in the community, especially implementers, to provide feedback. Proposed resolutions should include what specific text of the spec needs changing, preferably with replacement text, and test cases if applicable (e.g. a resolution could just document the current state more precisely without needing to provide any new test cases).
 +
* '''Provide feedback on proposed resolution(s).''' Anyone may provide feedback on proposed resolutions with their name attached, in summary (e.g. +1/0/-1 opinions), and additionally with reasoning (required for objections, optional otherwise), or optionally with suggested improvements, or counter-proposals (per "Propose a resolution" above).
 +
* '''Iterate to resolve objections if any.''' If there are any objections to a proposed resolution, proposer(s) and anyone agreeing should work to iterate on the proposal to resolve objections to the satisfaction (or at least withdrawal of objection) of anyone objecting. The more objections resolved the better, and incremental progress is forward progress.
 +
* '''Broaden implementer consensus.''' Proposer(s) and anyone agreeing should reach out (e.g. via #microformats [[IRC]]) to multiple implementers of the specification to get their opinions and feedback on proposal(s). The more implementers providing feedback the better. Iterate to resolve any new objections per "Iterate to resolve objections if any" above.
 +
* '''Encourage and get 1+ implementation(s).''' Encourage, get, and document 1+ implementation(s) of implementation affecting aspects of a proposed resolution, preferably with a test case if applicable.
 +
* '''Resolve by implementation verified rough consensus.''' Once there is rough consensus on a proposal (i.e. either no objections, or at a minimum no objections by implementers, and explicit positive opinions by 2+ implementers) and a proposal's feasibility is verified by at least 1 implementation of aspects of the proposal that affect implementations (none needed if there are none, e.g. purely editorial), cite those in a "Resolution:" statement on the issue (e.g. in a comment), and explicitly share this resolution statement and link to issue in the #microformats [[IRC]] channel.
 +
* '''Edit specification.''' Normally the spec editor(s) will make edits per implementation verified rough consensus resolutions, however anyone (though especially issue discussion participants) may make a specification edit per a resolution if they are able to verify the citations that the resolution has achieve rough consensus, and has 1+ implementation(s) per "Encourage and get 1+ implementation(s)" above. Edits must contain a "Summary" field entry that at a minimum mention the issue by name, should provide a URL to the issue resolution, and preferably be done by a spec editor or an implementer. Once the edit is made, the issue should be closed, or at least a comment made on the issue requesting that the opener of the issue close the issue.
 +
 +
These change control steps are inspired by the tradition of "Rough consensus and running code" as exhibited by example by IETF and W3C processes, and in that regard, seek to be a philosophically compatible approach to specification iteration. They have been in rough practice since 2015-01-21, increasingly strictly applied since then with consensus of issue discussion participants, and explicitly documented based on issue resolving and spec editing experience.
== see also ==
== see also ==

Revision as of 02:53, 7 July 2016

microformats2 is a simple, open format for marking up data in HTML. The microformats2 parsing specification describes how to implement a microformats2 parser, independent of any specific vocabularies.

Status
This is a Living Specification with several interoperable implementations. This specification is considered stable. It is a living specification only subject to change by issues and errata filed in response to implementation experience (since 2015-01-21). See change control for how. There are currently no draft or proposed new features in this specification, and if any were to be added, they would be explicitly labeled as such.
Participate
Open Issues
Resolved issues before 2016-06-20
IRC: #microformats on Freenode
Editor
Tantek Çelik
License
Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2017-11-24, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Contents

algorithm

parse a document for microformats

To parse a document for microformats, follow the HTML parsing rules and do the following:

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

Parsers may simultaneously parse the document for both class and rel microformats (e.g. in a single tree traversal).

parse an element for class microformats

To parse an element for class microformats:

The "*" for root (and property) class names consists only of lowercase a-z and '-' characters.

parse an element for properties

parsing a p- property

To parse an element for a p-x property value whether explicit "p-*" or backcompat equivalent:

parsing a u- property

To parse an element for a u-x property value whether explicit "u-*" or backcompat equivalent:

parsing a dt- property

To parse an element for a dt-x property value whether explicit "dt-*" or backcompat equivalent:

parsing an e- property

To parse an element for a e-x property value whether explicit "e-*" or backcompat equivalent:

parsing for implied properties

Imply properties only on explicit h-x class name root microformat element (no backcompat roots)

Note: The same markup for a property should not be causing that property to occur in both a microformat and one embedded inside - such a property should only be showing up on one of them. The parsing algorithm has details to prevent that, such as the :not[.h-*] tests above.

parse a hyperlink element for rel microformats

To parse a hyperlink element (e.g. a or link) for rel microformats: use the following algorithm or an algorithm that produces equivalent results:

rel parse examples

Here are some examples to show how parsed rels may be reflected into the JSON (empty items key).

E.g. parsing this markup:

<a rel="author" href="http://example.com/a">author a</a>
<a rel="author" href="http://example.com/b">author b</a>
<a rel="in-reply-to" href="http://example.com/1">post 1</a>
<a rel="in-reply-to" href="http://example.com/2">post 2</a>
<a rel="alternate home"
   href="http://example.com/fr"
   media="handheld"
   hreflang="fr">French mobile homepage</a>

Would generate this JSON:

{
  "items": [],
  "rels": { 
    "author": [ "http://example.com/a", "http://example.com/b" ],
    "in-reply-to": [ "http://example.com/1", "http://example.com/2" ],
    "alternate": [ "http://example.com/fr" ], 
    "home": [ "http://example.com/fr" ] 
  },
  "rel-urls": {
    "http://example.com/a": {
      "rels": ["author"], 
      "text": "author a"
    },
    "http://example.com/b": {
      "rels": ["author"], 
      "text": "author b"
    },
    "http://example.com/1": {
      "rels": ["in-reply-to"], 
      "text": "post 1"
    },
    "http://example.com/2": {
      "rels": ["in-reply-to"], 
      "text": "post 2"
    },
    "http://example.com/fr": {
      "rels": ["alternate", "home"],
      "media": "handheld", 
      "hreflang": "fr", 
      "text": "French mobile homepage"
    }
  }
}


what do the CSS selector expressions mean

This section is non-normative.

Use SelectORacle to expand any of the above CSS selector expressions into longform English prose.

Exception:

note HTML parsing rules

This section is non-normative.

microformats2 parsers are expected to follow HTML parsing rules, which includes for example:

note backward compatibility details

The parsing algorithm and details refer to "backcompat root classes" (backcompat roots for short) and "backcompat properties". These conditions and steps in the algorithm document how to parse pre-microformats2 microformats which all defined their own specific root class names and explicit sets of properties.

Some details to be aware of (which are explicitly in the algorithm, this is just an informal summary)

backward compatibility mappings

Note: several parser implementations have encoded backward compatible mappings into source and data files. Implementers of parsers may find these useful:

questions

See the FAQ:

issues

See the issues page:

implementations

Main article: microformats2#Implementations

There are open source microformats2 parsers available for Javascript, node.js, PHP, Ruby and Python.

test suite

See:

Ports to/for other languages encouraged.

change control

Minor editorial changes (e.g. fixing minor typos or punctuation) that do not change and preferably clarify the structure and existing intended meaning may be done by anyone without filing issues, requiring only a sufficient "Summary" description field entry for the edit. More than minor but still purely editorial changes may be made by an editor. Questioning any such editorial change may be undone without filing an issue. Any further reversion or iteration on such an editorial change must be done by filing an issue.

Per the stable status of this document, substantive issue filing, resolution, and edits are done with the following change control steps, which may nearly all be done asynchronously once an issue is filed to reach the required state of "Resolve by implementation verified rough consensus". All steps should be openly documented (e.g. on this wiki or GitHub issues) such that others may later verify the history of an issue, and all steps are encouraged to be announced on #microformats IRC with a link to the issue.

These change control steps are inspired by the tradition of "Rough consensus and running code" as exhibited by example by IETF and W3C processes, and in that regard, seek to be a philosophically compatible approach to specification iteration. They have been in rough practice since 2015-01-21, increasingly strictly applied since then with consensus of issue discussion participants, and explicitly documented based on issue resolving and spec editing experience.

see also

Categories

microformats2 parsing specification was last modified: Wednesday, December 31st, 1969

Views