Microformats Wiki - User contributions [en]

microformats2-parsing-brainstorming

2011-10-10T09:35:26Z

BenWard: /* Other Interpretation/Parsing Notes */ Note/query about parsing the value and value-title patterns.

Author: [[User:BenWard|Ben Ward]]

[[microformats-2|Microformats 2]] proposes a new, all encompassing syntax modification of [[microformats-2-prefixes|prefixes]] that will allow microformats to be parsed from pages by processors without prior knowledge of a vocabulary. The core components of this model are quite simple, are quite simple to implement, but there are a number of conflicts that emerge with the functionality of existing microformats parsers that need to be handled. This page documents a proposed model to separate these concerns clearly in a way that can be applied to the documentation of generic microformats parsing rules, and the documentation of individual vocabularies.

==Parsing Microformats 2.0 Syntax: Extraction vs. Interpretation==

A microformats ‘1.0’ parser performs the following function:

* Given a piece of HTML content, discover a known microformat, extract it, apply various extraction patterns based upon the HTML mark-up used (e.g. include pattern, <code>abbr</code> patterns, date-time patterns, value-title pattern), apply various content optimisations where applicable, and return the result in an object native to the programming language.

This is performing two types of function: Extraction of data from an HTML document or fragment, ''and'' interpretation and optimisation of that content to match the rules set out by a vocabulary specification.

It is only possible to write a generic parser that covers the first half of this task: Extraction, and application of global rules based on HTML elements and patterns common to all formats.

The purpose of a generic parser (as supported by use cases such as search engines, and other crawlers) is:

To provide a way for tools to extract rich data from a page for native storage, such that the data may be interpreted later by applications. This allows microformats to be crawled, and indexed, and removes the need to include complex HTML parsing within every implementation of microformat data.

Microformats will continue to define various vocabulary-specific optimisations. as part of the design to be optimised for authors. For example: The <code>fn</code> pattern in [[hcard]], or the <code>lat;long</code> pattern in [[geo]], as well as default values for properties, such as the maximum rating in an [[hreview]].
* Actually, no, as it is defined currently, microformats 2 ''drops'' vocabulary-specific optimizations. Such optimizations have often been too inapplicable, error prone or i18n-unsafe (e.g. fn to given-name + family-name fails for both numerous cases where middlenames/initials are used, and in general in numerous Asian languages where given/family name order is the reverse of Western English conventions, or languages with multiple family-names, e.g. Spanish - see [[hcard-issues-resolved]] for more). This is a deliberate cutting of a "feature" from microformats 1, it is a deliberate model simplification design decision. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

Microformats 2.0 should refer only to ''extraction'' of microformats. Vocabularies should in turn document their appropriate optimisations, which will need to be applied by implementations, or a companion to an extractor, which I'll refer to here as an ‘interpreter’.
* Vocabularies will no longer have optimizations, this is again deliberately, as they've been shown to be more error prone than helpful. Thus there should be no need for any vocabulary-specific 'interpreters'. However, due to design quirks in various legacy/interchange formats, ''export conversions algorithms'' to those legacy/interchange formats will require some additional legacy-format-specific rules (e.g. odd "required" rules in [[Atom]] or [[vCard]] will require specific synthesis rules, limitations in said formats will require filtering of some values, e.g. [[vcard3]] BDAY disallows vague birthdays like year-month and --month-day - subsequently allowed in [[vcard4]]). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

A microformats 2.0 ‘extractor’, in combination with the functionality of a domain and format-aware ‘interpreter’ (either another shared component, or part of the implementation itself) would be equivalent to a microformats 1.0 ‘parser.’
* A microformats 2.0 parser is both generic (no knowledge of specific vocabularies), and lacks any/all such vocabulary-specific rules as compared to a microformats 1.0 [[hcard-parsing|parser]] with the exception of a 1) a limited list of well-established/interoperable backward compat root class names (of current [[microformats]] that are or can be soon shown to be specifications/standards per the [[process]]), 2) flat sets of backward compat property names (some with prefix/name specific conversion) for each of those backward compat root class names. This is a deliberate design decision that makes microformats 2 more "micro", and yes this means that even with such backward compat support, this simple form of backward compat may mean that some existing microformats 1 content breaks. We'll assess those and iterate on a documented case-by-case basis rather than attempt to maintain theoretical 100% backward compatibility (since many current microformats format-specific-features are either unused, or may have caused more problems than solutions). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

N.B. I'll rewrite some of these as microformats-2-parsing-faq to help better clarify. The reasoning that led to most of these design decisions is documented in the [[microformats-2#About_This_Brainstorm|microformats 2: About This Brainstorm]] section and following sections. I'll recheck those sections to see if/where reasoning for some of the above noted design decisions may have been missed, and back-fill accordingly. This is necessary because [[microformats 2]] is a evolutionary result of simultaneously addressing both numerous generic [[issues]] as well as various common [[hcard-issues-resolved|format]]-[[hcalendar-issues-resolved|specific]] [[mfo|problems]] in microformats 1 syntax and vocabularies. The very number of changes may make it more challenging (from a microformats 1 perspective) to see why any particular design change has been made. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

==Parsing Literal Values==

It is proposed for microformats 2.0 that all microformats be parseable from just their root element, e.g. <code><p class="h-card">Ben Ward</p></code> would create an hCard with the following properties after parsing:

<source lang=javascript>
{
'type': ['h-card'],
'properties': {
'name': ['Ben Ward']
}
}
</source>

This is a four-fold change from the current [[hCard]]:
# type is generically identifiable as a microformat root, even in parsed form. The use of the 'h-' prefix persists into the type of the object. This is deliberately so, as a result of re-using the JSON data model of microdata which itself is re-using a common JSON convention, such that microformatted data is clearly distinguishable (as opposed to any other random schema that may be using a similar data model).
# root-class-only support. Per [[microformats-2-implied-properties]], the ''name'' property is implied by the entirety of the root class name element.
# 'name' instead of 'fn'. As also documented in [[microformats-2-implied-properties]], the continuous challenges/problems and need to repeatedly re-explain 'fn' over the years combined with the real-world market response of nearly every other party doing a person vocabulary renaming 'fn' to 'name', microformats 2 makes this change as well.
# There is no automatic parse-time inferring of <code>'given-name': ['Ben']</code> and <code>'family-name': ['Ward']</code>. Any such inferring *might* be made by a vCard converter, but is left up to that specific application (not all applications) built on that vocabulary, though even in that case it may not be necessary, as an empty "N:;;;" [[vCard]] property is sufficient to satisfy the N property requirement of [[vCard]], and also causes no problems when imported into various [[vcard-implementations]].

It is required of the extractor to understand that when a microformats object specifies no explicit child properties, that it must treat <code>h-card</code> as having a <code>p-name</code>. But, the parser is generic, so it also treats <code>h-review</code>, <code>h-entry</code>, <code>h-recipe</code>, <code>h-geo</code> as having a ‘<code>p-name</code>’.

As a result, specific vocabularies are evolved to drop their specific form of name (e.g. fn, summary, entry-title) and simplified to use a common 'name' property instead.

Note: while the overwhelming majority of real world publishing/consuming uses of microformats do so with proper nouns which have names (and thus this parser-level incorporation of an implied 'name'), there are some formats that do not have a 'name' semantic. For example, [[geo]], [[adr]], and possibly if/when developed, units of measure, length, cost. The current thinking is that the benefits to the far greater proper-noun use-case of microformats outweigh the technical inelegance of having an extra/ignored 'name' property on formats that lack such a semantic.

Some formats also may appear in theory to better imply some other property, e.g. a review might be thought to imply its ''content'', not its name, and an Atom entry its ''content'', not its title, but in practice (actual publishing patterns) this is not the case. Typically, brief unstructured reviews (or mentions thereof) provide a ''summary'' (often hyperlinked to an expanded structured form) of that review, not its content, and similarly, brief unstructured posts (e.g. RSS items) have historically most often been link blog items which include the title of an item and a link. Short status updates as well established by Twitter are newer and would seem to imply purely content with no title, at least semantically, however, even Twitter populates the RSS title and ATOM entry title of their feeds with the content. It's not clear what went into that decision, however, that's likely irrelevant, as the outcome turns out to be emergent consistency among publishing behaviors.

To avoid overloading or undermining the semantics of a vocabulary, I propose that we handle this at the extractor level in a simpler fashion: Define a new property for literal data, that an extractor will provide if no other information was available. All ''interpreters'' may then be instructed that in the event that an object has no properties, it can attempt to interpret the literal value from the page instead.
* This was one of the design iterations I went through which led me to the current implied 'name' design. Another iteration was the ability for a vocabulary to specify a single required property which was implied if there were no properties provided. However, the combination of the fact that in most cases such single required properties were quite name-like, and that a vocabulary-specific rule like that would then bind parsers to specific vocabularies (even so slightly) led me to collapse them into implying a 'name'. It's not perfect, but it's the best alternative so far that balances practical convenience of publishing/consuming, avoids vocabulary-specific knowledge in the parser, and technical (in)elegance. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

In existing microformats, the closest existing example we have for this is the <code>label</code> property in hCard, which is used to represent the literal address label for a place. It is a corresponding piece of <code>fn</code>, <code>org</code> and <code>adr</code> in combination, but has no structure in and of itself. Possibly, every microformat could have a <code>label</code> form where structured data is unavailable.

However in practice, the hCard <code>label</code> property is both little understood and little used. It's not even clear that it ought to be kept for microformats 2 (no known consumers, very few (if any?) real-world non-test publishers). This disuse is likely a good indicator that we should avoid basing anything on its design.

Alternatively, <code>value</code> is used throughout microformats to target a generic value (e.g. in combination with <code>price</code> in hListing.) It has been proposed that when parsing properties that are also themselves microformats, we create native objects of the form:

{
'value': '1900 12th Street, San Francisco, CA 94'
, 'type': ['adr']
, 'properties': {
'street-address': '1900 12th Street'
, 'etc': 'etc'
}
}

We could apply this same pattern to the root level:

{
type: [hcard]
, properties: {}
, value: 'Ben Ward'
}

In this case, an interpreter or implementation is responsible for using <code>value</code> in place of <code>fn</code>, or restructuring the object. It would be the responsibility of each vocabulary to define its root property. The parsing layer of microformats 2.0 would not impose semantics or naming onto that.

For another example, geo would end up like this:

{
type: [geo]
, properties: {}
, value: '1.3232;-0.543'
}

* This is an alternative I've been considering as well: [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)
** 'value' is more generic than 'name' (applies to more vocabularies) with the trade-off that it naturally has less (weaker) semantics.
*** +1 I think that having naturally weaker semantics would be appropriate for this parsing functionality. —[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC)
** The interesting thing that this analysis has revealed is that there appear to be two distinct clusters of microformats, the much more commonly used/understood/useful proper-noun microformats which markup things with names (people, events, reviews, recipes), and the less used compound-data microformats which are often used ''inside'' other microformats and just have some sort of semi-structured value (adr, geo, measure, and perhaps even things like tel). Perhaps this is implying the possibility and some degree of utility for ''two'' microformats root class name prefixes, 'h-' for existing proper-noun microformats, and something else ('m-' for microformat/molecule?, 's-' for structured-value?, 'v-' for value (though historically "v-"/"v." has meant "vendor-specific")?) for unnamed structured data microformats.
*** This more and more feels like a good idea, and I'm leaning toward "s-" for struct / structure / structured value. "s-" works just like "h-" except that it doesn't imply any properties at parse time. We can try it and see what happens. There's also no harm if publishers just use "h-" structures, they just (possibly) get a few extra properties if they happen to omit properties.
** Parallels the same JSON when a property has both a string value ''and'' is a structure itself.
*** Changed my mind on this. The parallel is not quite there. 'name'/'url'/'photo' are only implied if there are NO properties, where as the JSON string value + structure convention *always* provides a 'value'. [[User:Tantek|Tantek]] 22:39, 4 October 2011 (UTC)
*** And due to this difference in behavior ('value' is there when nested properties are present, whereas 'name' is only implied when there are no properties specified), I think it's correct to keep them separate, i.e. stick with implied 'name'. [[User:Tantek|Tantek]] 14:56, 5 October 2011 (UTC)
** However, I'm still currently leaning towards the practical convenience of providing a 'name' for the vast majority of microformats uses, rather than diluting this feature for the sake of avoiding implying inapplicable semantics to the few plain structured data microformats, and even then, only when no properties are explicitly specified! I'd rather introduce a new root prefix for those than lose the simplicity and utility of implied 'name'. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

==Parsing properties from rel attributes==

--[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC):

* Currently, hAtom parses `bookmark` as a permalink
* Various microformats parse `rel=tag` as tags
* The current proposal for parsing does not allow parsing properties from rel attributes.

Microformats parsers could instead extract ''all'' link relationships from rel attributes within an microformat object, parsing them as if a u- prefixed property.
* Minor nit: Rather than same as a u- prefixed property, I think such "rel" properties should be parsed purely from the <code>href</code> attribute on <code><a></code> and <code><area></code> elements and nothing more. I would strongly disagree to extending rel to apply to other elements with URLs like img src, object data, or to apply to elements in general like div. That's the path that RDFa has taken and caused much confusion as a result. [[User:Tantek|Tantek]] 07:39, 5 October 2011 (UTC)
** Agree: That seems like a perfectly reasonable restriction. --[[User:BenWard|BenWard]] 08:29, 5 October 2011 (UTC)

This results in:

* Continuing use of the <code>rel</code> attribute in HTML, thereby building on HTML semantics rather than bypassing them or ignoring them in favour of something less meaningful.
* Parsing hAtom objects contain a property named <code>bookmark</code>, in place of <code>permalink</code>.
* All microformats that use <code>rel-tag</code> would contain a property named… <code>tag</code>. Perfect.

Since <code>rel</code> attributes are not overloaded for other functionality like class is, and other uses of <code>rel</code> within content are low (and non-semantic uses are nil, to the best of my knowledge) the risk of property pollution would be extremely low.

Note, with regard to this last point, that a generic microformats parser ''will'' parse false-positive properties, and ''will'' parse objects in combined chunks, rather than individually by format. Extracted objects will often not represent a vocabulary without further processing.

<div class="discussion">
* This sounds like it might be workable. Let's try it and see how well authors "get it". - [[User:Tantek|Tantek]]
* Possible issue: do we have any collisions between class property names and rel names? (I don't think so offhand, but useful to ask the question). - [[User:Tantek|Tantek]]
** None that I can think of in microformats. There is the case of Google's <code>rel=author</code> and <code>p-author</code> in hAtom. However, the next point, about mfo scoping, would cover it in most situations (rel-author on a hyperlink within an hcard wouldn't be applied to the hentry.) The one situation in a parse tree where it's ambiguous would be this:
<source lang=html4strict>
<a href="p-author h-card"
rel="author"
href="http://benward.me">
Ben Ward
</a>
</source>
** I can think of two quite reasonable solutions:
*** 1. Declare that class properties take precedence over rel properties of the same name, discarding rel values if a class is also found, or
*** 2. Since all properties are now multi-value anyway, the hAtom object could be parsed as:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': ['Ben Ward'], /* from the p-author */
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},
'http://benward.me' /* from the rel="author" */
],
…
}
}
</source>
** —[[User:BenWard|BenWard]] 08:29, 5 October 2011 (UTC)
*** Option 2 makes sense and is consistent with the rest of the multi-value parsing/handling. - [[User:Tantek|Tantek]] 14:56, 5 October 2011 (UTC)
*** What about without the 'p-author'?
<source lang=html4strict>
<a href="h-card"
rel="author"
href="http://benward.me">
Ben Ward
</a>
</source>
Should that be parsed as:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},
'http://benward.me' /* from the rel="author" */
],
…
}
}
</source>
Or
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': 'http://benward.me' /* from the rel="author" */
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},

],
…
}
}
</source>
*** And if the former, then we're presumably saying that the value parsed due to the presence of a rel is always its own value, and does not combine with any other structures. I am fine with this, but I wanted to make sure we are ok with that explicitly. [[User:Tantek|Tantek]] 14:56, 5 October 2011 (UTC)
**** +1 I think that since the rel attribute is specifically concerned with the relation to an href attribute, it should not be combined with other structures that are rightly declared uses classes.
***** The more I've thought about this and how consuming applications may want to treat rel semantics, the more it seems correct to keep rel semantics distinct from class semantics. Class semantics are quite general/flexible, whereas rel is quite specific, naming something else in terms of a relationship from the current page/microformat's perspective. I think we should consider putting rel values in their own 'rel' collection, separate from the 'properties' collection. E.g. the original rel-author p-author h-card markup example would be parsed into this:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': ['Ben Ward'], /* from the p-author */
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
}
],
…
}
'rel': {
'author': ['http://benward.me'] /* from the rel="author" */
}
}
</source>
***** and if a post had multiple authors:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': ['Ben Ward'], /* from p-author */
'type': ['h-card'], /* from h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},
{
'value': ['Tantek Çelik'], /* from 2nd p-author */
'type': ['h-card'], /* from 2nd h-card ... */
'properties': {
'name': ['Tantek Çelik'],
'url': ['http://tantek.com']
},
],
…
}
'rel': {
'author': [
'http://benward.me', /* from rel="author" */
'http://tantek.com' /* from 2nd rel="author" */
]
}
}
</source>
***** This preserves the semantic distinction between rel and properties in general, and leaves it up to a higher-level application to implement any logic around showing "more info" about a rel-author, e.g. by correlating the rel-author URL with the 'url' of an hCard it found in the same entry. However, note that even in the earlier JSON data model, the rel-author value just shows up as another property value, and any higher level application would still have to do some correlation logic. At least with this JSON data model, applications that may be looking for a rel value in particular, or a property value in particular can do so without having one unintentionally pollute the other. [[User:Tantek|Tantek]] 17:33, 6 October 2011 (UTC)

* Presumably we'd apply all the same property scoping rules to rel scoping as well. E.g. a rel hyperlink inside a microformat won't be seen by any containing microformat. - [[User:Tantek|Tantek]]
** Correct, it should be parsed in the same scope as all other class properties in the object.
</div>

==Other Interpretation/Parsing Notes==

Collection of other unresolved parsing issues in a generic model:

This is good material for documenting as [[microformats-2-issues]], [[microformats-2-faq]], and perhaps some of the more technical details in [[microformats-2-parsing-faq]].

* The include pattern references other elements from elsewhere in a document. A generic parser needs to track IDs and fill them in after walking the DOM. (also, <code>itemref</code> if adopted.)
** The current thinking per [[microformats-2-brainstorming]] is to adopt <code>itemref</code> and drop the [[include-pattern]]. [[User:Tantek|Tantek]]
* Will <code>itemref</code> always map to an <code>item</code> property name?
** No, <code>itemref</code> maps to one or more elements by ids, and their children. Those referenced elements may have property class names themselves, or they may contain elements that do. [[User:Tantek|Tantek]]
* [[hAtom]] implies <code>author</code> from an hCard in a page that uses an <code>address</code> element. This requires format knowledge, but a generic parser does not currently track the element type of a property node. Should it?
** It should not. element-specific handling (e.g. using "alt" from img, and "title" from abbr) is completely done at parse time. The JSON data model does not reflect which element type or attribute the value came from. Additionally, [[hAtom]] is an example where we created far too many vocabulary-specific rules, in practice they're not necessary, and only complicate the microformat for both publisher understanding and parser implementation. [[User:Tantek|Tantek]]
* [[hAtom]] defines that the highest level heading within an entry implies <code>entry-title</code>. This particular optimisation might be better off dead.
** Agreed, this is gone in microformats 2. [[User:Tantek|Tantek]]
* [[hAtom]] defines that permalinks be parsed from <code>rel</code> attributes, not <code>class</code>
** In practice this has been one of the more problematic/error prone aspects of hAtom implementations, and it's also inconsistent with other microformats (although [[hReview]] tried to use both rel permalinks and "url"). The dependence upon [[rel-bookmark]] for permalinks is dropped in h-atom in preference to re-using "u-url" and "u-uid". [[User:Tantek|Tantek]]
* [[XFN]] is entirely built on <code>rel</code> (although, has various other differences from structural microformats, as do vote-links, so perhaps are excluded from this discussion and will always be handled by dedicated parsers/queries regardless?)
** The best (easiest and most reliable) use of 'rel' microformats in practice is when they are orthogonal to 'class' microformats. This is true both with [[XFN]] and some newer [[existing-rel-values|rel values]] like [[rel-author]]. In addition, it was very clear at the recent [[schema.org]] workshop's syntax session that RDFa's decision to apparently arbitrarily mix use of 'rel' and 'property' attributes for specifying different types of properties (it wasn't clear to people in the room when you use which for what) has caused a high degree of confusion among publishers and thus high error-rates. Thus if anything we should learn from both the mistakes of RDFa and our own experiences with even very deliberate/specific mixing of rel microformats in class microformats, and keep them defined as separate orthogonal building blocks that work together, but don't depend on each other. [[User:Tantek|Tantek]]
*** Relatedly to this: <code>rel-tag</code> in hAtom. --[[User:BenWard|BenWard]] 06:50, 5 October 2011 (UTC)
**** Yes, and two related things here. First, despite my (and others') objection and (past) interoperable post/entry-specific treatment by Technorati and Ice Rocket, Hixie has redefined rel-tag in [[HTML5]] to mean applying to the whole page, not a single post. Second, I've explicitly added 'p-category' to the draft 'h-atom' vocabulary in [[microformats-2]]. [[User:Tantek|Tantek]] 07:12, 5 October 2011 (UTC)
* HTML's <code>time</code> element includes an optional <code>pubdate</code> attribute. Simply: We should parse this as <code>dt-published</code>. --[[User:BenWard|BenWard]] 06:12, 10 October 2011 (UTC)
* Value pattern: In microformats-2, since there are no sub-properties, there will presumably no-longer be a 'value' property in any parsed model. Properties such as 'tel > type' in hCard are, as I recall, deprecated due to underuse anyway, so 'tel > value' becomes redundant. (There's also potentially some clarification around 'price > value' in hListing, whereby value was used in a pattern. So, what does this mean for value class parsing, with regard to value-title patterns and date separation patterns. Are we looking for a 'p-value' and 'p-value-title' classname, but treating them specially (excluding them from regular property parsing.) Or, are we giving them a special prefix (v-text, v-title? That seems confusing, but could be a concept.) I'm fine with p- for both, and just having the parser ignore them since they're special, but need clarification and naming confirmation. --[[User:BenWard|BenWard]] 09:35, 10 October 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-faq]]
* [[microformats-2-issues]]
* [[microformats-2-parsing-faq]]

microformats2-parsing-brainstorming

2011-10-10T06:12:55Z

BenWard: /* Other Interpretation/Parsing Notes */ Suggest parsing time/@pubdate as .dt-published.

Author: [[User:BenWard|Ben Ward]]

[[microformats-2|Microformats 2]] proposes a new, all encompassing syntax modification of [[microformats-2-prefixes|prefixes]] that will allow microformats to be parsed from pages by processors without prior knowledge of a vocabulary. The core components of this model are quite simple, are quite simple to implement, but there are a number of conflicts that emerge with the functionality of existing microformats parsers that need to be handled. This page documents a proposed model to separate these concerns clearly in a way that can be applied to the documentation of generic microformats parsing rules, and the documentation of individual vocabularies.

==Parsing Microformats 2.0 Syntax: Extraction vs. Interpretation==

A microformats ‘1.0’ parser performs the following function:

* Given a piece of HTML content, discover a known microformat, extract it, apply various extraction patterns based upon the HTML mark-up used (e.g. include pattern, <code>abbr</code> patterns, date-time patterns, value-title pattern), apply various content optimisations where applicable, and return the result in an object native to the programming language.

This is performing two types of function: Extraction of data from an HTML document or fragment, ''and'' interpretation and optimisation of that content to match the rules set out by a vocabulary specification.

It is only possible to write a generic parser that covers the first half of this task: Extraction, and application of global rules based on HTML elements and patterns common to all formats.

The purpose of a generic parser (as supported by use cases such as search engines, and other crawlers) is:

To provide a way for tools to extract rich data from a page for native storage, such that the data may be interpreted later by applications. This allows microformats to be crawled, and indexed, and removes the need to include complex HTML parsing within every implementation of microformat data.

Microformats will continue to define various vocabulary-specific optimisations. as part of the design to be optimised for authors. For example: The <code>fn</code> pattern in [[hcard]], or the <code>lat;long</code> pattern in [[geo]], as well as default values for properties, such as the maximum rating in an [[hreview]].
* Actually, no, as it is defined currently, microformats 2 ''drops'' vocabulary-specific optimizations. Such optimizations have often been too inapplicable, error prone or i18n-unsafe (e.g. fn to given-name + family-name fails for both numerous cases where middlenames/initials are used, and in general in numerous Asian languages where given/family name order is the reverse of Western English conventions, or languages with multiple family-names, e.g. Spanish - see [[hcard-issues-resolved]] for more). This is a deliberate cutting of a "feature" from microformats 1, it is a deliberate model simplification design decision. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

Microformats 2.0 should refer only to ''extraction'' of microformats. Vocabularies should in turn document their appropriate optimisations, which will need to be applied by implementations, or a companion to an extractor, which I'll refer to here as an ‘interpreter’.
* Vocabularies will no longer have optimizations, this is again deliberately, as they've been shown to be more error prone than helpful. Thus there should be no need for any vocabulary-specific 'interpreters'. However, due to design quirks in various legacy/interchange formats, ''export conversions algorithms'' to those legacy/interchange formats will require some additional legacy-format-specific rules (e.g. odd "required" rules in [[Atom]] or [[vCard]] will require specific synthesis rules, limitations in said formats will require filtering of some values, e.g. [[vcard3]] BDAY disallows vague birthdays like year-month and --month-day - subsequently allowed in [[vcard4]]). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

A microformats 2.0 ‘extractor’, in combination with the functionality of a domain and format-aware ‘interpreter’ (either another shared component, or part of the implementation itself) would be equivalent to a microformats 1.0 ‘parser.’
* A microformats 2.0 parser is both generic (no knowledge of specific vocabularies), and lacks any/all such vocabulary-specific rules as compared to a microformats 1.0 [[hcard-parsing|parser]] with the exception of a 1) a limited list of well-established/interoperable backward compat root class names (of current [[microformats]] that are or can be soon shown to be specifications/standards per the [[process]]), 2) flat sets of backward compat property names (some with prefix/name specific conversion) for each of those backward compat root class names. This is a deliberate design decision that makes microformats 2 more "micro", and yes this means that even with such backward compat support, this simple form of backward compat may mean that some existing microformats 1 content breaks. We'll assess those and iterate on a documented case-by-case basis rather than attempt to maintain theoretical 100% backward compatibility (since many current microformats format-specific-features are either unused, or may have caused more problems than solutions). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

N.B. I'll rewrite some of these as microformats-2-parsing-faq to help better clarify. The reasoning that led to most of these design decisions is documented in the [[microformats-2#About_This_Brainstorm|microformats 2: About This Brainstorm]] section and following sections. I'll recheck those sections to see if/where reasoning for some of the above noted design decisions may have been missed, and back-fill accordingly. This is necessary because [[microformats 2]] is a evolutionary result of simultaneously addressing both numerous generic [[issues]] as well as various common [[hcard-issues-resolved|format]]-[[hcalendar-issues-resolved|specific]] [[mfo|problems]] in microformats 1 syntax and vocabularies. The very number of changes may make it more challenging (from a microformats 1 perspective) to see why any particular design change has been made. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

==Parsing Literal Values==

It is proposed for microformats 2.0 that all microformats be parseable from just their root element, e.g. <code><p class="h-card">Ben Ward</p></code> would create an hCard with the following properties after parsing:

<source lang=javascript>
{
'type': ['h-card'],
'properties': {
'name': ['Ben Ward']
}
}
</source>

This is a four-fold change from the current [[hCard]]:
# type is generically identifiable as a microformat root, even in parsed form. The use of the 'h-' prefix persists into the type of the object. This is deliberately so, as a result of re-using the JSON data model of microdata which itself is re-using a common JSON convention, such that microformatted data is clearly distinguishable (as opposed to any other random schema that may be using a similar data model).
# root-class-only support. Per [[microformats-2-implied-properties]], the ''name'' property is implied by the entirety of the root class name element.
# 'name' instead of 'fn'. As also documented in [[microformats-2-implied-properties]], the continuous challenges/problems and need to repeatedly re-explain 'fn' over the years combined with the real-world market response of nearly every other party doing a person vocabulary renaming 'fn' to 'name', microformats 2 makes this change as well.
# There is no automatic parse-time inferring of <code>'given-name': ['Ben']</code> and <code>'family-name': ['Ward']</code>. Any such inferring *might* be made by a vCard converter, but is left up to that specific application (not all applications) built on that vocabulary, though even in that case it may not be necessary, as an empty "N:;;;" [[vCard]] property is sufficient to satisfy the N property requirement of [[vCard]], and also causes no problems when imported into various [[vcard-implementations]].

It is required of the extractor to understand that when a microformats object specifies no explicit child properties, that it must treat <code>h-card</code> as having a <code>p-name</code>. But, the parser is generic, so it also treats <code>h-review</code>, <code>h-entry</code>, <code>h-recipe</code>, <code>h-geo</code> as having a ‘<code>p-name</code>’.

As a result, specific vocabularies are evolved to drop their specific form of name (e.g. fn, summary, entry-title) and simplified to use a common 'name' property instead.

Note: while the overwhelming majority of real world publishing/consuming uses of microformats do so with proper nouns which have names (and thus this parser-level incorporation of an implied 'name'), there are some formats that do not have a 'name' semantic. For example, [[geo]], [[adr]], and possibly if/when developed, units of measure, length, cost. The current thinking is that the benefits to the far greater proper-noun use-case of microformats outweigh the technical inelegance of having an extra/ignored 'name' property on formats that lack such a semantic.

Some formats also may appear in theory to better imply some other property, e.g. a review might be thought to imply its ''content'', not its name, and an Atom entry its ''content'', not its title, but in practice (actual publishing patterns) this is not the case. Typically, brief unstructured reviews (or mentions thereof) provide a ''summary'' (often hyperlinked to an expanded structured form) of that review, not its content, and similarly, brief unstructured posts (e.g. RSS items) have historically most often been link blog items which include the title of an item and a link. Short status updates as well established by Twitter are newer and would seem to imply purely content with no title, at least semantically, however, even Twitter populates the RSS title and ATOM entry title of their feeds with the content. It's not clear what went into that decision, however, that's likely irrelevant, as the outcome turns out to be emergent consistency among publishing behaviors.

To avoid overloading or undermining the semantics of a vocabulary, I propose that we handle this at the extractor level in a simpler fashion: Define a new property for literal data, that an extractor will provide if no other information was available. All ''interpreters'' may then be instructed that in the event that an object has no properties, it can attempt to interpret the literal value from the page instead.
* This was one of the design iterations I went through which led me to the current implied 'name' design. Another iteration was the ability for a vocabulary to specify a single required property which was implied if there were no properties provided. However, the combination of the fact that in most cases such single required properties were quite name-like, and that a vocabulary-specific rule like that would then bind parsers to specific vocabularies (even so slightly) led me to collapse them into implying a 'name'. It's not perfect, but it's the best alternative so far that balances practical convenience of publishing/consuming, avoids vocabulary-specific knowledge in the parser, and technical (in)elegance. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

In existing microformats, the closest existing example we have for this is the <code>label</code> property in hCard, which is used to represent the literal address label for a place. It is a corresponding piece of <code>fn</code>, <code>org</code> and <code>adr</code> in combination, but has no structure in and of itself. Possibly, every microformat could have a <code>label</code> form where structured data is unavailable.

However in practice, the hCard <code>label</code> property is both little understood and little used. It's not even clear that it ought to be kept for microformats 2 (no known consumers, very few (if any?) real-world non-test publishers). This disuse is likely a good indicator that we should avoid basing anything on its design.

Alternatively, <code>value</code> is used throughout microformats to target a generic value (e.g. in combination with <code>price</code> in hListing.) It has been proposed that when parsing properties that are also themselves microformats, we create native objects of the form:

{
'value': '1900 12th Street, San Francisco, CA 94'
, 'type': ['adr']
, 'properties': {
'street-address': '1900 12th Street'
, 'etc': 'etc'
}
}

We could apply this same pattern to the root level:

{
type: [hcard]
, properties: {}
, value: 'Ben Ward'
}

In this case, an interpreter or implementation is responsible for using <code>value</code> in place of <code>fn</code>, or restructuring the object. It would be the responsibility of each vocabulary to define its root property. The parsing layer of microformats 2.0 would not impose semantics or naming onto that.

For another example, geo would end up like this:

{
type: [geo]
, properties: {}
, value: '1.3232;-0.543'
}

* This is an alternative I've been considering as well: [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)
** 'value' is more generic than 'name' (applies to more vocabularies) with the trade-off that it naturally has less (weaker) semantics.
*** +1 I think that having naturally weaker semantics would be appropriate for this parsing functionality. —[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC)
** The interesting thing that this analysis has revealed is that there appear to be two distinct clusters of microformats, the much more commonly used/understood/useful proper-noun microformats which markup things with names (people, events, reviews, recipes), and the less used compound-data microformats which are often used ''inside'' other microformats and just have some sort of semi-structured value (adr, geo, measure, and perhaps even things like tel). Perhaps this is implying the possibility and some degree of utility for ''two'' microformats root class name prefixes, 'h-' for existing proper-noun microformats, and something else ('m-' for microformat/molecule?, 's-' for structured-value?, 'v-' for value (though historically "v-"/"v." has meant "vendor-specific")?) for unnamed structured data microformats.
*** This more and more feels like a good idea, and I'm leaning toward "s-" for struct / structure / structured value. "s-" works just like "h-" except that it doesn't imply any properties at parse time. We can try it and see what happens. There's also no harm if publishers just use "h-" structures, they just (possibly) get a few extra properties if they happen to omit properties.
** Parallels the same JSON when a property has both a string value ''and'' is a structure itself.
*** Changed my mind on this. The parallel is not quite there. 'name'/'url'/'photo' are only implied if there are NO properties, where as the JSON string value + structure convention *always* provides a 'value'. [[User:Tantek|Tantek]] 22:39, 4 October 2011 (UTC)
*** And due to this difference in behavior ('value' is there when nested properties are present, whereas 'name' is only implied when there are no properties specified), I think it's correct to keep them separate, i.e. stick with implied 'name'. [[User:Tantek|Tantek]] 14:56, 5 October 2011 (UTC)
** However, I'm still currently leaning towards the practical convenience of providing a 'name' for the vast majority of microformats uses, rather than diluting this feature for the sake of avoiding implying inapplicable semantics to the few plain structured data microformats, and even then, only when no properties are explicitly specified! I'd rather introduce a new root prefix for those than lose the simplicity and utility of implied 'name'. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

==Parsing properties from rel attributes==

--[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC):

* Currently, hAtom parses `bookmark` as a permalink
* Various microformats parse `rel=tag` as tags
* The current proposal for parsing does not allow parsing properties from rel attributes.

Microformats parsers could instead extract ''all'' link relationships from rel attributes within an microformat object, parsing them as if a u- prefixed property.
* Minor nit: Rather than same as a u- prefixed property, I think such "rel" properties should be parsed purely from the <code>href</code> attribute on <code><a></code> and <code><area></code> elements and nothing more. I would strongly disagree to extending rel to apply to other elements with URLs like img src, object data, or to apply to elements in general like div. That's the path that RDFa has taken and caused much confusion as a result. [[User:Tantek|Tantek]] 07:39, 5 October 2011 (UTC)
** Agree: That seems like a perfectly reasonable restriction. --[[User:BenWard|BenWard]] 08:29, 5 October 2011 (UTC)

This results in:

* Continuing use of the <code>rel</code> attribute in HTML, thereby building on HTML semantics rather than bypassing them or ignoring them in favour of something less meaningful.
* Parsing hAtom objects contain a property named <code>bookmark</code>, in place of <code>permalink</code>.
* All microformats that use <code>rel-tag</code> would contain a property named… <code>tag</code>. Perfect.

Since <code>rel</code> attributes are not overloaded for other functionality like class is, and other uses of <code>rel</code> within content are low (and non-semantic uses are nil, to the best of my knowledge) the risk of property pollution would be extremely low.

Note, with regard to this last point, that a generic microformats parser ''will'' parse false-positive properties, and ''will'' parse objects in combined chunks, rather than individually by format. Extracted objects will often not represent a vocabulary without further processing.

<div class="discussion">
* This sounds like it might be workable. Let's try it and see how well authors "get it". - [[User:Tantek|Tantek]]
* Possible issue: do we have any collisions between class property names and rel names? (I don't think so offhand, but useful to ask the question). - [[User:Tantek|Tantek]]
** None that I can think of in microformats. There is the case of Google's <code>rel=author</code> and <code>p-author</code> in hAtom. However, the next point, about mfo scoping, would cover it in most situations (rel-author on a hyperlink within an hcard wouldn't be applied to the hentry.) The one situation in a parse tree where it's ambiguous would be this:
<source lang=html4strict>
<a href="p-author h-card"
rel="author"
href="http://benward.me">
Ben Ward
</a>
</source>
** I can think of two quite reasonable solutions:
*** 1. Declare that class properties take precedence over rel properties of the same name, discarding rel values if a class is also found, or
*** 2. Since all properties are now multi-value anyway, the hAtom object could be parsed as:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': ['Ben Ward'], /* from the p-author */
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},
'http://benward.me' /* from the rel="author" */
],
…
}
}
</source>
** —[[User:BenWard|BenWard]] 08:29, 5 October 2011 (UTC)
*** Option 2 makes sense and is consistent with the rest of the multi-value parsing/handling. - [[User:Tantek|Tantek]] 14:56, 5 October 2011 (UTC)
*** What about without the 'p-author'?
<source lang=html4strict>
<a href="h-card"
rel="author"
href="http://benward.me">
Ben Ward
</a>
</source>
Should that be parsed as:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},
'http://benward.me' /* from the rel="author" */
],
…
}
}
</source>
Or
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': 'http://benward.me' /* from the rel="author" */
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},

],
…
}
}
</source>
*** And if the former, then we're presumably saying that the value parsed due to the presence of a rel is always its own value, and does not combine with any other structures. I am fine with this, but I wanted to make sure we are ok with that explicitly. [[User:Tantek|Tantek]] 14:56, 5 October 2011 (UTC)
**** +1 I think that since the rel attribute is specifically concerned with the relation to an href attribute, it should not be combined with other structures that are rightly declared uses classes.
***** The more I've thought about this and how consuming applications may want to treat rel semantics, the more it seems correct to keep rel semantics distinct from class semantics. Class semantics are quite general/flexible, whereas rel is quite specific, naming something else in terms of a relationship from the current page/microformat's perspective. I think we should consider putting rel values in their own 'rel' collection, separate from the 'properties' collection. E.g. the original rel-author p-author h-card markup example would be parsed into this:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': ['Ben Ward'], /* from the p-author */
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
}
],
…
}
'rel': {
'author': ['http://benward.me'] /* from the rel="author" */
}
}
</source>
***** and if a post had multiple authors:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': ['Ben Ward'], /* from p-author */
'type': ['h-card'], /* from h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},
{
'value': ['Tantek Çelik'], /* from 2nd p-author */
'type': ['h-card'], /* from 2nd h-card ... */
'properties': {
'name': ['Tantek Çelik'],
'url': ['http://tantek.com']
},
],
…
}
'rel': {
'author': [
'http://benward.me', /* from rel="author" */
'http://tantek.com' /* from 2nd rel="author" */
]
}
}
</source>
***** This preserves the semantic distinction between rel and properties in general, and leaves it up to a higher-level application to implement any logic around showing "more info" about a rel-author, e.g. by correlating the rel-author URL with the 'url' of an hCard it found in the same entry. However, note that even in the earlier JSON data model, the rel-author value just shows up as another property value, and any higher level application would still have to do some correlation logic. At least with this JSON data model, applications that may be looking for a rel value in particular, or a property value in particular can do so without having one unintentionally pollute the other. [[User:Tantek|Tantek]] 17:33, 6 October 2011 (UTC)

* Presumably we'd apply all the same property scoping rules to rel scoping as well. E.g. a rel hyperlink inside a microformat won't be seen by any containing microformat. - [[User:Tantek|Tantek]]
** Correct, it should be parsed in the same scope as all other class properties in the object.
</div>

==Other Interpretation/Parsing Notes==

Collection of other unresolved parsing issues in a generic model:

This is good material for documenting as [[microformats-2-issues]], [[microformats-2-faq]], and perhaps some of the more technical details in [[microformats-2-parsing-faq]].

* The include pattern references other elements from elsewhere in a document. A generic parser needs to track IDs and fill them in after walking the DOM. (also, <code>itemref</code> if adopted.)
** The current thinking per [[microformats-2-brainstorming]] is to adopt <code>itemref</code> and drop the [[include-pattern]]. [[User:Tantek|Tantek]]
* Will <code>itemref</code> always map to an <code>item</code> property name?
** No, <code>itemref</code> maps to one or more elements by ids, and their children. Those referenced elements may have property class names themselves, or they may contain elements that do. [[User:Tantek|Tantek]]
* [[hAtom]] implies <code>author</code> from an hCard in a page that uses an <code>address</code> element. This requires format knowledge, but a generic parser does not currently track the element type of a property node. Should it?
** It should not. element-specific handling (e.g. using "alt" from img, and "title" from abbr) is completely done at parse time. The JSON data model does not reflect which element type or attribute the value came from. Additionally, [[hAtom]] is an example where we created far too many vocabulary-specific rules, in practice they're not necessary, and only complicate the microformat for both publisher understanding and parser implementation. [[User:Tantek|Tantek]]
* [[hAtom]] defines that the highest level heading within an entry implies <code>entry-title</code>. This particular optimisation might be better off dead.
** Agreed, this is gone in microformats 2. [[User:Tantek|Tantek]]
* [[hAtom]] defines that permalinks be parsed from <code>rel</code> attributes, not <code>class</code>
** In practice this has been one of the more problematic/error prone aspects of hAtom implementations, and it's also inconsistent with other microformats (although [[hReview]] tried to use both rel permalinks and "url"). The dependence upon [[rel-bookmark]] for permalinks is dropped in h-atom in preference to re-using "u-url" and "u-uid". [[User:Tantek|Tantek]]
* [[XFN]] is entirely built on <code>rel</code> (although, has various other differences from structural microformats, as do vote-links, so perhaps are excluded from this discussion and will always be handled by dedicated parsers/queries regardless?)
** The best (easiest and most reliable) use of 'rel' microformats in practice is when they are orthogonal to 'class' microformats. This is true both with [[XFN]] and some newer [[existing-rel-values|rel values]] like [[rel-author]]. In addition, it was very clear at the recent [[schema.org]] workshop's syntax session that RDFa's decision to apparently arbitrarily mix use of 'rel' and 'property' attributes for specifying different types of properties (it wasn't clear to people in the room when you use which for what) has caused a high degree of confusion among publishers and thus high error-rates. Thus if anything we should learn from both the mistakes of RDFa and our own experiences with even very deliberate/specific mixing of rel microformats in class microformats, and keep them defined as separate orthogonal building blocks that work together, but don't depend on each other. [[User:Tantek|Tantek]]
*** Relatedly to this: <code>rel-tag</code> in hAtom. --[[User:BenWard|BenWard]] 06:50, 5 October 2011 (UTC)
**** Yes, and two related things here. First, despite my (and others') objection and (past) interoperable post/entry-specific treatment by Technorati and Ice Rocket, Hixie has redefined rel-tag in [[HTML5]] to mean applying to the whole page, not a single post. Second, I've explicitly added 'p-category' to the draft 'h-atom' vocabulary in [[microformats-2]]. [[User:Tantek|Tantek]] 07:12, 5 October 2011 (UTC)
* HTML's <code>time</code> element includes an optional <code>pubdate</code> attribute. Simply: We should parse this as <code>dt-published</code>. --[[User:BenWard|BenWard]] 06:12, 10 October 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-faq]]
* [[microformats-2-issues]]
* [[microformats-2-parsing-faq]]

microformats2-parsing-brainstorming

2011-10-06T08:14:01Z

BenWard: Agree that rel sourced properties should *not* combine with nested microformat objects.

Author: [[User:BenWard|Ben Ward]]

[[microformats-2|Microformats 2]] proposes a new, all encompassing syntax modification of [[microformats-2-prefixes|prefixes]] that will allow microformats to be parsed from pages by processors without prior knowledge of a vocabulary. The core components of this model are quite simple, are quite simple to implement, but there are a number of conflicts that emerge with the functionality of existing microformats parsers that need to be handled. This page documents a proposed model to separate these concerns clearly in a way that can be applied to the documentation of generic microformats parsing rules, and the documentation of individual vocabularies.

==Parsing Microformats 2.0 Syntax: Extraction vs. Interpretation==

A microformats ‘1.0’ parser performs the following function:

* Given a piece of HTML content, discover a known microformat, extract it, apply various extraction patterns based upon the HTML mark-up used (e.g. include pattern, <code>abbr</code> patterns, date-time patterns, value-title pattern), apply various content optimisations where applicable, and return the result in an object native to the programming language.

This is performing two types of function: Extraction of data from an HTML document or fragment, ''and'' interpretation and optimisation of that content to match the rules set out by a vocabulary specification.

It is only possible to write a generic parser that covers the first half of this task: Extraction, and application of global rules based on HTML elements and patterns common to all formats.

The purpose of a generic parser (as supported by use cases such as search engines, and other crawlers) is:

To provide a way for tools to extract rich data from a page for native storage, such that the data may be interpreted later by applications. This allows microformats to be crawled, and indexed, and removes the need to include complex HTML parsing within every implementation of microformat data.

Microformats will continue to define various vocabulary-specific optimisations. as part of the design to be optimised for authors. For example: The <code>fn</code> pattern in [[hcard]], or the <code>lat;long</code> pattern in [[geo]], as well as default values for properties, such as the maximum rating in an [[hreview]].
* Actually, no, as it is defined currently, microformats 2 ''drops'' vocabulary-specific optimizations. Such optimizations have often been too inapplicable, error prone or i18n-unsafe (e.g. fn to given-name + family-name fails for both numerous cases where middlenames/initials are used, and in general in numerous Asian languages where given/family name order is the reverse of Western English conventions, or languages with multiple family-names, e.g. Spanish - see [[hcard-issues-resolved]] for more). This is a deliberate cutting of a "feature" from microformats 1, it is a deliberate model simplification design decision. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

Microformats 2.0 should refer only to ''extraction'' of microformats. Vocabularies should in turn document their appropriate optimisations, which will need to be applied by implementations, or a companion to an extractor, which I'll refer to here as an ‘interpreter’.
* Vocabularies will no longer have optimizations, this is again deliberately, as they've been shown to be more error prone than helpful. Thus there should be no need for any vocabulary-specific 'interpreters'. However, due to design quirks in various legacy/interchange formats, ''export conversions algorithms'' to those legacy/interchange formats will require some additional legacy-format-specific rules (e.g. odd "required" rules in [[Atom]] or [[vCard]] will require specific synthesis rules, limitations in said formats will require filtering of some values, e.g. [[vcard3]] BDAY disallows vague birthdays like year-month and --month-day - subsequently allowed in [[vcard4]]). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

A microformats 2.0 ‘extractor’, in combination with the functionality of a domain and format-aware ‘interpreter’ (either another shared component, or part of the implementation itself) would be equivalent to a microformats 1.0 ‘parser.’
* A microformats 2.0 parser is both generic (no knowledge of specific vocabularies), and lacks any/all such vocabulary-specific rules as compared to a microformats 1.0 [[hcard-parsing|parser]] with the exception of a 1) a limited list of well-established/interoperable backward compat root class names (of current [[microformats]] that are or can be soon shown to be specifications/standards per the [[process]]), 2) flat sets of backward compat property names (some with prefix/name specific conversion) for each of those backward compat root class names. This is a deliberate design decision that makes microformats 2 more "micro", and yes this means that even with such backward compat support, this simple form of backward compat may mean that some existing microformats 1 content breaks. We'll assess those and iterate on a documented case-by-case basis rather than attempt to maintain theoretical 100% backward compatibility (since many current microformats format-specific-features are either unused, or may have caused more problems than solutions). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

N.B. I'll rewrite some of these as microformats-2-parsing-faq to help better clarify. The reasoning that led to most of these design decisions is documented in the [[microformats-2#About_This_Brainstorm|microformats 2: About This Brainstorm]] section and following sections. I'll recheck those sections to see if/where reasoning for some of the above noted design decisions may have been missed, and back-fill accordingly. This is necessary because [[microformats 2]] is a evolutionary result of simultaneously addressing both numerous generic [[issues]] as well as various common [[hcard-issues-resolved|format]]-[[hcalendar-issues-resolved|specific]] [[mfo|problems]] in microformats 1 syntax and vocabularies. The very number of changes may make it more challenging (from a microformats 1 perspective) to see why any particular design change has been made. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

==Parsing Literal Values==

It is proposed for microformats 2.0 that all microformats be parseable from just their root element, e.g. <code><p class="h-card">Ben Ward</p></code> would create an hCard with the following properties after parsing:

<source lang=javascript>
{
'type': ['h-card'],
'properties': {
'name': ['Ben Ward']
}
}
</source>

This is a four-fold change from the current [[hCard]]:
# type is generically identifiable as a microformat root, even in parsed form. The use of the 'h-' prefix persists into the type of the object. This is deliberately so, as a result of re-using the JSON data model of microdata which itself is re-using a common JSON convention, such that microformatted data is clearly distinguishable (as opposed to any other random schema that may be using a similar data model).
# root-class-only support. Per [[microformats-2-implied-properties]], the ''name'' property is implied by the entirety of the root class name element.
# 'name' instead of 'fn'. As also documented in [[microformats-2-implied-properties]], the continuous challenges/problems and need to repeatedly re-explain 'fn' over the years combined with the real-world market response of nearly every other party doing a person vocabulary renaming 'fn' to 'name', microformats 2 makes this change as well.
# There is no automatic parse-time inferring of <code>'given-name': ['Ben']</code> and <code>'family-name': ['Ward']</code>. Any such inferring *might* be made by a vCard converter, but is left up to that specific application (not all applications) built on that vocabulary, though even in that case it may not be necessary, as an empty "N:;;;" [[vCard]] property is sufficient to satisfy the N property requirement of [[vCard]], and also causes no problems when imported into various [[vcard-implementations]].

It is required of the extractor to understand that when a microformats object specifies no explicit child properties, that it must treat <code>h-card</code> as having a <code>p-name</code>. But, the parser is generic, so it also treats <code>h-review</code>, <code>h-entry</code>, <code>h-recipe</code>, <code>h-geo</code> as having a ‘<code>p-name</code>’.

As a result, specific vocabularies are evolved to drop their specific form of name (e.g. fn, summary, entry-title) and simplified to use a common 'name' property instead.

Note: while the overwhelming majority of real world publishing/consuming uses of microformats do so with proper nouns which have names (and thus this parser-level incorporation of an implied 'name'), there are some formats that do not have a 'name' semantic. For example, [[geo]], [[adr]], and possibly if/when developed, units of measure, length, cost. The current thinking is that the benefits to the far greater proper-noun use-case of microformats outweigh the technical inelegance of having an extra/ignored 'name' property on formats that lack such a semantic.

Some formats also may appear in theory to better imply some other property, e.g. a review might be thought to imply its ''content'', not its name, and an Atom entry its ''content'', not its title, but in practice (actual publishing patterns) this is not the case. Typically, brief unstructured reviews (or mentions thereof) provide a ''summary'' (often hyperlinked to an expanded structured form) of that review, not its content, and similarly, brief unstructured posts (e.g. RSS items) have historically most often been link blog items which include the title of an item and a link. Short status updates as well established by Twitter are newer and would seem to imply purely content with no title, at least semantically, however, even Twitter populates the RSS title and ATOM entry title of their feeds with the content. It's not clear what went into that decision, however, that's likely irrelevant, as the outcome turns out to be emergent consistency among publishing behaviors.

To avoid overloading or undermining the semantics of a vocabulary, I propose that we handle this at the extractor level in a simpler fashion: Define a new property for literal data, that an extractor will provide if no other information was available. All ''interpreters'' may then be instructed that in the event that an object has no properties, it can attempt to interpret the literal value from the page instead.
* This was one of the design iterations I went through which led me to the current implied 'name' design. Another iteration was the ability for a vocabulary to specify a single required property which was implied if there were no properties provided. However, the combination of the fact that in most cases such single required properties were quite name-like, and that a vocabulary-specific rule like that would then bind parsers to specific vocabularies (even so slightly) led me to collapse them into implying a 'name'. It's not perfect, but it's the best alternative so far that balances practical convenience of publishing/consuming, avoids vocabulary-specific knowledge in the parser, and technical (in)elegance. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

In existing microformats, the closest existing example we have for this is the <code>label</code> property in hCard, which is used to represent the literal address label for a place. It is a corresponding piece of <code>fn</code>, <code>org</code> and <code>adr</code> in combination, but has no structure in and of itself. Possibly, every microformat could have a <code>label</code> form where structured data is unavailable.

However in practice, the hCard <code>label</code> property is both little understood and little used. It's not even clear that it ought to be kept for microformats 2 (no known consumers, very few (if any?) real-world non-test publishers). This disuse is likely a good indicator that we should avoid basing anything on its design.

Alternatively, <code>value</code> is used throughout microformats to target a generic value (e.g. in combination with <code>price</code> in hListing.) It has been proposed that when parsing properties that are also themselves microformats, we create native objects of the form:

{
'value': '1900 12th Street, San Francisco, CA 94'
, 'type': ['adr']
, 'properties': {
'street-address': '1900 12th Street'
, 'etc': 'etc'
}
}

We could apply this same pattern to the root level:

{
type: [hcard]
, properties: {}
, value: 'Ben Ward'
}

In this case, an interpreter or implementation is responsible for using <code>value</code> in place of <code>fn</code>, or restructuring the object. It would be the responsibility of each vocabulary to define its root property. The parsing layer of microformats 2.0 would not impose semantics or naming onto that.

For another example, geo would end up like this:

{
type: [geo]
, properties: {}
, value: '1.3232;-0.543'
}

* This is an alternative I've been considering as well: [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)
** 'value' is more generic than 'name' (applies to more vocabularies) with the trade-off that it naturally has less (weaker) semantics.
*** +1 I think that having naturally weaker semantics would be appropriate for this parsing functionality. —[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC)
** The interesting thing that this analysis has revealed is that there appear to be two distinct clusters of microformats, the much more commonly used/understood/useful proper-noun microformats which markup things with names (people, events, reviews, recipes), and the less used compound-data microformats which are often used ''inside'' other microformats and just have some sort of semi-structured value (adr, geo, measure, and perhaps even things like tel). Perhaps this is implying the possibility and some degree of utility for ''two'' microformats root class name prefixes, 'h-' for existing proper-noun microformats, and something else ('m-' for microformat/molecule?, 's-' for structured-value?, 'v-' for value (though historically "v-"/"v." has meant "vendor-specific")?) for unnamed structured data microformats.
*** This more and more feels like a good idea, and I'm leaning toward "s-" for struct / structure / structured value. "s-" works just like "h-" except that it doesn't imply any properties at parse time. We can try it and see what happens. There's also no harm if publishers just use "h-" structures, they just (possibly) get a few extra properties if they happen to omit properties.
** Parallels the same JSON when a property has both a string value ''and'' is a structure itself.
*** Changed my mind on this. The parallel is not quite there. 'name'/'url'/'photo' are only implied if there are NO properties, where as the JSON string value + structure convention *always* provides a 'value'. [[User:Tantek|Tantek]] 22:39, 4 October 2011 (UTC)
*** And due to this difference in behavior ('value' is there when nested properties are present, whereas 'name' is only implied when there are no properties specified), I think it's correct to keep them separate, i.e. stick with implied 'name'. [[User:Tantek|Tantek]] 14:56, 5 October 2011 (UTC)
** However, I'm still currently leaning towards the practical convenience of providing a 'name' for the vast majority of microformats uses, rather than diluting this feature for the sake of avoiding implying inapplicable semantics to the few plain structured data microformats, and even then, only when no properties are explicitly specified! I'd rather introduce a new root prefix for those than lose the simplicity and utility of implied 'name'. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

==Parsing properties from rel attributes==

--[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC):

* Currently, hAtom parses `bookmark` as a permalink
* Various microformats parse `rel=tag` as tags
* The current proposal for parsing does not allow parsing properties from rel attributes.

Microformats parsers could instead extract ''all'' link relationships from rel attributes within an microformat object, parsing them as if a u- prefixed property.
* Minor nit: Rather than same as a u- prefixed property, I think such "rel" properties should be parsed purely from the <code>href</code> attribute on <code><a></code> and <code><area></code> elements and nothing more. I would strongly disagree to extending rel to apply to other elements with URLs like img src, object data, or to apply to elements in general like div. That's the path that RDFa has taken and caused much confusion as a result. [[User:Tantek|Tantek]] 07:39, 5 October 2011 (UTC)
** Agree: That seems like a perfectly reasonable restriction. --[[User:BenWard|BenWard]] 08:29, 5 October 2011 (UTC)

This results in:

* Continuing use of the <code>rel</code> attribute in HTML, thereby building on HTML semantics rather than bypassing them or ignoring them in favour of something less meaningful.
* Parsing hAtom objects contain a property named <code>bookmark</code>, in place of <code>permalink</code>.
* All microformats that use <code>rel-tag</code> would contain a property named… <code>tag</code>. Perfect.

Since <code>rel</code> attributes are not overloaded for other functionality like class is, and other uses of <code>rel</code> within content are low (and non-semantic uses are nil, to the best of my knowledge) the risk of property pollution would be extremely low.

Note, with regard to this last point, that a generic microformats parser ''will'' parse false-positive properties, and ''will'' parse objects in combined chunks, rather than individually by format. Extracted objects will often not represent a vocabulary without further processing.

<div class="discussion">
* This sounds like it might be workable. Let's try it and see how well authors "get it". - [[User:Tantek|Tantek]]
* Possible issue: do we have any collisions between class property names and rel names? (I don't think so offhand, but useful to ask the question). - [[User:Tantek|Tantek]]
** None that I can think of in microformats. There is the case of Google's <code>rel=author</code> and <code>p-author</code> in hAtom. However, the next point, about mfo scoping, would cover it in most situations (rel-author on a hyperlink within an hcard wouldn't be applied to the hentry.) The one situation in a parse tree where it's ambiguous would be this:
<source lang=html4strict>
<a href="p-author h-card"
rel="author"
href="http://benward.me">
Ben Ward
</a>
</source>
** I can think of two quite reasonable solutions:
*** 1. Declare that class properties take precedence over rel properties of the same name, discarding rel values if a class is also found, or
*** 2. Since all properties are now multi-value anyway, the hAtom object could be parsed as:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': ['Ben Ward'], /* from the p-author */
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},
'http://benward.me' /* from the rel="author" */
],
…
}
}
</source>
** —[[User:BenWard|BenWard]] 08:29, 5 October 2011 (UTC)
*** Option 2 makes sense and is consistent with the rest of the multi-value parsing/handling. - [[User:Tantek|Tantek]] 14:56, 5 October 2011 (UTC)
*** What about without the 'p-author'?
<source lang=html4strict>
<a href="h-card"
rel="author"
href="http://benward.me">
Ben Ward
</a>
</source>
Should that be parsed as:
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},
'http://benward.me' /* from the rel="author" */
],
…
}
}
</source>
Or
<source lang=javascript>
{
'type': ['h-entry'],
'properties': {
…
'author': [
{
'value': 'http://benward.me' /* from the rel="author" */
'type': ['h-card'], /* from the h-card ... */
'properties': {
'name': ['Ben Ward'],
'url': ['http://benward.me']
},

],
…
}
}
</source>
*** And if the former, then we're presumably saying that the value parsed due to the presence of a rel is always its own value, and does not combine with any other structures. I am fine with this, but I wanted to make sure we are ok with that explicitly. [[User:Tantek|Tantek]] 14:56, 5 October 2011 (UTC)
**** +1 I think that since the rel attribute is specifically concerned with the relation to an href attribute, it should not be combined with other structures that are rightly declared uses classes.

* Presumably we'd apply all the same property scoping rules to rel scoping as well. E.g. a rel hyperlink inside a microformat won't be seen by any containing microformat. - [[User:Tantek|Tantek]]
** Correct, it should be parsed in the same scope as all other class properties in the object.
</div>

==Other Interpretation/Parsing Notes==

Collection of other unresolved parsing issues in a generic model:

This is good material for documenting as [[microformats-2-issues]], [[microformats-2-faq]], and perhaps some of the more technical details in [[microformats-2-parsing-faq]].

* The include pattern references other elements from elsewhere in a document. A generic parser needs to track IDs and fill them in after walking the DOM. (also, <code>itemref</code> if adopted.)
** The current thinking per [[microformats-2-brainstorming]] is to adopt <code>itemref</code> and drop the [[include-pattern]]. [[User:Tantek|Tantek]]
* Will <code>itemref</code> always map to an <code>item</code> property name?
** No, <code>itemref</code> maps to one or more elements by ids, and their children. Those referenced elements may have property class names themselves, or they may contain elements that do. [[User:Tantek|Tantek]]
* [[hAtom]] implies <code>author</code> from an hCard in a page that uses an <code>address</code> element. This requires format knowledge, but a generic parser does not currently track the element type of a property node. Should it?
** It should not. element-specific handling (e.g. using "alt" from img, and "title" from abbr) is completely done at parse time. The JSON data model does not reflect which element type or attribute the value came from. Additionally, [[hAtom]] is an example where we created far too many vocabulary-specific rules, in practice they're not necessary, and only complicate the microformat for both publisher understanding and parser implementation. [[User:Tantek|Tantek]]
* [[hAtom]] defines that the highest level heading within an entry implies <code>entry-title</code>. This particular optimisation might be better off dead.
** Agreed, this is gone in microformats 2. [[User:Tantek|Tantek]]
* [[hAtom]] defines that permalinks be parsed from <code>rel</code> attributes, not <code>class</code>
** In practice this has been one of the more problematic/error prone aspects of hAtom implementations, and it's also inconsistent with other microformats (although [[hReview]] tried to use both rel permalinks and "url"). The dependence upon [[rel-bookmark]] for permalinks is dropped in h-atom in preference to re-using "u-url" and "u-uid". [[User:Tantek|Tantek]]
* [[XFN]] is entirely built on <code>rel</code> (although, has various other differences from structural microformats, as do vote-links, so perhaps are excluded from this discussion and will always be handled by dedicated parsers/queries regardless?)
** The best (easiest and most reliable) use of 'rel' microformats in practice is when they are orthogonal to 'class' microformats. This is true both with [[XFN]] and some newer [[existing-rel-values|rel values]] like [[rel-author]]. In addition, it was very clear at the recent [[schema.org]] workshop's syntax session that RDFa's decision to apparently arbitrarily mix use of 'rel' and 'property' attributes for specifying different types of properties (it wasn't clear to people in the room when you use which for what) has caused a high degree of confusion among publishers and thus high error-rates. Thus if anything we should learn from both the mistakes of RDFa and our own experiences with even very deliberate/specific mixing of rel microformats in class microformats, and keep them defined as separate orthogonal building blocks that work together, but don't depend on each other. [[User:Tantek|Tantek]]
*** Relatedly to this: <code>rel-tag</code> in hAtom. --[[User:BenWard|BenWard]] 06:50, 5 October 2011 (UTC)
**** Yes, and two related things here. First, despite my (and others') objection and (past) interoperable post/entry-specific treatment by Technorati and Ice Rocket, Hixie has redefined rel-tag in [[HTML5]] to mean applying to the whole page, not a single post. Second, I've explicitly added 'p-category' to the draft 'h-atom' vocabulary in [[microformats-2]]. [[User:Tantek|Tantek]] 07:12, 5 October 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-faq]]
* [[microformats-2-issues]]
* [[microformats-2-parsing-faq]]

microformats2-parsing-brainstorming

2011-10-05T08:29:36Z

BenWard: /* Parsing properties from rel attributes */ Proposed handlings for possible rel/class conflicts (with 'author' example)

Author: [[User:BenWard|Ben Ward]]

[[microformats-2|Microformats 2]] proposes a new, all encompassing syntax modification of [[microformats-2-prefixes|prefixes]] that will allow microformats to be parsed from pages by processors without prior knowledge of a vocabulary. The core components of this model are quite simple, are quite simple to implement, but there are a number of conflicts that emerge with the functionality of existing microformats parsers that need to be handled. This page documents a proposed model to separate these concerns clearly in a way that can be applied to the documentation of generic microformats parsing rules, and the documentation of individual vocabularies.

==Parsing Microformats 2.0 Syntax: Extraction vs. Interpretation==

A microformats ‘1.0’ parser performs the following function:

* Given a piece of HTML content, discover a known microformat, extract it, apply various extraction patterns based upon the HTML mark-up used (e.g. include pattern, <code>abbr</code> patterns, date-time patterns, value-title pattern), apply various content optimisations where applicable, and return the result in an object native to the programming language.

This is performing two types of function: Extraction of data from an HTML document or fragment, ''and'' interpretation and optimisation of that content to match the rules set out by a vocabulary specification.

It is only possible to write a generic parser that covers the first half of this task: Extraction, and application of global rules based on HTML elements and patterns common to all formats.

The purpose of a generic parser (as supported by use cases such as search engines, and other crawlers) is:

To provide a way for tools to extract rich data from a page for native storage, such that the data may be interpreted later by applications. This allows microformats to be crawled, and indexed, and removes the need to include complex HTML parsing within every implementation of microformat data.

Microformats will continue to define various vocabulary-specific optimisations. as part of the design to be optimised for authors. For example: The <code>fn</code> pattern in [[hcard]], or the <code>lat;long</code> pattern in [[geo]], as well as default values for properties, such as the maximum rating in an [[hreview]].
* Actually, no, as it is defined currently, microformats 2 ''drops'' vocabulary-specific optimizations. Such optimizations have often been too inapplicable, error prone or i18n-unsafe (e.g. fn to given-name + family-name fails for both numerous cases where middlenames/initials are used, and in general in numerous Asian languages where given/family name order is the reverse of Western English conventions, or languages with multiple family-names, e.g. Spanish - see [[hcard-issues-resolved]] for more). This is a deliberate cutting of a "feature" from microformats 1, it is a deliberate model simplification design decision. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

Microformats 2.0 should refer only to ''extraction'' of microformats. Vocabularies should in turn document their appropriate optimisations, which will need to be applied by implementations, or a companion to an extractor, which I'll refer to here as an ‘interpreter’.
* Vocabularies will no longer have optimizations, this is again deliberately, as they've been shown to be more error prone than helpful. Thus there should be no need for any vocabulary-specific 'interpreters'. However, due to design quirks in various legacy/interchange formats, ''export conversions algorithms'' to those legacy/interchange formats will require some additional legacy-format-specific rules (e.g. odd "required" rules in [[Atom]] or [[vCard]] will require specific synthesis rules, limitations in said formats will require filtering of some values, e.g. [[vcard3]] BDAY disallows vague birthdays like year-month and --month-day - subsequently allowed in [[vcard4]]). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

A microformats 2.0 ‘extractor’, in combination with the functionality of a domain and format-aware ‘interpreter’ (either another shared component, or part of the implementation itself) would be equivalent to a microformats 1.0 ‘parser.’
* A microformats 2.0 parser is both generic (no knowledge of specific vocabularies), and lacks any/all such vocabulary-specific rules as compared to a microformats 1.0 [[hcard-parsing|parser]] with the exception of a 1) a limited list of well-established/interoperable backward compat root class names (of current [[microformats]] that are or can be soon shown to be specifications/standards per the [[process]]), 2) flat sets of backward compat property names (some with prefix/name specific conversion) for each of those backward compat root class names. This is a deliberate design decision that makes microformats 2 more "micro", and yes this means that even with such backward compat support, this simple form of backward compat may mean that some existing microformats 1 content breaks. We'll assess those and iterate on a documented case-by-case basis rather than attempt to maintain theoretical 100% backward compatibility (since many current microformats format-specific-features are either unused, or may have caused more problems than solutions). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

N.B. I'll rewrite some of these as microformats-2-parsing-faq to help better clarify. The reasoning that led to most of these design decisions is documented in the [[microformats-2#About_This_Brainstorm|microformats 2: About This Brainstorm]] section and following sections. I'll recheck those sections to see if/where reasoning for some of the above noted design decisions may have been missed, and back-fill accordingly. This is necessary because [[microformats 2]] is a evolutionary result of simultaneously addressing both numerous generic [[issues]] as well as various common [[hcard-issues-resolved|format]]-[[hcalendar-issues-resolved|specific]] [[mfo|problems]] in microformats 1 syntax and vocabularies. The very number of changes may make it more challenging (from a microformats 1 perspective) to see why any particular design change has been made. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

==Parsing Literal Values==

It is proposed for microformats 2.0 that all microformats be parseable from just their root element, e.g. <code><p class="h-card">Ben Ward</p></code> would create an hCard with the following properties after parsing:

<source lang=javascript>
{
'type': ['h-card'],
'properties': {
'name': ['Ben Ward']
}
}
</source>

This is a four-fold change from the current [[hCard]]:
# type is generically identifiable as a microformat root, even in parsed form. The use of the 'h-' prefix persists into the type of the object. This is deliberately so, as a result of re-using the JSON data model of microdata which itself is re-using a common JSON convention, such that microformatted data is clearly distinguishable (as opposed to any other random schema that may be using a similar data model).
# root-class-only support. Per [[microformats-2-implied-properties]], the ''name'' property is implied by the entirety of the root class name element.
# 'name' instead of 'fn'. As also documented in [[microformats-2-implied-properties]], the continuous challenges/problems and need to repeatedly re-explain 'fn' over the years combined with the real-world market response of nearly every other party doing a person vocabulary renaming 'fn' to 'name', microformats 2 makes this change as well.
# There is no automatic parse-time inferring of <code>'given-name': ['Ben']</code> and <code>'family-name': ['Ward']</code>. Any such inferring *might* be made by a vCard converter, but is left up to that specific application (not all applications) built on that vocabulary, though even in that case it may not be necessary, as an empty "N:;;;" [[vCard]] property is sufficient to satisfy the N property requirement of [[vCard]], and also causes no problems when imported into various [[vcard-implementations]].

It is required of the extractor to understand that when a microformats object specifies no explicit child properties, that it must treat <code>h-card</code> as having a <code>p-name</code>. But, the parser is generic, so it also treats <code>h-review</code>, <code>h-entry</code>, <code>h-recipe</code>, <code>h-geo</code> as having a ‘<code>p-name</code>’.

As a result, specific vocabularies are evolved to drop their specific form of name (e.g. fn, summary, entry-title) and simplified to use a common 'name' property instead.

Note: while the overwhelming majority of real world publishing/consuming uses of microformats do so with proper nouns which have names (and thus this parser-level incorporation of an implied 'name'), there are some formats that do not have a 'name' semantic. For example, [[geo]], [[adr]], and possibly if/when developed, units of measure, length, cost. The current thinking is that the benefits to the far greater proper-noun use-case of microformats outweigh the technical inelegance of having an extra/ignored 'name' property on formats that lack such a semantic.

Some formats also may appear in theory to better imply some other property, e.g. a review might be thought to imply its ''content'', not its name, and an Atom entry its ''content'', not its title, but in practice (actual publishing patterns) this is not the case. Typically, brief unstructured reviews (or mentions thereof) provide a ''summary'' (often hyperlinked to an expanded structured form) of that review, not its content, and similarly, brief unstructured posts (e.g. RSS items) have historically most often been link blog items which include the title of an item and a link. Short status updates as well established by Twitter are newer and would seem to imply purely content with no title, at least semantically, however, even Twitter populates the RSS title and ATOM entry title of their feeds with the content. It's not clear what went into that decision, however, that's likely irrelevant, as the outcome turns out to be emergent consistency among publishing behaviors.

To avoid overloading or undermining the semantics of a vocabulary, I propose that we handle this at the extractor level in a simpler fashion: Define a new property for literal data, that an extractor will provide if no other information was available. All ''interpreters'' may then be instructed that in the event that an object has no properties, it can attempt to interpret the literal value from the page instead.
* This was one of the design iterations I went through which led me to the current implied 'name' design. Another iteration was the ability for a vocabulary to specific a single required property which was implied if there were no properties provided. However, the combination of the fact that in most cases such single required properties were quite name-like, and that a vocabulary-specific rule like that would then bind parsers to specific vocabularies (even so slightly) let me to collapse them into implying a 'name'. It's not perfect, but it's the best alternative so far that balances practical convenience of publishing/consuming, avoids vocabulary-specific knowledge in the parser, and technical elegance. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

In existing microformats, the closest existing example we have for this is the <code>label</code> property in hCard, which is used to represent the literal address label for a place. It is a corresponding piece of <code>fn</code>, <code>org</code> and <code>adr</code> in combination, but has no structure in and of itself. Possibly, every microformat could have a <code>label</code> form where structured data is unavailable.

However in practice, the hCard <code>label</code> property is both little understood and little used. It's not even clear that it ought to be kept for microformats 2 (no known consumers, very few (if any?) real-world non-test publishers). This disuse is likely a good indicator that we should avoid basing anything on its design.

Alternatively, <code>value</code> is used throughout microformats to target a generic value (e.g. in combination with <code>price</code> in hListing.) It has been proposed that when parsing properties that are also themselves microformats, we create native objects of the form:

{
'value': '1900 12th Street, San Francisco, CA 94'
, 'type': ['adr']
, 'properties': {
'street-address': '1900 12th Street'
, 'etc': 'etc'
}
}

We could apply this same pattern to the root level:

{
type: [hcard]
, properties: {}
, value: 'Ben Ward'
}

In this case, an interpreter or implementation is responsible for using <code>value</code> in place of <code>fn</code>, or restructuring the object. It would be the responsibility of each vocabulary to define its root property. The parsing layer of microformats 2.0 would not impose semantics or naming onto that.

For another example, geo would end up like this:

{
type: [geo]
, properties: {}
, value: '1.3232;-0.543'
}

* This is an alternative I've been considering as well: [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)
** 'value' is more generic than 'name' (applies to more vocabularies) with the trade-off that it naturally has less (weaker) semantics.
*** +1 I think that having naturally weaker semantics would be appropriate for this parsing functionality. —[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC)
** The interesting thing that this analysis has revealed is that there appear to be two distinct clusters of microformats, the much more commonly used/understood/useful proper-noun microformats which markup things with names (people, events, reviews, recipes), and the less used compound-data microformats which are often used ''inside'' other microformats and just have some sort of semi-structured value (adr, geo, measure, and perhaps even things like tel). Perhaps this is implying the possibility and some degree of utility for ''two'' microformats root class name prefixes, 'h-' for existing proper-noun microformats, and something else ('m-' for microformat/molecule?, 's-' for structured-value?, 'v-' for value (though historically "v-"/"v." has meant "vendor-specific")?) for unnamed structured data microformats.
*** This more and more feels like a good idea, and I'm leaning toward "s-" for struct / structure / structured value. "s-" works just like "h-" except that it doesn't imply any properties at parse time. We can try it and see what happens. There's also no harm if publishers just use "h-" structures, they just (possibly) get a few extra properties if they happen to omit properties.
** Parallels the same JSON when a property has both a string value ''and'' is a structure itself.
*** Changed my mind on this. The parallel is not quite there. 'name'/'url'/'photo' are only implied if there are NO properties, where as the JSON string value + structure convention *always* provides a 'value'. [[User:Tantek|Tantek]] 22:39, 4 October 2011 (UTC)
** However, I'm still currently leaning towards the practical convenience of providing a 'name' for the vast majority of microformats uses, rather than diluting this feature for the sake of avoiding implying inapplicable semantics to the few plain structured data microformats. And I think I'd rather introduce a new root prefix for those than lose the simplicity and utility of implied 'name'. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

==Parsing properties from rel attributes==

--[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC):

* Currently, hAtom parses `bookmark` as a permalink
* Various microformats parse `rel=tag` as tags
* The current proposal for parsing does not allow parsing properties from rel attributes.

Microformats parsers could instead extract ''all'' link relationships from rel attributes within an microformat object, parsing them as if a u- prefixed property.
* Minor nit: Rather than same as a u- prefixed property, I think such "rel" properties should be parsed purely from the <code>href</code> attribute on <code><a></code> and <code><area></code> elements and nothing more. I would strongly disagree to extending rel to apply to other elements with URLs like img src, object data, or to apply to elements in general like div. That's the path that RDFa has taken and caused much confusion as a result. [[User:Tantek|Tantek]] 07:39, 5 October 2011 (UTC)
** Agree: That seems like a perfectly reasonable restriction. --[[User:BenWard|BenWard]] 08:29, 5 October 2011 (UTC)

This results in:

* Continuing use of the <code>rel</code> attribute in HTML, thereby building on HTML semantics rather than bypassing them or ignoring them in favour of something less meaningful.
* Parsing hAtom objects contain a property named <code>bookmark</code>, in place of <code>permalink</code>.
* All microformats that use <code>rel-tag</code> would contain a property named… <code>tag</code>. Perfect.

Since <code>rel</code> attributes are not overloaded for other functionality like class is, and other uses of <code>rel</code> within content are low (and non-semantic uses are nil, to the best of my knowledge) the risk of property pollution would be extremely low.

Note, with regard to this last point, that a generic microformats parser ''will'' parse false-positive properties, and ''will'' parse objects in combined chunks, rather than individually by format. Extracted objects will often not represent a vocabulary without further processing.

<div class="discussion">
* This sounds like it might be workable. Let's try it and see how well authors "get it". - [[User:Tantek|Tantek]]
* Possible issue: do we have any collisions between class property names and rel names? (I don't think so offhand, but useful to ask the question). - [[User:Tantek|Tantek]]
** None that I can think of in microformats. There is the case of Google's <code>rel=author</code> and <code>p-author</code> in hAtom. However, the next point, about mfo scoping, would cover it in most situations (rel-author on a hyperlink within an hcard wouldn't be applied to the hentry.) The one situation in a parse tree where it's ambiguous would be this: <code><a href="p-author h-card" rel="author" href="http://benward.me">Ben Ward</a></code>. I can think of two quite reasonable solutions: 1. Declare that class properties take precedence over rel properties of the same name, discarding rel values if a class is also found, or 2. Since all properties are now multi-value anyway, the hAtom object could be parsed as:
{
'type': ['h-entry'],
'properties': {
…
'author': [
{ 'type': ['h-card'], 'properties': { 'name': 'Ben Ward', 'url': 'http://benward.me' },
'http://benward.me'
],
…
}
}
** —[[User:BenWard|BenWard]] 08:29, 5 October 2011 (UTC)
* Presumably we'd apply all the same property scoping rules to rel scoping as well. E.g. a rel hyperlink inside a microformat won't be seen by any containing microformat. - [[User:Tantek|Tantek]]
** Correct, it should be parsed in the same scope as all other class properties in the object.
</div>

==Other Interpretation/Parsing Notes==

Collection of other unresolved parsing issues in a generic model:

This is good material for documenting as [[microformats-2-issues]], [[microformats-2-faq]], and perhaps some of the more technical details in [[microformats-2-parsing-faq]].

* The include pattern references other elements from elsewhere in a document. A generic parser needs to track IDs and fill them in after walking the DOM. (also, <code>itemref</code> if adopted.)
** The current thinking per [[microformats-2-brainstorming]] is to adopt <code>itemref</code> and drop the [[include-pattern]]. [[User:Tantek|Tantek]]
* Will <code>itemref</code> always map to an <code>item</code> property name?
** No, <code>itemref</code> maps to one or more elements by ids, and their children. Those referenced elements may have property class names themselves, or they may contain elements that do. [[User:Tantek|Tantek]]
* [[hAtom]] implies <code>author</code> from an hCard in a page that uses an <code>address</code> element. This requires format knowledge, but a generic parser does not currently track the element type of a property node. Should it?
** It should not. element-specific handling (e.g. using "alt" from img, and "title" from abbr) is completely done at parse time. The JSON data model does not reflect which element type or attribute the value came from. Additionally, [[hAtom]] is an example where we created far too many vocabulary-specific rules, in practice they're not necessary, and only complicate the microformat for both publisher understanding and parser implementation. [[User:Tantek|Tantek]]
* [[hAtom]] defines that the highest level heading within an entry implies <code>entry-title</code>. This particular optimisation might be better off dead.
** Agreed, this is gone in microformats 2. [[User:Tantek|Tantek]]
* [[hAtom]] defines that permalinks be parsed from <code>rel</code> attributes, not <code>class</code>
** In practice this has been one of the more problematic/error prone aspects of hAtom implementations, and it's also inconsistent with other microformats (although [[hReview]] tried to use both rel permalinks and "url"). The dependence upon [[rel-bookmark]] for permalinks is dropped in h-atom in preference to re-using "u-url" and "u-uid". [[User:Tantek|Tantek]]
* [[XFN]] is entirely built on <code>rel</code> (although, has various other differences from structural microformats, as do vote-links, so perhaps are excluded from this discussion and will always be handled by dedicated parsers/queries regardless?)
** The best (easiest and most reliable) use of 'rel' microformats in practice is when they are orthogonal to 'class' microformats. This is true both with [[XFN]] and some newer [[existing-rel-values|rel values]] like [[rel-author]]. In addition, it was very clear at the recent [[schema.org]] workshop's syntax session that RDFa's decision to apparently arbitrarily mix use of 'rel' and 'property' attributes for specifying different types of properties (it wasn't clear to people in the room when you use which for what) has caused a high degree of confusion among publishers and thus high error-rates. Thus if anything we should learn from both the mistakes of RDFa and our own experiences with even very deliberate/specific mixing of rel microformats in class microformats, and keep them defined as separate orthogonal building blocks that work together, but don't depend on each other. [[User:Tantek|Tantek]]
*** Relatedly to this: <code>rel-tag</code> in hAtom. --[[User:BenWard|BenWard]] 06:50, 5 October 2011 (UTC)
**** Yes, and two related things here. First, despite my (and others') objection and (past) interoperable post/entry-specific treatment by Technorati and Ice Rocket, Hixie has redefined rel-tag in [[HTML5]] to mean applying to the whole page, not a single post. Second, I've explicitly added 'p-category' to the draft 'h-atom' vocabulary in [[microformats-2]]. [[User:Tantek|Tantek]] 07:12, 5 October 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
* [[microformats-2-prefixes]]
* [[microformats-2-faq]]
* [[microformats-2-issues]]
* [[microformats-2-parsing-faq]]

microformats2-parsing-brainstorming

2011-10-05T07:24:09Z

BenWard: Alternative: Propose parsing all rel attributes for all microformats.

Author: [[User:BenWard|Ben Ward]]

[[microformats-2|Microformats 2]] proposes a new, all encompassing syntax modification of [[microformats-2-prefixes|prefixes]] that will allow microformats to be parsed from pages by processors without prior knowledge of a vocabulary. The core components of this model are quite simple, are quite simple to implement, but there are a number of conflicts that emerge with the functionality of existing microformats parsers that need to be handled. This page documents a proposed model to separate these concerns clearly in a way that can be applied to the documentation of generic microformats parsing rules, and the documentation of individual vocabularies.

==Parsing Microformats 2.0 Syntax: Extraction vs. Interpretation==

A microformats ‘1.0’ parser performs the following function:

* Given a piece of HTML content, discover a known microformat, extract it, apply various extraction patterns based upon the HTML mark-up used (e.g. include pattern, <code>abbr</code> patterns, date-time patterns, value-title pattern), apply various content optimisations where applicable, and return the result in an object native to the programming language.

This is performing two types of function: Extraction of data from an HTML document or fragment, ''and'' interpretation and optimisation of that content to match the rules set out by a vocabulary specification.

It is only possible to write a generic parser that covers the first half of this task: Extraction, and application of global rules based on HTML elements and patterns common to all formats.

The purpose of a generic parser (as supported by use cases such as search engines, and other crawlers) is:

To provide a way for tools to extract rich data from a page for native storage, such that the data may be interpreted later by applications. This allows microformats to be crawled, and indexed, and removes the need to include complex HTML parsing within every implementation of microformat data.

Microformats will continue to define various vocabulary-specific optimisations. as part of the design to be optimised for authors. For example: The <code>fn</code> pattern in [[hcard]], or the <code>lat;long</code> pattern in [[geo]], as well as default values for properties, such as the maximum rating in an [[hreview]].
* Actually, no, as it is defined currently, microformats 2 ''drops'' vocabulary-specific optimizations. Such optimizations have often been too inapplicable, error prone or i18n-unsafe (e.g. fn to given-name + family-name fails for both numerous cases where middlenames/initials are used, and in general in numerous Asian languages where given/family name order is the reverse of Western English conventions, or languages with multiple family-names, e.g. Spanish - see [[hcard-issues-resolved]] for more). This is a deliberate cutting of a "feature" from microformats 1, it is a deliberate model simplification design decision. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

Microformats 2.0 should refer only to ''extraction'' of microformats. Vocabularies should in turn document their appropriate optimisations, which will need to be applied by implementations, or a companion to an extractor, which I'll refer to here as an ‘interpreter’.
* Vocabularies will no longer have optimizations, this is again deliberately, as they've been shown to be more error prone than helpful. Thus there should be no need for any vocabulary-specific 'interpreters'. However, due to design quirks in various legacy/interchange formats, ''export conversions algorithms'' to those legacy/interchange formats will require some additional legacy-format-specific rules (e.g. odd "required" rules in [[Atom]] or [[vCard]] will require specific synthesis rules, limitations in said formats will require filtering of some values, e.g. [[vcard3]] BDAY disallows vague birthdays like year-month and --month-day - subsequently allowed in [[vcard4]]). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

A microformats 2.0 ‘extractor’, in combination with the functionality of a domain and format-aware ‘interpreter’ (either another shared component, or part of the implementation itself) would be equivalent to a microformats 1.0 ‘parser.’
* A microformats 2.0 parser is both generic (no knowledge of specific vocabularies), and lacks any/all such vocabulary-specific rules as compared to a microformats 1.0 [[hcard-parsing|parser]] with the exception of a 1) a limited list of well-established/interoperable backward compat root class names (of current [[microformats]] that are or can be soon shown to be specifications/standards per the [[process]]), 2) flat sets of backward compat property names (some with prefix/name specific conversion) for each of those backward compat root class names. This is a deliberate design decision that makes microformats 2 more "micro", and yes this means that even with such backward compat support, this simple form of backward compat may mean that some existing microformats 1 content breaks. We'll assess those and iterate on a documented case-by-case basis rather than attempt to maintain theoretical 100% backward compatibility (since many current microformats format-specific-features are either unused, or may have caused more problems than solutions). [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

N.B. I'll rewrite some of these as microformats-2-parsing-faq to help better clarify. The reasoning that led to most of these design decisions is documented in the [[microformats-2#About_This_Brainstorm|microformats 2: About This Brainstorm]] section and following sections. I'll recheck those sections to see if/where reasoning for some of the above noted design decisions may have been missed, and back-fill accordingly. This is necessary because [[microformats 2]] is a evolutionary result of simultaneously addressing both numerous generic [[issues]] as well as various common [[hcard-issues-resolved|format]]-[[hcalendar-issues-resolved|specific]] [[mfo|problems]] in microformats 1 syntax and vocabularies. The very number of changes may make it more challenging (from a microformats 1 perspective) to see why any particular design change has been made. [[User:Tantek|Tantek]] 12:43, 4 October 2011 (UTC)

==Parsing Literal Values==

It is proposed for microformats 2.0 that all microformats be parseable from just their root element, e.g. <code><p class="h-card">Ben Ward</p></code> would create an hCard with the following properties after parsing:

<source lang=javascript>
{
'type': ['h-card'],
'properties': {
'name': ['Ben Ward']
}
}
</source>

This is a four-fold change from the current [[hCard]]:
# type is generically identifiable as a microformat root, even in parsed form. The use of the 'h-' prefix persists into the type of the object. This is deliberately so, as a result of re-using the JSON data model of microdata which itself is re-using a common JSON convention, such that microformatted data is clearly distinguishable (as opposed to any other random schema that may be using a similar data model).
# root-class-only support. Per [[microformats-2-implied-properties]], the ''name'' property is implied by the entirety of the root class name element.
# 'name' instead of 'fn'. As also documented in [[microformats-2-implied-properties]], the continuous challenges/problems and need to repeatedly re-explain 'fn' over the years combined with the real-world market response of nearly every other party doing a person vocabulary renaming 'fn' to 'name', microformats 2 makes this change as well.
# There is no automatic parse-time inferring of <code>'given-name': ['Ben']</code> and <code>'family-name': ['Ward']</code>. Any such inferring *might* be made by a vCard converter, but is left up to that specific application (not all applications) built on that vocabulary, though even in that case it may not be necessary, as an empty "N:;;;" [[vCard]] property is sufficient to satisfy the N property requirement of [[vCard]], and also causes no problems when imported into various [[vcard-implementations]].

It is required of the extractor to understand that when a microformats object specifies no explicit child properties, that it must treat <code>h-card</code> as having a <code>p-name</code>. But, the parser is generic, so it also treats <code>h-review</code>, <code>h-entry</code>, <code>h-recipe</code>, <code>h-geo</code> as having a ‘<code>p-name</code>’.

As a result, specific vocabularies are evolved to drop their specific form of name (e.g. fn, summary, entry-title) and simplified to use a common 'name' property instead.

Note: while the overwhelming majority of real world publishing/consuming uses of microformats do so with proper nouns which have names (and thus this parser-level incorporation of an implied 'name'), there are some formats that do not have a 'name' semantic. For example, [[geo]], [[adr]], and possibly if/when developed, units of measure, length, cost. The current thinking is that the benefits to the far greater proper-noun use-case of microformats outweigh the technical inelegance of having an extra/ignored 'name' property on formats that lack such a semantic.

Some formats also may appear in theory to better imply some other property, e.g. a review might be thought to imply its ''content'', not its name, and an Atom entry its ''content'', not its title, but in practice (actual publishing patterns) this is not the case. Typically, brief unstructured reviews (or mentions thereof) provide a ''summary'' (often hyperlinked to an expanded structured form) of that review, not its content, and similarly, brief unstructured posts (e.g. RSS items) have historically most often been link blog items which include the title of an item and a link. Short status updates as well established by Twitter are newer and would seem to imply purely content with no title, at least semantically, however, even Twitter populates the RSS title and ATOM entry title of their feeds with the content. It's not clear what went into that decision, however, that's likely irrelevant, as the outcome turns out to be emergent consistency among publishing behaviors.

To avoid overloading or undermining the semantics of a vocabulary, I propose that we handle this at the extractor level in a simpler fashion: Define a new property for literal data, that an extractor will provide if no other information was available. All ''interpreters'' may then be instructed that in the event that an object has no properties, it can attempt to interpret the literal value from the page instead.
* This was one of the design iterations I went through which led me to the current implied 'name' design. Another iteration was the ability for a vocabulary to specific a single required property which was implied if there were no properties provided. However, the combination of the fact that in most cases such single required properties were quite name-like, and that a vocabulary-specific rule like that would then bind parsers to specific vocabularies (even so slightly) let me to collapse them into implying a 'name'. It's not perfect, but it's the best alternative so far that balances practical convenience of publishing/consuming, avoids vocabulary-specific knowledge in the parser, and technical elegance. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

In existing microformats, the closest existing example we have for this is the <code>label</code> property in hCard, which is used to represent the literal address label for a place. It is a corresponding piece of <code>fn</code>, <code>org</code> and <code>adr</code> in combination, but has no structure in and of itself. Possibly, every microformat could have a <code>label</code> form where structured data is unavailable.

However in practice, the hCard <code>label</code> property is both little understood and little used. It's not even clear that it ought to be kept for microformats 2 (no known consumers, very few (if any?) real-world non-test publishers). This disuse is likely a good indicator that we should avoid basing anything on its design.

Alternatively, <code>value</code> is used throughout microformats to target a generic value (e.g. in combination with <code>price</code> in hListing.) It has been proposed that when parsing properties that are also themselves microformats, we create native objects of the form:

{
'value': '1900 12th Street, San Francisco, CA 94'
, 'type': ['adr']
, 'properties': {
'street-address': '1900 12th Street'
, 'etc': 'etc'
}
}

We could apply this same pattern to the root level:

{
type: [hcard]
, properties: {}
, value: 'Ben Ward'
}

In this case, an interpreter or implementation is responsible for using <code>value</code> in place of <code>fn</code>, or restructuring the object. It would be the responsibility of each vocabulary to define its root property. The parsing layer of microformats 2.0 would not impose semantics or naming onto that.

For another example, geo would end up like this:

{
type: [geo]
, properties: {}
, value: '1.3232;-0.543'
}

* This is an alternative I've been considering as well: [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)
** 'value' is more generic than 'name' (applies to more vocabularies) with the trade-off that it naturally has less (weaker) semantics.
*** +1 I think that having naturally weaker semantics would be appropriate for this parsing functionality. —[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC)
** The interesting thing that this analysis has revealed is that there appear to be two distinct clusters of microformats, the much more commonly used/understood/useful proper-noun microformats which markup things with names (people, events, reviews, recipes), and the less used compound-data microformats which are often used ''inside'' other microformats and just have some sort of semi-structured value (adr, geo, measure, and perhaps even things like tel). Perhaps this is implying the possibility and some degree of utility for ''two'' microformats root class name prefixes, 'h-' for existing proper-noun microformats, and something else ('m-' for microformat/molecule?, 's-' for structured-value?, 'v-' for value (though historically "v-"/"v." has meant "vendor-specific")?) for unnamed structured data microformats.
*** This more and more feels like a good idea, and I'm leaning toward "s-" for struct / structure / structured value. "s-" works just like "h-" except that it doesn't imply any properties at parse time. We can try it and see what happens. There's also no harm if publishers just use "h-" structures, they just (possibly) get a few extra properties if they happen to omit properties.
** Parallels the same JSON when a property has both a string value ''and'' is a structure itself.
*** Changed my mind on this. The parallel is not quite there. 'name'/'url'/'photo' are only implied if there are NO properties, where as the JSON string value + structure convention *always* provides a 'value'. [[User:Tantek|Tantek]] 22:39, 4 October 2011 (UTC)
** However, I'm still currently leaning towards the practical convenience of providing a 'name' for the vast majority of microformats uses, rather than diluting this feature for the sake of avoiding implying inapplicable semantics to the few plain structured data microformats. And I think I'd rather introduce a new root prefix for those than lose the simplicity and utility of implied 'name'. [[User:Tantek|Tantek]] 13:48, 4 October 2011 (UTC)

==Parsing properties from rel attributes==

--[[User:BenWard|BenWard]] 07:24, 5 October 2011 (UTC):

* Currently, hAtom parses `bookmark` as a permalink
* Various microformats parse `rel=tag` as tags
* The current proposal for parsing does not allow parsing properties from rel attributes.

Microformats parsers could instead extract ''all'' link relationships from rel attributes within an microformat object, parsing them as if a u- prefixed property.

This results in:

* Continuing use of the <code>rel</code> attribute in HTML, thereby building on HTML semantics rather than bypassing them or ignoring them in favour of something less meaningful.
* Parsing hAtom objects contain a property named <code>bookmark</code>, in place of <code>permalink</code>.
* All microformats that use <code>rel-tag</code> would contain a property named… <code>tag</code>. Perfect.

Since <code>rel</code> attributes are not overloaded for other functionality like class is, and other uses of <code>rel</code> within content are low (and non-semantic uses are nil, to the best of my knowledge) the risk of property pollution would be extremely low.

Note, with regard to this last point, that a generic microformats parser ''will'' parse false-positive properties, and ''will'' parse objects in combined chunks, rather than individually by format. Extracted objects will often not represent a vocabulary without further processing.

==Other Interpretation/Parsing Notes==

Collection of other unresolved parsing issues in a generic model:

This is good material for documenting as [[microformats-2-issues]], [[microformats-2-faq]], and perhaps some of the more technical details in [[microformats-2-parsing-faq]].

* The include pattern references other elements from elsewhere in a document. A generic parser needs to track IDs and fill them in after walking the DOM. (also, <code>itemref</code> if adopted.)
** The current thinking per [[microformats-2-brainstorming]] is to adopt <code>itemref</code> and drop the [[include-pattern]]. [[User:Tantek|Tantek]]
* Will <code>itemref</code> always map to an <code>item</code> property name?
** No, <code>itemref</code> maps to one or more elements by ids, and their children. Those referenced elements may have property class names themselves, or they may contain elements that do. [[User:Tantek|Tantek]]
* [[hAtom]] implies <code>author</code> from an hCard in a page that uses an <code>address</code> element. This requires format knowledge, but a generic parser does not currently track the element type of a property node. Should it?
** It should not. element-specific handling (e.g. using "alt" from img, and "title" from abbr) is completely done at parse time. The JSON data model does not reflect which element type or attribute the value came from. Additionally, [[hAtom]] is an example where we created far too many vocabulary-specific rules, in practice they're not necessary, and only complicate the microformat for both publisher understanding and parser implementation. [[User:Tantek|Tantek]]
* [[hAtom]] defines that the highest level heading within an entry implies <code>entry-title</code>. This particular optimisation might be better off dead.
** Agreed, this is gone in microformats 2. [[User:Tantek|Tantek]]
* [[hAtom]] defines that permalinks be parsed from <code>rel</code> attributes, not <code>class</code>
** In practice this has been one of the more problematic/error prone aspects of hAtom implementations, and it's also inconsistent with other microformats (although [[hReview]] tried to use both rel permalinks and "url"). The dependence upon [[rel-bookmark]] for permalinks is dropped in h-atom in preference to re-using "u-url" and "u-uid". [[User:Tantek|Tantek]]
* [[XFN]] is entirely built on <code>rel</code> (although, has various other differences from structural microformats, as do vote-links, so perhaps are excluded from this discussion and will always be handled by dedicated parsers/queries regardless?)
** The best (easiest and most reliable) use of 'rel' microformats in practice is when they are orthogonal to 'class' microformats. This is true both with [[XFN]] and some newer [[existing-rel-values|rel values]] like [[rel-author]]. In addition, it was very clear at the recent [[schema.org]] workshop's syntax session that RDFa's decision to apparently arbitrarily mix use of 'rel' and 'property' attributes for specifying different types of properties (it wasn't clear to people in the room when you use which for what) has caused a high degree of confusion among publishers and thus high error-rates. Thus if anything we should learn from both the mistakes of RDFa and our own experiences with even very deliberate/specific mixing of rel microformats in class microformats, and keep them defined as separate orthogonal building blocks that work together, but don't depend on each other. [[User:Tantek|Tantek]]
*** Relatedly to this: <code>rel-tag</code> in hAtom. --[[User:BenWard|BenWard]] 06:50, 5 October 2011 (UTC)
**** Yes, and two related things here. First, despite my (and others') objection and (past) interoperable post/entry-specific treatment by Technorati and Ice Rocket, Hixie has redefined rel-tag in [[HTML5]] to mean applying to the whole page, not a single post. Second, I've explicitly added 'p-category' to the draft 'h-atom' vocabulary in [[microformats-2]]. [[User:Tantek|Tantek]] 07:12, 5 October 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
* [[microformats-2-prefixes]]
* [[microformats-2-faq]]
* [[microformats-2-issues]]
* [[microformats-2-parsing-faq]]

microformats2-parsing-brainstorming

2011-10-05T06:50:56Z

BenWard: /* Other Interpretation/Parsing Notes */ Aaaaand, rel-tag in hAtom would be unparsable, too.

microformats2-brainstorming

2011-10-05T06:46:41Z

BenWard: /* adopt itemref */ fix code typo

Brainstorming experimental / undeveloped / rejected ideas for [[microformats-2]].

== further simplifications ==

=== more on allow root class name only ===
This has been stable for a while, see:
* [[microformats-2-implied-properties]]

== adopt itemref ==

There many existing real-world use-cases where either:
* several microformats in a page want to share some common data without repeating it.
** e.g. a page about a product with multiple reviews of that product (very common, products sites, Amazon/CNET et al, review aggregators, Yelp et al)
** e.g. representing the author of multiple hAtom entries on a page. Currently this is possible with the <code><address class="hcard"></code> optimisation, which would be rendered obsolete by the proposed new generic parsing rules.
* a microformat in a page needs to incorporate information spread across different parts of a page, without assigning the entire page to that microformat

The [[include-pattern]] provides the necessary functionality for existing microformats (1.0).

For 2.0 it may be reasonable to simply re-use the nice <code>itemref</code> attribute from microdata, with identical/analogous functionality.

That is, when present on the root element of a microformat, the <code>itemref</code> attribute provides a space separated list of ids of elements in the document which are then incorporated as children of the microformat, before its actual children in the document. This is a simple coarse summary of course, and the actual itemref inclusion algorithm should be followed.

One might say that this raises the issue of requiring [[HTML5]] with the ability to accepted extended attributes like "itemref", but I think that might be ok for the set of use-cases that need "itemref". That is, they *are* a minority of actual use-cases, and thus making them use HTML5 is probably ok.

* More problematic is the fact that <code>itemref</code> is not part of the HTML5 specification, nor is it documented as a stable draft. In the past, we resisted cribbing attributes from RDFa, which was a ''stable'' augmentation of HTML, and creating an ugly empty-element hack rather than reusing <code>content</code>. We build atop HTML, and it would be dangerous to adopt features of separate technologies that are unstable, may change, or may disappear. --[[User:BenWard|BenWard]] 06:46, 5 October 2011 (UTC)

== rejected ideas ==

=== n prefix for multiple numbers ===
Idea:

* '''"n-*" for (one or more) numbers''', e.g. "n-rating", "n-geo", leaving the semantics of more than one number up to specific format. e.g. for an "n-rating" inside an "h-review", the first number would presumably be the rating value, when only two numbers the second would be the "best" value (e.g. rated <code><span class="n-rating">3 out of 4</span></code>), when three numbers the second would be the "worst" and the third would be the "best" (e.g. <code><span class="n-rating">7.5 out of 1 to 10</span></code>). similarly "n-geo" would specify the first number to be the latitude and the second to be the longitude.

Rejected because while this *might* work for some properties in *English* it will NOT localize/internationalize well (orders of numbers in phrases change in different languages), and it will also limit the human expressivity of the plain text. Thanks to Ben Ward for this feedback at the 2011-06-02 microformats dinner. [[User:Tantek|Tantek]] 14:25, 9 June 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-implied-properties]]
* [[microformats-2-faq]]

microformats2-brainstorming

2011-10-05T06:46:07Z

BenWard: /* adopt itemref */ Noting that lovely as itemref is, it's not HTML5, nor is it stable, and we've rejected useful invalid attributes in the past.

Brainstorming experimental / undeveloped / rejected ideas for [[microformats-2]].

== further simplifications ==

=== more on allow root class name only ===
This has been stable for a while, see:
* [[microformats-2-implied-properties]]

== adopt itemref ==

There many existing real-world use-cases where either:
* several microformats in a page want to share some common data without repeating it.
** e.g. a page about a product with multiple reviews of that product (very common, products sites, Amazon/CNET et al, review aggregators, Yelp et al)
** e.g. representing the author of multiple hAtom entries on a page. Currently this is possible with the <code><address class="hcard"></code> optimisation, which would be rendered obsolete by the proposed new generic parsing rules.
* a microformat in a page needs to incorporate information spread across different parts of a page, without assigning the entire page to that microformat

The [[include-pattern]] provides the necessary functionality for existing microformats (1.0).

For 2.0 it may be reasonable to simply re-use the nice <code>itemref</code> attribute from microdata, with identical/analogous functionality.

That is, when present on the root element of a microformat, the <code>itemref</code> attribute provides a space separated list of ids of elements in the document which are then incorporated as children of the microformat, before its actual children in the document. This is a simple coarse summary of course, and the actual itemref inclusion algorithm should be followed.

One might say that this raises the issue of requiring [[HTML5]] with the ability to accepted extended attributes like "itemref", but I think that might be ok for the set of use-cases that need "itemref". That is, they *are* a minority of actual use-cases, and thus making them use HTML5 is probably ok.

* More problematic is the fact that <code>itemref</code> is not part of the HTML5 specification, nor is it documented as a stable draft. In the past, we resisted cribbing attributes from RDFa, which was a ''stable'' augmentation of HTML, and creating an ugly empty-element hack rather than reusing <code>content</content>. We build atop HTML, and it would be dangerous to adopt features of separate technologies that are unstable, may change, or may disappear. --[[User:BenWard|BenWard]] 06:46, 5 October 2011 (UTC)

== rejected ideas ==

=== n prefix for multiple numbers ===
Idea:

* '''"n-*" for (one or more) numbers''', e.g. "n-rating", "n-geo", leaving the semantics of more than one number up to specific format. e.g. for an "n-rating" inside an "h-review", the first number would presumably be the rating value, when only two numbers the second would be the "best" value (e.g. rated <code><span class="n-rating">3 out of 4</span></code>), when three numbers the second would be the "worst" and the third would be the "best" (e.g. <code><span class="n-rating">7.5 out of 1 to 10</span></code>). similarly "n-geo" would specify the first number to be the latitude and the second to be the longitude.

Rejected because while this *might* work for some properties in *English* it will NOT localize/internationalize well (orders of numbers in phrases change in different languages), and it will also limit the human expressivity of the plain text. Thanks to Ben Ward for this feedback at the 2011-06-02 microformats dinner. [[User:Tantek|Tantek]] 14:25, 9 June 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-implied-properties]]
* [[microformats-2-faq]]

microformats2-brainstorming

2011-10-05T06:36:19Z

BenWard: /* adopt itemref */ Note hAtom shared author use case for itemref left open by loss of <address> optimisation.

Brainstorming experimental / undeveloped / rejected ideas for [[microformats-2]].

== further simplifications ==

=== more on allow root class name only ===
This has been stable for a while, see:
* [[microformats-2-implied-properties]]

== adopt itemref ==

There many existing real-world use-cases where either:
* several microformats in a page want to share some common data without repeating it.
** e.g. a page about a product with multiple reviews of that product (very common, products sites, Amazon/CNET et al, review aggregators, Yelp et al)
** e.g. representing the author of multiple hAtom entries on a page. Currently this is possible with the <code><address class="hcard"></code> optimisation, which would be rendered obsolete by the proposed new generic parsing rules.
* a microformat in a page needs to incorporate information spread across different parts of a page, without assigning the entire page to that microformat

The [[include-pattern]] provides the necessary functionality for existing microformats (1.0).

For 2.0 it may be reasonable to simply re-use the nice <code>itemref</code> attribute from microdata, with identical/analogous functionality.

That is, when present on the root element of a microformat, the <code>itemref</code> attribute provides a space separated list of ids of elements in the document which are then incorporated as children of the microformat, before its actual children in the document. This is a simple coarse summary of course, and the actual itemref inclusion algorithm should be followed.

One might say that this raises the issue of requiring [[HTML5]] with the ability to accepted extended attributes like "itemref", but I think that might be ok for the set of use-cases that need "itemref". That is, they *are* a minority of actual use-cases, and thus making them use HTML5 is probably ok.

== rejected ideas ==

=== n prefix for multiple numbers ===
Idea:

* '''"n-*" for (one or more) numbers''', e.g. "n-rating", "n-geo", leaving the semantics of more than one number up to specific format. e.g. for an "n-rating" inside an "h-review", the first number would presumably be the rating value, when only two numbers the second would be the "best" value (e.g. rated <code><span class="n-rating">3 out of 4</span></code>), when three numbers the second would be the "worst" and the third would be the "best" (e.g. <code><span class="n-rating">7.5 out of 1 to 10</span></code>). similarly "n-geo" would specify the first number to be the latitude and the second to be the longitude.

Rejected because while this *might* work for some properties in *English* it will NOT localize/internationalize well (orders of numbers in phrases change in different languages), and it will also limit the human expressivity of the plain text. Thanks to Ben Ward for this feedback at the 2011-06-02 microformats dinner. [[User:Tantek|Tantek]] 14:25, 9 June 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-implied-properties]]
* [[microformats-2-faq]]

microformats2-prefixes

2011-10-05T06:30:07Z

BenWard: /* prefixes for future consideration */ -1 on s-prefix.

<entry-title>microformats 2 prefix conventions</entry-title>

[[microformats 2]] uses a small number of prefixes to distinguish microformats 2 class names from other class names.

== motivating causes ==
As described on the [[microformats 2]] page.

=== distinguishing properties from other classes ===
Current microformats properties re-use generic terms like "summary", "photo", "updated" both for ease of use and understanding.

However, through longer term experience, we've seen sites that accidentally drop (or break) their microformats support (e.g. Upcoming.org, Facebook) because web authors sometimes rewrite all their class names, and either are unaware that microformats were in the page, or couldn't easily distinguish microformats property class names from other site-specific class names.

This issue has been reported by a number of web authors:
* [http://html5doctor.com/microformats/#comment-10241 Wim's comment on HTML5Doctor] "Authors use classes like 'url' or 'region' all the time ... All sorts of markup might look like a microformat."
* ...

There has also been an anecdotal report of a design firm who was not (yet) familiar with microformats seeing the "extra" classes that "that don't seem to be used" (without corresponding CSS rules) and asking if they "can remove them". By making microformats class names different from generic words, authors unfamiliar with microformats may at least notice such distinction and infer special functionality accordingly.

Thus microformats 2 uses ''prefixes'' for property class names, e.g.:
* '''p-summary''' instead of ''summary''
* '''u-photo''' instead of ''photo''
* '''dt-updated''' instead of ''updated''

Such prefixing of all microformats class names was first suggested by Scott Isaacs of Microsoft to Tantek on a visit to Microsoft sometime in 2006/2007, but specifically aimed at making microformats easier to parse. At the time the suggestion was rejected since microformats were focused on web authors rather than parsers.

However, since experience has shown that distinguishing property class names is an issue for '''both web authors and parser developers''', this is a key change that microformats 2 is adopting. See the next section for details.

=== existing microformats parsing requirements ===
A non-trivial number of parser and tools developers have been sufficiently frustrated with some general issues with microformats that they've done the significant extra work to support very different and less friendly alternatives (microdata, RDFa). Based on this real-world data (market behavior), it behooves us to address these general issues with microformats for this constituency.

COMMUNITY and TOOLS (that) USE MICROFORMATS
* parser / parsing
* structured
* getting the data out
* json - 1:1 mapping

[[parsing]] microformats currently requires
# a list of root class names of each microformat to be parsed
# a list of properties for each specific microformats, along with knowledge of the type of each property in order to parse their data from potentially different portions of the HTML markup
# some number of format-specific specific rules (markup/content optimizations)

This has meant that whenever a new microformat is drafted/specificied/adopted, parsers need to updated to handle it correctly, at a minimum to parse them when inside other microformats and avoid errantly implying properties from one to the other (containment, [[mfo]] problem).

== microformats 2 prefixes ==
=== naming conventions for generic parsing ===
There is a fairly simple solution to #1 and #2 from the above list, and we can make progress towards minimizing #3. In short:

'''Proposal: a set of naming conventions for microformat root class names and properties that make it obvious when:'''
* a class name represents a microformat root class name
* a class name represents a microformat property name
* a class name represents a microformat property that needs special parsing (specific type of property).

In particular - derived from the real world examples of existing proven microformats (rather than any abstraction of what a schema should have)
* '''"h-*" for root class names''', e.g. "h-card", "h-event", "h-entry"
** The 'h-' prefix is based on the existing microformats naming pattern of starting with 'h'.
* '''"p-*" for simple (text) properties''', e.g. "p-fn", "p-summary"
** vocabulary generic parsing, element text in general, treat certain HTML element/attribute combination as special and use those first, e.g. img/alt, abbr/title.
** The 'p-' prefix is based on the word "property" starting with 'p'.
* '''"u-*" for URL properties''', e.g. "u-url", "u-photo", "u-logo"
** special parsing required: prefer a/href, img/src, object/data etc. attributes to element contents.
** The 'u-' prefix is based on URL/URI starting with the letter 'u', which is the type of most of these related properties.
* '''"dt-*" for datetime properties''', e.g. "dt-start", "dt-end", "dt-bday"
** special parsing required: [[value-class-pattern]], in particular separate date time value parsing for better human readabillity / DRY balance.
** The 'dt-' prefix is based on "date time" having the initials "dt" and the preponderance of existing date time properties starting with "dt", e.g. dtstart, dtend, dtstamp, dtreviewed.
*** Initially I had proposed "dt-*" but Chris Messina suggested reducing it to "d-*" so that all prefixes were a single letter - made sense.
*** However, I've noticed that Google+ is using "d-*" class names on [https://plus.google.com/109182513536739786206 profile pages], thus we can't really use 'd-' as a microformats 2 property parsing prefix. [[User:Tantek|Tantek]] 03:00, 22 July 2011 (UTC)
* '''"e-*" for properties''' where the entire contained element hierarchy is the value, e.g. "e-content" (formerly "entry-content") for [[hAtom]]. The 'e-' prefix can also be mnemonically remembered as "element tree", "embedded markup", or "encapsulated markup".

This provides a simpler transition/education story for existing microformats authors/publishers:
* "h*" to "h-*", "dt*" to "dt-*", url-like properties to "u-*", entire embedded markup to "e-*", and "p-*" for all "plain text" properties.

==== prefixes for future consideration ====
possibly also:
<div class="discussion">
* '''"s-*" for structured properties''' basically s-* works just like h-* except that no properties (e.g. 'name','url','photo') are implied when there are no properties present. Example uses: s-geo and s-adr. This is being considered as a result of [[microformats-2-parsing#Parsing_Literal_Values|microformats 2 parsing discussions]]. We can try it and see what happens. There's also no harm if publishers just use "h-" structures, they just (possibly) get a few extra properties if they happen to omit properties.
** -1. Although I do think the implied-literal parsing behaviour carries some complications and parsed-cruft with more 'structural' formats, introducing a further generic prefix to differentiate one kind of format from another is oesoteric, won't be understood by authors (we're already considering a full reversal rename of 'fn' to 'name' in response to user comprehension), and we've seen historically that mixed prefixes (v and h) also cause muddle. --[[User:BenWard|BenWard]] 06:30, 5 October 2011 (UTC)
** Furthermore, both of the examples given here have in-the-wild use cases for literal parsing: Geo's existing documented optimisation of <code>1.233;0.453</code> is applied in two (one valid) manners with the <code>abbr</code> element (incorrectly as an expansion of a place name, and as an alternative to degree-format co-ordinates. Coordinates are also displayed in-place alongside map references, markers, and the like.) In the case of <code>adr</code>, there's an overlap with existing uses of the <code>label</code> label property, which is used in cases of unstructured addresses (common in most social network profile systems, also in vcalendar.) Based on previous discussion around unstructured addresses, Twitter uses <code><* class="adr"><* class="label"></code> on profiles ([https://twitter.com/intent/user?screen_name=benward&detailed Example].) Having literal parsing of <code>adr</code> would be neater though, if <code>label</code> were to be deprecated. --[[User:BenWard|BenWard]] 06:30, 5 October 2011 (UTC)
* '''"e-*" for properties''' where the entire contained element hierarchy is the value, e.g. "e-content" (formerly "entry-content") for [[hAtom]]. (2011-09-21 note: this has now been included in microformats 2, the below discussion is kept for posterity [[User:Tantek|Tantek]] 09:44, 21 September 2011 (UTC))
** unclear if this is necessary in general. and if so, if this is only for hAtom, that's insufficient to justify putting it in the generic syntax.
** Would be sufficient to have all <code>p-</code> properties parse the complete content, including any nested mark-up if present, and then implementations to sanitize/run a <code>strip_tags</code> style function (as per data input best practice) as appropriate. --[[User:BenWard|BenWard]] 22:05, 19 September 2011 (UTC)
** Ouch that sounds like passing on complexity downstream for all cases just to handle *one* known use-case so far. Since we'd typically do the opposite (simplify for the 99% case over the 1% case), passing on content including mark-up by default seems like a step backwards. Also, given how many vulnerabilities seem to deal with parsing/filtering, doing that *first* rather than burdening downstream implementations seems like the right choice. I'd rather wait til we get a concrete complaint from a microformats-2 hAtom consumer before worrying about this for hAtom 2.0. Or are there other current real world use cases besides Atom? [[User:Tantek|Tantek]] 22:22, 19 September 2011 (UTC)
*** In addition to <code>entry-content</code> in hAtom there's also <code>entry-summary</code>, plus any large region of text in other microformats, which at the very least can commonly contain additional hyperlinks, images, and phrasing mark-up: <code>description</code> in hCal, hReview, hProduct, hListing, <code>note</code> in hCard, <code>ingredient</code>, <code>instructions</code> in hRecipe may link to a store, or wikipedia entry for the ingredient, or include an image to illustrate a step of a recipe, as well as recipe instructions that are expressed as lists. If an author/publisher marks up a property in such a way that it contains further mark-up, that mark-up should be assumed to be part of the value. It's always going to be up to an implementation to decide whether it wishes to translate that HTML mark-up into some other format (e.g. Markdown-esque text annotation when converting to something like <code>vcard</code>, or some other kind of formatting language on non-HTML platforms, or stripping text altogether. —[[User:BenWard|BenWard]] 01:05, 20 September 2011 (UTC)
**** While hAtom's <code>entry-content</code> and possibly hCard's <code>note</code> may be the only existing practical use-cases (<code>entry-summary</code> and other "large region of text" are potential/prospective use cases), I'm now convinced the hAtom use-case alone is worthy of including the "e-" prefix because it enables a full fidelity replacement for typical Atom use cases. [[User:Tantek|Tantek]] 09:44, 21 September 2011 (UTC)
* '''"i-*" for ID properties''', e.g. "i-uid" (if this is the only one, then perhaps we just always re-use "uid" or collapse with "u-*" into "u-id".)
** parsing is no different than "u-*" parsing, thus no need to introduce for now.
* '''"n-*" for numbers''', e.g. "n-rating", "n-geo", where the numbers may have different human-readable-friendly and decimal/machine values (e.g. with geo lat/long degrees minutes seconds vs decimal).
** requires definition of how would different parsing work before worthy of consideration.
* '''"t-*" for time duration''', e.g. "t-duration" in [[hCalendar]], [[hAudio]], [[hRecipe]] (note also Google's hRecipe extensions "preptime", "cooktime", "totaltime")
** requires definition of how would different parsing work before worthy of consideration.
</div>

==== reserving other prefixes ====
We should '''reserve all other single-letter-dash prefixes for future use.'''

In practice we have seen little (if any) use of single-letter-dash prefixing of class names by web developers/designers, and thus in practice we think this will have little if any impact/collisions. Certainly far fewer than existing generic microformat property class names like "title", "note", "summary".

==== existing single letter class prefixes ====
We should document existing usage of single/double letter prefixed names:
* Google+ (e.g. [https://plus.google.com/109182513536739786206 profile page], others) uses:
** '''a-'''
** '''d-'''
** '''g-''', '''gb*'''
* Yahoo
** '''y-'''
* others? please add alphabetical by company/org name.

== microformats 2 example ==
Example: taking that simple heading hCard example forward:

<source lang=html4strict>
<h1 class="h-card">Chris Messina</h1>
</source>

As part of microformats 2.0 we would immediately define root class names and property names for all existing microformats and drafts consistent with this naming convention, and require support thereof from all new implementations, as well as strongly encouraging existing implementations to adopt the simplified microformats 2.0 syntax and mechanism. Question: which microformats deserve explicit backward compatibility?

As a community we would continue to use the microformats [[process]] both for researching and determining the need for new microformats, and for naming new microformat property names for maximum re-use and interoperability of a shared vocabulary.

If it turns out we need a new property type in the future, we can use one of the remaining single-letter-prefixes to add it to microformats 2.0. This would require updating of parsers of course, but in practice the number of different types of properties has grown very slowly, and we know from other schema/programming languages that there's always some small limited number of scalar/atomic property types that you need, and using those you can create compound types/objects that represent richer / more complicated types of data.

=== ADVANTAGES ===
This has numerous advantages:
* '''better maintainability''' - much more obvious to web authors/designers/publishers which class names are for/from microformats.
* '''no chance of collision''' - for all practical purposes with existing class names and thus avoiding any need to add more complex CSS style rules to prevent unintended styling effects.
* '''simpler parsing''' - parsers can now do a simple stream-parse (or in-order DOM tree walk) and parse out '''all''' microformat objects, properties, and values, without having to know anything about any specific microformats.
* '''separation of syntax and vocabulary''' - by abstracting microformats 2 syntax independent of any vocabulary, it allows and encourages development of shared vocabularies that can work in alternative syntaxes.

More examples: here is that same heading example with name components:

<source lang=html4strict>
<h1 class="h-card">
<span class="p-fn">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</span>
</h1>
</source>

with a hyperlink to Chris's URL:

<source lang=html4strict>
<h1 class="h-card">
<a class="p-fn u-url" href="http://factoryjoe.com/">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</a>
</h1>
</source>

=== COMPATIBILITY ===

microformats 2.0 is backwards compatible in that in permits content authors to markup with both old and new class names for compatibility with old tools.

Here is a simple example:

<source lang=html4strict>
<h1 class="h-card vcard">
<span class="fn">Chris Messina</span>
</h1>
</source>

a microformats 2.0 parser would see the class name "h-card" and imply the one required property from the contents, while a microformats 1.0 parser would find the class name "vcard" and then look for the class name "fn". no data duplication is required. this is a very important continuing application of the <abbr title="don't repeat yourself">DRY</abbr> [[principle]].

And the above hyperlinked example with both sets of class names:

<source lang=html4strict>
<h1 class="h-card vcard">
<a class="p-fn u-url n fn url" href="http://factoryjoe.com/">
<span class="p-given-name given-name">Chris</span>
<abbr class="p-additional-name additional-name">R.</abbr>
<span class="p-family-name family-name">Messina</span>
</a>
</h1>
</source>

== vendor extensions ==
(this section was only discussed verbally and not written up during discussions - capturing here as it is topical)

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties has in recent years allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

There have been times when specific sites have wanted to extend microformats beyond what the set of properties in the microformat, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

'''Proposal:'''
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension OR
** OR "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-)
** e.g.
** "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "onering" microformat root class name.
** "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)
** "p-x-prep-time" - a possible experimental property name to be added to hRecipe upon consideration/documentation of real-world usage/uptake.

Background - this proposal is a composition of the following (at least somewhat) successful vendor extension syntaxes
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

== issues ==
=== Hungarian prefixing issues ===
Raised by [[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)

Microformats 2.0 proposes using an explicit <code>[a-z]-</code> prefix on properties, to differentiate them from other uses of the class attribute, and identify them as microformat properties, such that they can be parsed generically.

* The differentiation use case is supported by anecdotal evidence of sites (such as Facebook, Twitter, Yahoo) removing microformats or breaking objects in page edits. The addition of a prefix assists self-documentation of code.
* The generic parsing use case is supported by Google Rich Snippets, Yahoo Search Monkey, and extensible plugins like Operator and the Firefox microformats parser. Although these extract microformats from the page, they are intermediate systems between the page content and the actual interpretation of the data. They need to parse all objects from a page, and then another developer or application will interpret some of them into something else.

(Note: the theoretical assertion "they need to parse all objects from a page" is not actually backed by *any* existing use of microformats/microdata/RDFa parsing - *none* of those parse "all objects from a page" if you consider every markup element an "object" - rather, one of the strength of microformats (mimicked by the others) is that the publisher is able to markup *just* the data to be extracted, rather than perhaps purely "presentational" content, ads, UI widgets etc. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )

The µf2 proposal goes further, though, into a small vocabulary of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian] prefixes of properties based on data type. This increases the level of understanding required to read microformats, and reduces the benefit of all microformat properties having a consistent identifying prefix.

(Debatable assertion:"increases the level of understanding required to read microformats" - how? In microformats 2.0, authors/developers know that any single-letter-and-hyphen prefixed class name is for microformats 2.0, in contrast to today - developers have consistently given feedback that's hard to tell which generic class names (other than h* names) are microformat related and which are not. As for specific prefixes, "h-*" is special and follows the pattern of existing microformats. p = generic (p)roperty, and the other prefixes have trivial mnemonics as well, d for (d)atetimes etc. (so far, hopefully we can keep that up). -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )

Hungarian notation itself is controversial amongst programmers.
Plenty find it uglifies their code, can be a cause of confusion (especially when very-short prefixes are used, or esoteric types, or where the declared set of types differs from the available types in other programming languages.) Others support its benefits to type identification.

(Programmers are not the priority here, rather, designers/authors/publishers are. We design microformats for them first as they're the common use case, and we should avoid making statements that seem to imply any priority for the aesthetic preferences of programmers. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC))

Critically, however, there is no clear indication that either of the above use cases requires types to be strongly identified.

<div class="discussion">
* For identifying µf in pages, a differentiator is required from regular classnames. There is no evidence of further requirement to differentiate between properties beyond their name (and existing criticisms of Hungarian notation suggest it can harm understandability.)
** There is such evidence, and perhaps thus this would be a good FAQ topic. The derivation is quite simple - it comes directly from minimally affecting existing markup, and maximally using existing semantic information. Example of special purpose parsing, URL-like properties use the value of the 'href' (or equivalent) attribute because that's where that data already is in pages. Similarly with dates and datetimes - special parsing rules for that data type have permitted us to design the [[value-class-pattern]] to take advantage of specially parsing date and time separation. By re-using data *where publishers already put it, including attributes vs inline* we minimize the risk of data drift. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
** Additionally, this special type-specific parsing of microformats properties conveys microformats advantages of markup brevity that other syntaxes lack. E.g. you can convey *multiple* properties and values from a single existing element, e.g. the *very* common real-world pattern <code><br/><nowiki><a href="http://example.com/user">User Name</a></nowiki><br/></code> is minimally marked up as <code><br/><nowiki><span class="h-card"><a class="p-name u-url" href="http://example.com/user">User Name</a></span></nowiki><br/></code>
* For generic parsing, there is no requirement that datatypes be established at extraction time. Data types will instead be applied by the developers of apps and widgets that build on the generic parsers.
** There are requirements based on experience with actual markup. In order to support the patterns of where content publishers put the data we want to extract, we have determined (based on those publishing patterns) a few different ways (types) of parsing this data. This is all captured in the [[hcard-parsing]] property-specific parsing rules each of which were added one at a time as Brian Suda and myself encountered real world sites wanting to use [[hCard]] but not wanting to have to rewrite their markup (adding one span and some class names was about the limit, moving tags/attributes around was a showstopper in many/most cases), and each of the microformats 2.0 "types" are directly derived from such special purpose data/type parsing across *multiple* microformats. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
* A counter argument may be that special properties in microformats—such as URLs, or images—need to be identified because in microformats it is common to parse an attribute (href, or src) rather than inner text of an element for these properties. However, in the context of extracting and then interpreting HTML in other contexts this is insufficient: For example, though an image only exists as a single property in vcard, in HTML it is both a URL to a resource ''and'' and text string (alt) representing an accessible fallback. A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context. Likewise, an application interpreting a URL may also consider using the original inner text as an inferred label. Both pieces of data are useful, and a generic parser should not discard elemental semantics at the extraction level.
** It's not just "*common* to parse an attribute rather than inner text of an element for these properties" - it is the vast overwhelming majority - if not all - such cases!
** One misconception: "image only exists as a single property". No, there is both 'photo' and 'logo'. The 'url' and 'sound' properties are also of type 'url'. For all of these, when parsing an "object" element, you must use the 'data' attribute first for example. hCalendar has "attachment" as well. Etc.
** Theoretical assertion: "A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context." Why? There is no existing nor demonstrated use case for this requirement, even across other formats. While I agree it "might be nice" to develop a new "structured image" type - that's brand new work (deserving of research per the [[process]] etc.), and not a good source of reasoning to reject existing working patterns. I reject blocking microformats 2.0 on an as-yet-to-be-researched-enhancement. This is certainly a case where "better" is an enemy of the good.
** Theoretical assertion: "a generic parser should not discard elemental semantics at the extraction level" - already does for other syntaxes like both microdata and RDFa - so clearly this is not a reasonable "should not" assertion (and thus unnecessary) for development of a minimally competitive syntax. RDFa kind of cheats by overloading the 'rel' attribute in attempt to solve the name+url case as mentioned above, but that's only two types - and existing real world use of microformats has demonstrated utility of a few more. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
</div>

Given this, hungarian prefixes are of no benefit to parsers (and may in fact harm applications down the chain if parsing is prematurely strict.) It would be sufficient then not to concern embedding data types in property names, and instead settle on one single property prefix to differentiate all properties consistently. This would reduce the prefixes to just 3:

* <code>h</code> would indicates a root class name. An ‘object in HTML’.
* <code>p</code> would indicates a property within an object.
* <code>x</code> would indicates an experimental extension to an object.

--[[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)

The primary benefit of type-specific parsing is *not* for parsers, but rather, publishers (who we still hold in higher priority than parsers).

I will also note that *each* of the type-specific parsing methods in [[hcard-parsing]] was added both conservatively, reluctantly, and only when it became clear that such type-specific publishing patterns existing across *multiple* sites that would otherwise be unable to change their markup to work with microformats (Yes, I'm wishing now that I better documented exactly *which* sites, precisely *when*, but like many startups, early on we didn't exactly know how much to document vs get things done - frankly I think we documented far more than any other comparable such efforts, e.g. we managed to at least capture/grow both an explicit [[process]] and [[principles]] in *far* greater detail than anything remotely comparable either before microformats or since!). The type-specific parsing features are certainly not overdesigned, on the contrary they've *slowly* evolved, adapting to real world data on the web.

While per the [[simplicity]] principle, I would actually *strongly* prefer to only have the three prefixes given above, or actually just *two* (I started with just two for the design of microformats 2.0 actually, just "h-*" and "p-*"), doing so would be a step *backwards* in terms of the adaptability of microformats to existing markup, and that's IMHO an unacceptable barrier, and a sufficiently high barrier to hurt the adoption/applicability of microformats 2.0.

(Aside: In addition, note that you still need h-x-* for experimental objects, and thus it's *simpler* to simply have *both* h-x-* and p-x-* rather than add x-*. Alternatively x-h-* and x-p-* is no better, in some ways worse, in that object vs. property is a more important distinction for parsers than established vs experimental, especially if/when an experimental property (or object) may be adopted. Also, mild precdent: PNG started with image/x-png, not x-image/png.).

To put it in a positive way, type-specific parsing conveys microformats a publisher-markup-density (and re-use) advantage which neither microdata nor RDFa have, and it would behoove us to *keep* this significant real-world advantage as we evolve microformats.

-- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-faq]]

microformats2-parsing-brainstorming

2011-10-04T09:02:15Z

BenWard: /* Parsing Literal Values */ Fix inline HTML code sample.

microformats2-parsing-brainstorming

2011-10-04T08:56:51Z

BenWard: Fix code intendation, noted various other parsing issues that have come to mind during implementation of hparse.js

microformats2-parsing-brainstorming

2011-10-04T08:45:44Z

BenWard: Fixed some links.

microformats2-parsing-brainstorming

2011-10-04T08:45:11Z

BenWard: Initial brian dump on parsing root elements, not forcing semantics or naming onto vocabularies, handling string literals, and defining a distinction between extraction and interpretation parsing.

Author: [[User:BenWard|Ben Ward]]

[microformats-2|Microformats 2] proposes a new, all encompassing syntax modification of [microformats-2-prefixes|prefixes] that will allow microformats to be parsed from pages by processors without prior knowledge of a vocabulary. The core components of this model are quite simple, are quite simple to implement, but there are a number of conflicts that emerge with the functionality of existing microformats parsers that need to be handled. This page documents a proposed model to separate these concerns clearly in a way that can be applied to the documentation of generic microformats parsing rules, and the documentation of individual vocabularies.

==Parsing Microformats 2.0 Syntax: Extraction vs. Interpretation==

A microformats ‘1.0’ parser performs the following function:

* Given a piece of HTML content, discover a known microformat, extract it, apply various extraction patterns based upon the HTML mark-up used (e.g. include pattern, <code>abbr</code> patterns, date-time patterns, value-title pattern), apply various content optimisations where applicable, and return the result in an object native to the programming language.

This is performing two types of function: Extraction of data from an HTML document or fragment, ''and'' interpretation and optimisation of that content to match the rules set out by a vocabulary specification.

It is only possible to write a generic parser that covers the first half of this task: Extraction, and application of global rules based on HTML elements and patterns common to all formats.

The purpose of a generic parser (as supported by use cases such as search engines, and other crawlers) is:

To provide a way for tools to extract rich data from a page for native storage, such that the data may be interpreted later by applications. This allows microformats to be crawled, and indexed, and removes the need to include complex HTML parsing within every implementation of microformat data.

Microformats will continue to define various vocabulary-specific optimisations. as part of the design to be optimised for authors. For example: The <code>fn</code> pattern in [[hcard]], or the <code>lat;long</code> pattern in [[geo]], as well as default values for properties, such as the maximum rating in an [[hreview]].

Microformats 2.0 should refer only to ''extraction'' of microformats. Vocabularies should in turn document their appropriate optimisations, which will need to be applied by implementations, or a companion to an extractor, which I'll refer to here as an ‘interpreter’.

A microformats 2.0 ‘extractor’, in combination with the functionality of a domain and format-aware ‘interpreter’ (either another shared component, or part of the implementation itself) would be equivalent to a microformats 1.0 ‘parser.’

==Parsing Literal Values==

It is proposed for microformats 2.0 that all microformats be parseable from just their root element, e.g. <code><p class="h-card">Ben Ward</p></code> would create an hCard with the following properties after extraction and interpretation:

<code>{
type: [hcard]
, properties: {
'fn': ['Ben Ward']
, 'given-name': ['Ben']
, 'family-name': ['Ward']
}
}</code>

It is required of the extractor to understand that when a microformats object specifies no explicit child properties, that it must treat <code>h-card</code> as <code>p-fn</code>. But, the parser is generic, so it would also treat <code>h-review</code>, <code>h-entry</code>, <code>h-recipe</code>, <code>h-geo</code> as ‘<code>p-fn</code>’. As a parser, this is somewhat acceptable, but is unacceptable to the vocabularies, many of which do not define <code>fn</code> and that even if all various of <code>fn</code>, <code>summary</code> and <code>entry-title</code> be consolidated to <code>fn</code> (which it is also proposed be renamed to <code>name</code), it cannot with certainly be claimed that every one of these formats provide anything semantically valid in that case. What, for example, is the ‘name’ of a geo? It has none. Likewise, a review described with just a single field would more likely map to the review's ''content'', not its name, and an Atom entry its ''content'', not its title.

To avoid overloading or undermining the semantics of a vocabulary, I propose that we handle this at the extractor level in a simpler fashion: Define a new property for literal data, that an extractor will provide if no other information was available. All ''interpreters'' may then be instructed that in the event that an object has no properties, it can attempt to interpret the literal value from the page instead.

This enables a parser to operate generically without incorrectly applying semantics, and allows applications an interpreters to work with parsed data is a simple and defined way.

In existing microformats, the closest existing example we have for this is the <code>label<code> property in hCard, which is used to represent the literal address label for a place. It is a corresponding piece of <code>fn</code>, <code>org</code> and <code>adr</code> in combination, but has no structure in and of itself.

Possibly, every microformat could have a <code>label<code> form where structured data is unavailable.

Alternatively, <code>value</code> is used throughout microformats to target a generic value (e.g. in combination with <code>price</code> in hListing.) It has been proposed that when parsing properties that are also themselves microformats, we create native objects of the form:

<code>{
'value': '1900 12th Street, San Francisco, CA 94'
, 'type': ['adr']
, 'properties': {
'street-address': '1900 12th Street'
, 'etc': 'etc'
}
}</code>

We could apply this same pattern to the root level:

<code>{
type: [hcard]
, properties: {}
, value: 'Ben Ward'
}</code>

In this case, an interpreter or implementation is responsible for using <code>value</code> in place of <code>fn</code>, or restructuring the object. It would be the responsibility of each vocabulary to define its root property. The parsing layer of microformats 2.0 would not impose semantics or naming onto that.

microformats2-prefixes

2011-09-20T01:07:00Z

BenWard: /* prefixes for future consideration */ typo.

<entry-title>microformats 2 prefix conventions</entry-title>

[[microformats 2]] uses a small number of prefixes to distinguish microformats 2 class names from other class names.

== motivating causes ==
As described on the [[microformats 2]] page.

=== distinguishing properties from other classes ===
Current microformats properties re-use generic terms like "summary", "photo", "updated" both for ease of use and understanding.

However, through longer term experience, we've seen sites that accidentally drop (or break) their microformats support (e.g. Upcoming.org, Facebook) because web authors sometimes rewrite all their class names, and either are unaware that microformats were in the page, or couldn't easily distinguish microformats property class names from other site-specific class names.

This issue has been reported by a number of web authors:
* [http://html5doctor.com/microformats/#comment-10241 Wim's comment on HTML5Doctor] "Authors use classes like 'url' or 'region' all the time ... All sorts of markup might look like a microformat."
* ...

There has also been an anecdotal report of a design firm who was not (yet) familiar with microformats seeing the "extra" classes that "that don't seem to be used" (without corresponding CSS rules) and asking if they "can remove them". By making microformats class names different from generic words, authors unfamiliar with microformats may at least notice such distinction and infer special functionality accordingly.

Thus microformats 2 uses ''prefixes'' for property class names, e.g.:
* '''p-summary''' instead of ''summary''
* '''u-photo''' instead of ''photo''
* '''dt-updated''' instead of ''updated''

Such prefixing of all microformats class names was first suggested by Scott Isaacs of Microsoft to Tantek on a visit to Microsoft sometime in 2006/2007, but specifically aimed at making microformats easier to parse. At the time the suggestion was rejected since microformats were focused on web authors rather than parsers.

However, since experience has shown that distinguishing property class names is an issue for '''both web authors and parser developers''', this is a key change that microformats 2 is adopting. See the next section for details.

=== existing microformats parsing requirements ===
A non-trivial number of parser and tools developers have been sufficiently frustrated with some general issues with microformats that they've done the significant extra work to support very different and less friendly alternatives (microdata, RDFa). Based on this real-world data (market behavior), it behooves us to address these general issues with microformats for this constituency.

COMMUNITY and TOOLS (that) USE MICROFORMATS
* parser / parsing
* structured
* getting the data out
* json - 1:1 mapping

[[parsing]] microformats currently requires
# a list of root class names of each microformat to be parsed
# a list of properties for each specific microformats, along with knowledge of the type of each property in order to parse their data from potentially different portions of the HTML markup
# some number of format-specific specific rules (markup/content optimizations)

This has meant that whenever a new microformat is drafted/specificied/adopted, parsers need to updated to handle it correctly, at a minimum to parse them when inside other microformats and avoid errantly implying properties from one to the other (containment, [[mfo]] problem).

== microformats 2 prefixes ==
=== naming conventions for generic parsing ===
There is a fairly simple solution to #1 and #2 from the above list, and we can make progress towards minimizing #3. In short:

'''Proposal: a set of naming conventions for microformat root class names and properties that make it obvious when:'''
* a class name represents a microformat root class name
* a class name represents a microformat property name
* a class name represents a microformat property that needs special parsing (specific type of property).

In particular - derived from the real world examples of existing proven microformats (rather than any abstraction of what a schema should have)
* '''"h-*" for root class names''', e.g. "h-card", "h-event", "h-entry"
** The 'h-' prefix is based on the existing microformats naming pattern of starting with 'h'.
* '''"p-*" for simple (text) properties''', e.g. "p-fn", "p-summary"
** vocabulary generic parsing, element text in general, treat certain HTML element/attribute combination as special and use those first, e.g. img/alt, abbr/title.
** The 'p-' prefix is based on the word "property" starting with 'p'.
* '''"u-*" for URL properties''', e.g. "u-url", "u-photo", "u-logo"
** special parsing required: prefer a/href, img/src, object/data etc. attributes to element contents.
** The 'u-' prefix is based on URL/URI starting with the letter 'u', which is the type of most of these related properties.
* '''"dt-*" for datetime properties''', e.g. "dt-start", "dt-end", "dt-bday"
** special parsing required: [[value-class-pattern]], in particular separate date time value parsing for better human readabillity / DRY balance.
** The 'dt-' prefix is based on "date time" having the initials "dt" and the preponderance of existing date time properties starting with "dt", e.g. dtstart, dtend, dtstamp, dtreviewed.
*** Initially I had proposed "dt-*" but Chris Messina suggested reducing it to "d-*" so that all prefixes were a single letter - made sense.
*** However, I've noticed that Google+ is using "d-*" class names on [https://plus.google.com/109182513536739786206 profile pages], thus we can't really use 'd-' as a microformats 2 property parsing prefix. [[User:Tantek|Tantek]] 03:00, 22 July 2011 (UTC)
*** Frankly I also think this provides a simpler transition/education story for existing microformats authors/publishers: "h*" to "h-*", "dt*" to "dt-*", url type properties to "u-*", and "p-*" for all others.

See [[microformats-2-prefixes]] for further thoughts and discussions on these and other class prefixes.

==== prefixes for future consideration ====
possibly also:
<div class="discussion">
* '''"e-*" for properties''' where the entire contained element hierarchy is the value, e.g. "e-content" (formerly "entry-content") for [[hAtom]].
** unclear if this is necessary in general. and if so, if this is only for hAtom, that's insufficient to justify putting it in the generic syntax.
** Would be sufficient to have all <code>p-</code> properties parse the complete content, including any nested mark-up if present, and then implementations to sanitize/run a <code>strip_tags</code> style function (as per data input best practice) as appropriate. --[[User:BenWard|BenWard]] 22:05, 19 September 2011 (UTC)
** Ouch that sounds like passing on complexity downstream for all cases just to handle *one* known use-case so far. Since we'd typically do the opposite (simplify for the 99% case over the 1% case), passing on content including mark-up by default seems like a step backwards. Also, given how many vulnerabilities seem to deal with parsing/filtering, doing that *first* rather than burdening downstream implementations seems like the right choice. I'd rather wait til we get a concrete complaint from a microformats-2 hAtom consumer before worrying about this for hAtom 2.0. Or are there other current real world use cases besides Atom? [[User:Tantek|Tantek]] 22:22, 19 September 2011 (UTC)
*** In addition to <code>entry-content</code> in hAtom there's also <code>entry-summary</code>, plus any large region of text in other microformats, which at the very least can commonly contain additional hyperlinks, images, and phrasing mark-up: <code>description</code> in hCal, hReview, hProduct, hListing, <code>note</code> in hCard, <code>ingredient</code>, <code>instructions</code> in hRecipe may link to a store, or wikipedia entry for the ingredient, or include an image to illustrate a step of a recipe, as well as recipe instructions that are expressed as lists. If an author/publisher marks up a property in such a way that it contains further mark-up, that mark-up should be assumed to be part of the value. It's always going to be up to an implementation to decide whether it wishes to translate that HTML mark-up into some other format (e.g. Markdown-esque text annotation when converting to something like <code>vcard</code>, or some other kind of formatting language on non-HTML platforms, or stripping text altogether. —[[User:BenWard|BenWard]] 01:05, 20 September 2011 (UTC)
* '''"i-*" for ID properties''', e.g. "i-uid" (if this is the only one, then perhaps we just always re-use "uid" or collapse with "u-*" into "u-id".)
** parsing is no different than "u-*" parsing, thus no need to introduce for now.
* '''"n-*" for numbers''', e.g. "n-rating", "n-geo", where the numbers may have different human-readable-friendly and decimal/machine values (e.g. with geo lat/long degrees minutes seconds vs decimal).
** requires definition of how would different parsing work before worthy of consideration.
* '''"t-*" for time duration''', e.g. "t-duration" in [[hCalendar]], [[hAudio]], [[hRecipe]] (note also Google's hRecipe extensions "preptime", "cooktime", "totaltime")
** requires definition of how would different parsing work before worthy of consideration.
</div>

==== reserving other prefixes ====
We should '''reserve all other single-letter-dash prefixes for future use.'''

In practice we have seen little (if any) use of single-letter-dash prefixing of class names by web developers/designers, and thus in practice we think this will have little if any impact/collisions. Certainly far fewer than existing generic microformat property class names like "title", "note", "summary".

==== existing single letter class prefixes ====
We should document existing usage of single/double letter prefixed names:
* Google+ (e.g. [https://plus.google.com/109182513536739786206 profile page], others) uses:
** '''a-'''
** '''d-'''
** '''g-''', '''gb*'''
* Yahoo
** '''y-'''
* others? please add alphabetical by company/org name.

== microformats 2 example ==
Example: taking that simple heading hCard example forward:

<source lang=html4strict>
<h1 class="h-card">Chris Messina</h1>
</source>

As part of microformats 2.0 we would immediately define root class names and property names for all existing microformats and drafts consistent with this naming convention, and require support thereof from all new implementations, as well as strongly encouraging existing implementations to adopt the simplified microformats 2.0 syntax and mechanism. Question: which microformats deserve explicit backward compatibility?

As a community we would continue to use the microformats [[process]] both for researching and determining the need for new microformats, and for naming new microformat property names for maximum re-use and interoperability of a shared vocabulary.

If it turns out we need a new property type in the future, we can use one of the remaining single-letter-prefixes to add it to microformats 2.0. This would require updating of parsers of course, but in practice the number of different types of properties has grown very slowly, and we know from other schema/programming languages that there's always some small limited number of scalar/atomic property types that you need, and using those you can create compound types/objects that represent richer / more complicated types of data.

=== ADVANTAGES ===
This has numerous advantages:
* '''better maintainability''' - much more obvious to web authors/designers/publishers which class names are for/from microformats.
* '''no chance of collision''' - for all practical purposes with existing class names and thus avoiding any need to add more complex CSS style rules to prevent unintended styling effects.
* '''simpler parsing''' - parsers can now do a simple stream-parse (or in-order DOM tree walk) and parse out '''all''' microformat objects, properties, and values, without having to know anything about any specific microformats.
* '''separation of syntax and vocabulary''' - by abstracting microformats 2 syntax independent of any vocabulary, it allows and encourages development of shared vocabularies that can work in alternative syntaxes.

More examples: here is that same heading example with name components:

<source lang=html4strict>
<h1 class="h-card">
<span class="p-fn">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</span>
</h1>
</source>

with a hyperlink to Chris's URL:

<source lang=html4strict>
<h1 class="h-card">
<a class="p-fn u-url" href="http://factoryjoe.com/">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</a>
</h1>
</source>

=== COMPATIBILITY ===

microformats 2.0 is backwards compatible in that in permits content authors to markup with both old and new class names for compatibility with old tools.

Here is a simple example:

<source lang=html4strict>
<h1 class="h-card vcard">
<span class="fn">Chris Messina</span>
</h1>
</source>

a microformats 2.0 parser would see the class name "h-card" and imply the one required property from the contents, while a microformats 1.0 parser would find the class name "vcard" and then look for the class name "fn". no data duplication is required. this is a very important continuing application of the <abbr title="don't repeat yourself">DRY</abbr> [[principle]].

And the above hyperlinked example with both sets of class names:

<source lang=html4strict>
<h1 class="h-card vcard">
<a class="p-fn u-url n fn url" href="http://factoryjoe.com/">
<span class="p-given-name given-name">Chris</span>
<abbr class="p-additional-name additional-name">R.</abbr>
<span class="p-family-name family-name">Messina</span>
</a>
</h1>
</source>

== vendor extensions ==
(this section was only discussed verbally and not written up during discussions - capturing here as it is topical)

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties has in recent years allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

There have been times when specific sites have wanted to extend microformats beyond what the set of properties in the microformat, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

'''Proposal:'''
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension OR
** OR "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-)
** e.g.
** "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "onering" microformat root class name.
** "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)
** "p-x-prep-time" - a possible experimental property name to be added to hRecipe upon consideration/documentation of real-world usage/uptake.

Background - this proposal is a composition of the following (at least somewhat) successful vendor extension syntaxes
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

== issues ==
=== Hungarian prefixing issues ===
Raised by [[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)

Microformats 2.0 proposes using an explicit <code>[a-z]-</code> prefix on properties, to differentiate them from other uses of the class attribute, and identify them as microformat properties, such that they can be parsed generically.

* The differentiation use case is supported by anecdotal evidence of sites (such as Facebook, Twitter, Yahoo) removing microformats or breaking objects in page edits. The addition of a prefix assists self-documentation of code.
* The generic parsing use case is supported by Google Rich Snippets, Yahoo Search Monkey, and extensible plugins like Operator and the Firefox microformats parser. Although these extract microformats from the page, they are intermediate systems between the page content and the actual interpretation of the data. They need to parse all objects from a page, and then another developer or application will interpret some of them into something else.

(Note: the theoretical assertion "they need to parse all objects from a page" is not actually backed by *any* existing use of microformats/microdata/RDFa parsing - *none* of those parse "all objects from a page" if you consider every markup element an "object" - rather, one of the strength of microformats (mimicked by the others) is that the publisher is able to markup *just* the data to be extracted, rather than perhaps purely "presentational" content, ads, UI widgets etc. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )

The µf2 proposal goes further, though, into a small vocabulary of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian] prefixes of properties based on data type. This increases the level of understanding required to read microformats, and reduces the benefit of all microformat properties having a consistent identifying prefix.

(Debatable assertion:"increases the level of understanding required to read microformats" - how? In microformats 2.0, authors/developers know that any single-letter-and-hyphen prefixed class name is for microformats 2.0, in contrast to today - developers have consistently given feedback that's hard to tell which generic class names (other than h* names) are microformat related and which are not. As for specific prefixes, "h-*" is special and follows the pattern of existing microformats. p = generic (p)roperty, and the other prefixes have trivial mnemonics as well, d for (d)atetimes etc. (so far, hopefully we can keep that up). -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )

Hungarian notation itself is controversial amongst programmers.
Plenty find it uglifies their code, can be a cause of confusion (especially when very-short prefixes are used, or esoteric types, or where the declared set of types differs from the available types in other programming languages.) Others support its benefits to type identification.

(Programmers are not the priority here, rather, designers/authors/publishers are. We design microformats for them first as they're the common use case, and we should avoid making statements that seem to imply any priority for the aesthetic preferences of programmers. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC))

Critically, however, there is no clear indication that either of the above use cases requires types to be strongly identified.

<div class="discussion">
* For identifying µf in pages, a differentiator is required from regular classnames. There is no evidence of further requirement to differentiate between properties beyond their name (and existing criticisms of Hungarian notation suggest it can harm understandability.)
** There is such evidence, and perhaps thus this would be a good FAQ topic. The derivation is quite simple - it comes directly from minimally affecting existing markup, and maximally using existing semantic information. Example of special purpose parsing, URL-like properties use the value of the 'href' (or equivalent) attribute because that's where that data already is in pages. Similarly with dates and datetimes - special parsing rules for that data type have permitted us to design the [[value-class-pattern]] to take advantage of specially parsing date and time separation. By re-using data *where publishers already put it, including attributes vs inline* we minimize the risk of data drift. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
** Additionally, this special type-specific parsing of microformats properties conveys microformats advantages of markup brevity that other syntaxes lack. E.g. you can convey *multiple* properties and values from a single existing element, e.g. the *very* common real-world pattern <code><br/><nowiki><a href="http://example.com/user">User Name</a></nowiki><br/></code> is minimally marked up as <code><br/><nowiki><span class="h-card"><a class="p-name u-url" href="http://example.com/user">User Name</a></span></nowiki><br/></code>
* For generic parsing, there is no requirement that datatypes be established at extraction time. Data types will instead be applied by the developers of apps and widgets that build on the generic parsers.
** There are requirements based on experience with actual markup. In order to support the patterns of where content publishers put the data we want to extract, we have determined (based on those publishing patterns) a few different ways (types) of parsing this data. This is all captured in the [[hcard-parsing]] property-specific parsing rules each of which were added one at a time as Brian Suda and myself encountered real world sites wanting to use [[hCard]] but not wanting to have to rewrite their markup (adding one span and some class names was about the limit, moving tags/attributes around was a showstopper in many/most cases), and each of the microformats 2.0 "types" are directly derived from such special purpose data/type parsing across *multiple* microformats. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
* A counter argument may be that special properties in microformats—such as URLs, or images—need to be identified because in microformats it is common to parse an attribute (href, or src) rather than inner text of an element for these properties. However, in the context of extracting and then interpreting HTML in other contexts this is insufficient: For example, though an image only exists as a single property in vcard, in HTML it is both a URL to a resource ''and'' and text string (alt) representing an accessible fallback. A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context. Likewise, an application interpreting a URL may also consider using the original inner text as an inferred label. Both pieces of data are useful, and a generic parser should not discard elemental semantics at the extraction level.
** It's not just "*common* to parse an attribute rather than inner text of an element for these properties" - it is the vast overwhelming majority - if not all - such cases!
** One misconception: "image only exists as a single property". No, there is both 'photo' and 'logo'. The 'url' and 'sound' properties are also of type 'url'. For all of these, when parsing an "object" element, you must use the 'data' attribute first for example. hCalendar has "attachment" as well. Etc.
** Theoretical assertion: "A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context." Why? There is no existing nor demonstrated use case for this requirement, even across other formats. While I agree it "might be nice" to develop a new "structured image" type - that's brand new work (deserving of research per the [[process]] etc.), and not a good source of reasoning to reject existing working patterns. I reject blocking microformats 2.0 on an as-yet-to-be-researched-enhancement. This is certainly a case where "better" is an enemy of the good.
** Theoretical assertion: "a generic parser should not discard elemental semantics at the extraction level" - already does for other syntaxes like both microdata and RDFa - so clearly this is not a reasonable "should not" assertion (and thus unnecessary) for development of a minimally competitive syntax. RDFa kind of cheats by overloading the 'rel' attribute in attempt to solve the name+url case as mentioned above, but that's only two types - and existing real world use of microformats has demonstrated utility of a few more. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
</div>

Given this, hungarian prefixes are of no benefit to parsers (and may in fact harm applications down the chain if parsing is prematurely strict.) It would be sufficient then not to concern embedding data types in property names, and instead settle on one single property prefix to differentiate all properties consistently. This would reduce the prefixes to just 3:

* <code>h</code> would indicates a root class name. An ‘object in HTML’.
* <code>p</code> would indicates a property within an object.
* <code>x</code> would indicates an experimental extension to an object.

--[[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)

The primary benefit of type-specific parsing is *not* for parsers, but rather, publishers (who we still hold in higher priority than parsers).

I will also note that *each* of the type-specific parsing methods in [[hcard-parsing]] was added both conservatively, reluctantly, and only when it became clear that such type-specific publishing patterns existing across *multiple* sites that would otherwise be unable to change their markup to work with microformats (Yes, I'm wishing now that I better documented exactly *which* sites, precisely *when*, but like many startups, early on we didn't exactly know how much to document vs get things done - frankly I think we documented far more than any other comparable such efforts, e.g. we managed to at least capture/grow both an explicit [[process]] and [[principles]] in *far* greater detail than anything remotely comparable either before microformats or since!). The type-specific parsing features are certainly not overdesigned, on the contrary they've *slowly* evolved, adapting to real world data on the web.

While per the [[simplicity]] principle, I would actually *strongly* prefer to only have the three prefixes given above, or actually just *two* (I started with just two for the design of microformats 2.0 actually, just "h-*" and "p-*"), doing so would be a step *backwards* in terms of the adaptability of microformats to existing markup, and that's IMHO an unacceptable barrier, and a sufficiently high barrier to hurt the adoption/applicability of microformats 2.0.

(Aside: In addition, note that you still need h-x-* for experimental objects, and thus it's *simpler* to simply have *both* h-x-* and p-x-* rather than add x-*. Alternatively x-h-* and x-p-* is no better, in some ways worse, in that object vs. property is a more important distinction for parsers than established vs experimental, especially if/when an experimental property (or object) may be adopted. Also, mild precdent: PNG started with image/x-png, not x-image/png.).

To put it in a positive way, type-specific parsing conveys microformats a publisher-markup-density (and re-use) advantage which neither microdata nor RDFa have, and it would behoove us to *keep* this significant real-world advantage as we evolve microformats.

-- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-faq]]

microformats2-prefixes

2011-09-20T01:05:16Z

BenWard: /* prefixes for future consideration */ List of properties and examples in various microformats that can legitimately contain more mark-up.

<entry-title>microformats 2 prefix conventions</entry-title>

[[microformats 2]] uses a small number of prefixes to distinguish microformats 2 class names from other class names.

== motivating causes ==
As described on the [[microformats 2]] page.

=== distinguishing properties from other classes ===
Current microformats properties re-use generic terms like "summary", "photo", "updated" both for ease of use and understanding.

However, through longer term experience, we've seen sites that accidentally drop (or break) their microformats support (e.g. Upcoming.org, Facebook) because web authors sometimes rewrite all their class names, and either are unaware that microformats were in the page, or couldn't easily distinguish microformats property class names from other site-specific class names.

This issue has been reported by a number of web authors:
* [http://html5doctor.com/microformats/#comment-10241 Wim's comment on HTML5Doctor] "Authors use classes like 'url' or 'region' all the time ... All sorts of markup might look like a microformat."
* ...

There has also been an anecdotal report of a design firm who was not (yet) familiar with microformats seeing the "extra" classes that "that don't seem to be used" (without corresponding CSS rules) and asking if they "can remove them". By making microformats class names different from generic words, authors unfamiliar with microformats may at least notice such distinction and infer special functionality accordingly.

Thus microformats 2 uses ''prefixes'' for property class names, e.g.:
* '''p-summary''' instead of ''summary''
* '''u-photo''' instead of ''photo''
* '''dt-updated''' instead of ''updated''

Such prefixing of all microformats class names was first suggested by Scott Isaacs of Microsoft to Tantek on a visit to Microsoft sometime in 2006/2007, but specifically aimed at making microformats easier to parse. At the time the suggestion was rejected since microformats were focused on web authors rather than parsers.

However, since experience has shown that distinguishing property class names is an issue for '''both web authors and parser developers''', this is a key change that microformats 2 is adopting. See the next section for details.

=== existing microformats parsing requirements ===
A non-trivial number of parser and tools developers have been sufficiently frustrated with some general issues with microformats that they've done the significant extra work to support very different and less friendly alternatives (microdata, RDFa). Based on this real-world data (market behavior), it behooves us to address these general issues with microformats for this constituency.

COMMUNITY and TOOLS (that) USE MICROFORMATS
* parser / parsing
* structured
* getting the data out
* json - 1:1 mapping

[[parsing]] microformats currently requires
# a list of root class names of each microformat to be parsed
# a list of properties for each specific microformats, along with knowledge of the type of each property in order to parse their data from potentially different portions of the HTML markup
# some number of format-specific specific rules (markup/content optimizations)

This has meant that whenever a new microformat is drafted/specificied/adopted, parsers need to updated to handle it correctly, at a minimum to parse them when inside other microformats and avoid errantly implying properties from one to the other (containment, [[mfo]] problem).

== microformats 2 prefixes ==
=== naming conventions for generic parsing ===
There is a fairly simple solution to #1 and #2 from the above list, and we can make progress towards minimizing #3. In short:

'''Proposal: a set of naming conventions for microformat root class names and properties that make it obvious when:'''
* a class name represents a microformat root class name
* a class name represents a microformat property name
* a class name represents a microformat property that needs special parsing (specific type of property).

In particular - derived from the real world examples of existing proven microformats (rather than any abstraction of what a schema should have)
* '''"h-*" for root class names''', e.g. "h-card", "h-event", "h-entry"
** The 'h-' prefix is based on the existing microformats naming pattern of starting with 'h'.
* '''"p-*" for simple (text) properties''', e.g. "p-fn", "p-summary"
** vocabulary generic parsing, element text in general, treat certain HTML element/attribute combination as special and use those first, e.g. img/alt, abbr/title.
** The 'p-' prefix is based on the word "property" starting with 'p'.
* '''"u-*" for URL properties''', e.g. "u-url", "u-photo", "u-logo"
** special parsing required: prefer a/href, img/src, object/data etc. attributes to element contents.
** The 'u-' prefix is based on URL/URI starting with the letter 'u', which is the type of most of these related properties.
* '''"dt-*" for datetime properties''', e.g. "dt-start", "dt-end", "dt-bday"
** special parsing required: [[value-class-pattern]], in particular separate date time value parsing for better human readabillity / DRY balance.
** The 'dt-' prefix is based on "date time" having the initials "dt" and the preponderance of existing date time properties starting with "dt", e.g. dtstart, dtend, dtstamp, dtreviewed.
*** Initially I had proposed "dt-*" but Chris Messina suggested reducing it to "d-*" so that all prefixes were a single letter - made sense.
*** However, I've noticed that Google+ is using "d-*" class names on [https://plus.google.com/109182513536739786206 profile pages], thus we can't really use 'd-' as a microformats 2 property parsing prefix. [[User:Tantek|Tantek]] 03:00, 22 July 2011 (UTC)
*** Frankly I also think this provides a simpler transition/education story for existing microformats authors/publishers: "h*" to "h-*", "dt*" to "dt-*", url type properties to "u-*", and "p-*" for all others.

See [[microformats-2-prefixes]] for further thoughts and discussions on these and other class prefixes.

==== prefixes for future consideration ====
possibly also:
<div class="discussion">
* '''"e-*" for properties''' where the entire contained element hierarchy is the value, e.g. "e-content" (formerly "entry-content") for [[hAtom]].
** unclear if this is necessary in general. and if so, if this is only for hAtom, that's insufficient to justify putting it in the generic syntax.
** Would be sufficient to have all <code>p-</code> properties parse the complete content, including any nested mark-up if present, and then implementations to sanitize/run a <code>strip_tags</code> style function (as per data input best practice) as appropriate. --[[User:BenWard|BenWard]] 22:05, 19 September 2011 (UTC)
** Ouch that sounds like passing on complexity downstream for all cases just to handle *one* known use-case so far. Since we'd typically do the opposite (simplify for the 99% case over the 1% case), passing on content including mark-up by default seems like a step backwards. Also, given how many vulnerabilities seem to deal with parsing/filtering, doing that *first* rather than burdening downstream implementations seems like the right choice. I'd rather wait til we get a concrete complaint from a microformats-2 hAtom consumer before worrying about this for hAtom 2.0. Or are there other current real world use cases besides Atom? [[User:Tantek|Tantek]] 22:22, 19 September 2011 (UTC)
*** In addition to <code>entry-content</code> in hAtom there's also <code>entry-summary</code>, plus any large region of text in other microformats, which at the very least can commonly contain additional hyperlinks, images, and phrasing mark-up: <code>description</code> in hCal, hReview, hProduct, hListing, <code>note</code> in hCard, <code>ingredient</code>, <code>instructions</code> in hRecipe may link to a store, or wikipedia entry for the ingredient, or include an image to illustrate a step of a recipe, as well as recipe instructions that are expressed as lists. If an author/publisher marks up a property in such a way that it contains further mark-up, that mark-up should be assumed to be part of the value. It's always going to be up to an implementation to decide whether it wishes to translation that HTML mark-up into some other format (e.g. Markdown-esque text annotation when converting to something like <code>vcard</code>, or some other kind of formatting language on non-HTML platforms, or stripping text altogether. —[[User:BenWard|BenWard]] 01:05, 20 September 2011 (UTC)
* '''"i-*" for ID properties''', e.g. "i-uid" (if this is the only one, then perhaps we just always re-use "uid" or collapse with "u-*" into "u-id".)
** parsing is no different than "u-*" parsing, thus no need to introduce for now.
* '''"n-*" for numbers''', e.g. "n-rating", "n-geo", where the numbers may have different human-readable-friendly and decimal/machine values (e.g. with geo lat/long degrees minutes seconds vs decimal).
** requires definition of how would different parsing work before worthy of consideration.
* '''"t-*" for time duration''', e.g. "t-duration" in [[hCalendar]], [[hAudio]], [[hRecipe]] (note also Google's hRecipe extensions "preptime", "cooktime", "totaltime")
** requires definition of how would different parsing work before worthy of consideration.
</div>

==== reserving other prefixes ====
We should '''reserve all other single-letter-dash prefixes for future use.'''

In practice we have seen little (if any) use of single-letter-dash prefixing of class names by web developers/designers, and thus in practice we think this will have little if any impact/collisions. Certainly far fewer than existing generic microformat property class names like "title", "note", "summary".

==== existing single letter class prefixes ====
We should document existing usage of single/double letter prefixed names:
* Google+ (e.g. [https://plus.google.com/109182513536739786206 profile page], others) uses:
** '''a-'''
** '''d-'''
** '''g-''', '''gb*'''
* Yahoo
** '''y-'''
* others? please add alphabetical by company/org name.

== microformats 2 example ==
Example: taking that simple heading hCard example forward:

<source lang=html4strict>
<h1 class="h-card">Chris Messina</h1>
</source>

As part of microformats 2.0 we would immediately define root class names and property names for all existing microformats and drafts consistent with this naming convention, and require support thereof from all new implementations, as well as strongly encouraging existing implementations to adopt the simplified microformats 2.0 syntax and mechanism. Question: which microformats deserve explicit backward compatibility?

As a community we would continue to use the microformats [[process]] both for researching and determining the need for new microformats, and for naming new microformat property names for maximum re-use and interoperability of a shared vocabulary.

If it turns out we need a new property type in the future, we can use one of the remaining single-letter-prefixes to add it to microformats 2.0. This would require updating of parsers of course, but in practice the number of different types of properties has grown very slowly, and we know from other schema/programming languages that there's always some small limited number of scalar/atomic property types that you need, and using those you can create compound types/objects that represent richer / more complicated types of data.

=== ADVANTAGES ===
This has numerous advantages:
* '''better maintainability''' - much more obvious to web authors/designers/publishers which class names are for/from microformats.
* '''no chance of collision''' - for all practical purposes with existing class names and thus avoiding any need to add more complex CSS style rules to prevent unintended styling effects.
* '''simpler parsing''' - parsers can now do a simple stream-parse (or in-order DOM tree walk) and parse out '''all''' microformat objects, properties, and values, without having to know anything about any specific microformats.
* '''separation of syntax and vocabulary''' - by abstracting microformats 2 syntax independent of any vocabulary, it allows and encourages development of shared vocabularies that can work in alternative syntaxes.

More examples: here is that same heading example with name components:

<source lang=html4strict>
<h1 class="h-card">
<span class="p-fn">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</span>
</h1>
</source>

with a hyperlink to Chris's URL:

<source lang=html4strict>
<h1 class="h-card">
<a class="p-fn u-url" href="http://factoryjoe.com/">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</a>
</h1>
</source>

=== COMPATIBILITY ===

microformats 2.0 is backwards compatible in that in permits content authors to markup with both old and new class names for compatibility with old tools.

Here is a simple example:

<source lang=html4strict>
<h1 class="h-card vcard">
<span class="fn">Chris Messina</span>
</h1>
</source>

a microformats 2.0 parser would see the class name "h-card" and imply the one required property from the contents, while a microformats 1.0 parser would find the class name "vcard" and then look for the class name "fn". no data duplication is required. this is a very important continuing application of the <abbr title="don't repeat yourself">DRY</abbr> [[principle]].

And the above hyperlinked example with both sets of class names:

<source lang=html4strict>
<h1 class="h-card vcard">
<a class="p-fn u-url n fn url" href="http://factoryjoe.com/">
<span class="p-given-name given-name">Chris</span>
<abbr class="p-additional-name additional-name">R.</abbr>
<span class="p-family-name family-name">Messina</span>
</a>
</h1>
</source>

== vendor extensions ==
(this section was only discussed verbally and not written up during discussions - capturing here as it is topical)

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties has in recent years allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

There have been times when specific sites have wanted to extend microformats beyond what the set of properties in the microformat, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

'''Proposal:'''
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension OR
** OR "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-)
** e.g.
** "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "onering" microformat root class name.
** "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)
** "p-x-prep-time" - a possible experimental property name to be added to hRecipe upon consideration/documentation of real-world usage/uptake.

Background - this proposal is a composition of the following (at least somewhat) successful vendor extension syntaxes
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

== issues ==
=== Hungarian prefixing issues ===
Raised by [[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)

Microformats 2.0 proposes using an explicit <code>[a-z]-</code> prefix on properties, to differentiate them from other uses of the class attribute, and identify them as microformat properties, such that they can be parsed generically.

* The differentiation use case is supported by anecdotal evidence of sites (such as Facebook, Twitter, Yahoo) removing microformats or breaking objects in page edits. The addition of a prefix assists self-documentation of code.
* The generic parsing use case is supported by Google Rich Snippets, Yahoo Search Monkey, and extensible plugins like Operator and the Firefox microformats parser. Although these extract microformats from the page, they are intermediate systems between the page content and the actual interpretation of the data. They need to parse all objects from a page, and then another developer or application will interpret some of them into something else.

(Note: the theoretical assertion "they need to parse all objects from a page" is not actually backed by *any* existing use of microformats/microdata/RDFa parsing - *none* of those parse "all objects from a page" if you consider every markup element an "object" - rather, one of the strength of microformats (mimicked by the others) is that the publisher is able to markup *just* the data to be extracted, rather than perhaps purely "presentational" content, ads, UI widgets etc. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )

The µf2 proposal goes further, though, into a small vocabulary of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian] prefixes of properties based on data type. This increases the level of understanding required to read microformats, and reduces the benefit of all microformat properties having a consistent identifying prefix.

(Debatable assertion:"increases the level of understanding required to read microformats" - how? In microformats 2.0, authors/developers know that any single-letter-and-hyphen prefixed class name is for microformats 2.0, in contrast to today - developers have consistently given feedback that's hard to tell which generic class names (other than h* names) are microformat related and which are not. As for specific prefixes, "h-*" is special and follows the pattern of existing microformats. p = generic (p)roperty, and the other prefixes have trivial mnemonics as well, d for (d)atetimes etc. (so far, hopefully we can keep that up). -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )

Hungarian notation itself is controversial amongst programmers.
Plenty find it uglifies their code, can be a cause of confusion (especially when very-short prefixes are used, or esoteric types, or where the declared set of types differs from the available types in other programming languages.) Others support its benefits to type identification.

(Programmers are not the priority here, rather, designers/authors/publishers are. We design microformats for them first as they're the common use case, and we should avoid making statements that seem to imply any priority for the aesthetic preferences of programmers. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC))

Critically, however, there is no clear indication that either of the above use cases requires types to be strongly identified.

<div class="discussion">
* For identifying µf in pages, a differentiator is required from regular classnames. There is no evidence of further requirement to differentiate between properties beyond their name (and existing criticisms of Hungarian notation suggest it can harm understandability.)
** There is such evidence, and perhaps thus this would be a good FAQ topic. The derivation is quite simple - it comes directly from minimally affecting existing markup, and maximally using existing semantic information. Example of special purpose parsing, URL-like properties use the value of the 'href' (or equivalent) attribute because that's where that data already is in pages. Similarly with dates and datetimes - special parsing rules for that data type have permitted us to design the [[value-class-pattern]] to take advantage of specially parsing date and time separation. By re-using data *where publishers already put it, including attributes vs inline* we minimize the risk of data drift. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
** Additionally, this special type-specific parsing of microformats properties conveys microformats advantages of markup brevity that other syntaxes lack. E.g. you can convey *multiple* properties and values from a single existing element, e.g. the *very* common real-world pattern <code><br/><nowiki><a href="http://example.com/user">User Name</a></nowiki><br/></code> is minimally marked up as <code><br/><nowiki><span class="h-card"><a class="p-name u-url" href="http://example.com/user">User Name</a></span></nowiki><br/></code>
* For generic parsing, there is no requirement that datatypes be established at extraction time. Data types will instead be applied by the developers of apps and widgets that build on the generic parsers.
** There are requirements based on experience with actual markup. In order to support the patterns of where content publishers put the data we want to extract, we have determined (based on those publishing patterns) a few different ways (types) of parsing this data. This is all captured in the [[hcard-parsing]] property-specific parsing rules each of which were added one at a time as Brian Suda and myself encountered real world sites wanting to use [[hCard]] but not wanting to have to rewrite their markup (adding one span and some class names was about the limit, moving tags/attributes around was a showstopper in many/most cases), and each of the microformats 2.0 "types" are directly derived from such special purpose data/type parsing across *multiple* microformats. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
* A counter argument may be that special properties in microformats—such as URLs, or images—need to be identified because in microformats it is common to parse an attribute (href, or src) rather than inner text of an element for these properties. However, in the context of extracting and then interpreting HTML in other contexts this is insufficient: For example, though an image only exists as a single property in vcard, in HTML it is both a URL to a resource ''and'' and text string (alt) representing an accessible fallback. A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context. Likewise, an application interpreting a URL may also consider using the original inner text as an inferred label. Both pieces of data are useful, and a generic parser should not discard elemental semantics at the extraction level.
** It's not just "*common* to parse an attribute rather than inner text of an element for these properties" - it is the vast overwhelming majority - if not all - such cases!
** One misconception: "image only exists as a single property". No, there is both 'photo' and 'logo'. The 'url' and 'sound' properties are also of type 'url'. For all of these, when parsing an "object" element, you must use the 'data' attribute first for example. hCalendar has "attachment" as well. Etc.
** Theoretical assertion: "A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context." Why? There is no existing nor demonstrated use case for this requirement, even across other formats. While I agree it "might be nice" to develop a new "structured image" type - that's brand new work (deserving of research per the [[process]] etc.), and not a good source of reasoning to reject existing working patterns. I reject blocking microformats 2.0 on an as-yet-to-be-researched-enhancement. This is certainly a case where "better" is an enemy of the good.
** Theoretical assertion: "a generic parser should not discard elemental semantics at the extraction level" - already does for other syntaxes like both microdata and RDFa - so clearly this is not a reasonable "should not" assertion (and thus unnecessary) for development of a minimally competitive syntax. RDFa kind of cheats by overloading the 'rel' attribute in attempt to solve the name+url case as mentioned above, but that's only two types - and existing real world use of microformats has demonstrated utility of a few more. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
</div>

Given this, hungarian prefixes are of no benefit to parsers (and may in fact harm applications down the chain if parsing is prematurely strict.) It would be sufficient then not to concern embedding data types in property names, and instead settle on one single property prefix to differentiate all properties consistently. This would reduce the prefixes to just 3:

* <code>h</code> would indicates a root class name. An ‘object in HTML’.
* <code>p</code> would indicates a property within an object.
* <code>x</code> would indicates an experimental extension to an object.

--[[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)

The primary benefit of type-specific parsing is *not* for parsers, but rather, publishers (who we still hold in higher priority than parsers).

I will also note that *each* of the type-specific parsing methods in [[hcard-parsing]] was added both conservatively, reluctantly, and only when it became clear that such type-specific publishing patterns existing across *multiple* sites that would otherwise be unable to change their markup to work with microformats (Yes, I'm wishing now that I better documented exactly *which* sites, precisely *when*, but like many startups, early on we didn't exactly know how much to document vs get things done - frankly I think we documented far more than any other comparable such efforts, e.g. we managed to at least capture/grow both an explicit [[process]] and [[principles]] in *far* greater detail than anything remotely comparable either before microformats or since!). The type-specific parsing features are certainly not overdesigned, on the contrary they've *slowly* evolved, adapting to real world data on the web.

While per the [[simplicity]] principle, I would actually *strongly* prefer to only have the three prefixes given above, or actually just *two* (I started with just two for the design of microformats 2.0 actually, just "h-*" and "p-*"), doing so would be a step *backwards* in terms of the adaptability of microformats to existing markup, and that's IMHO an unacceptable barrier, and a sufficiently high barrier to hurt the adoption/applicability of microformats 2.0.

(Aside: In addition, note that you still need h-x-* for experimental objects, and thus it's *simpler* to simply have *both* h-x-* and p-x-* rather than add x-*. Alternatively x-h-* and x-p-* is no better, in some ways worse, in that object vs. property is a more important distinction for parsers than established vs experimental, especially if/when an experimental property (or object) may be adopted. Also, mild precdent: PNG started with image/x-png, not x-image/png.).

To put it in a positive way, type-specific parsing conveys microformats a publisher-markup-density (and re-use) advantage which neither microdata nor RDFa have, and it would behoove us to *keep* this significant real-world advantage as we evolve microformats.

-- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-faq]]

process

2011-09-20T00:48:02Z

BenWard: /* related issues questions regarding document stages */ Propose ‘Archiving’ rather than ‘uninteresting’

If this is your first visit, please see the [[introduction]] page first.

<entry-title>The microformats process</entry-title>

'''So you wanna develop a new microformat?'''

'''Or just a new vocabulary?'''

'''Or create a new standard based on empirical research and scientific methods?'''

This document will help guide you through the steps to take towards achieving these goals.

The microformats process has been cited as inspiration for other standards groups and efforts such as the WHATWG and ActivityStreams.

;Editor
:[[User:Tantek|Tantek Çelik]]

{{TOC-right}}

== Get some experience first ==
Before even considering pursuing a new microformat, first:

# Make your site [[POSH]].
# Add <em>existing</em> microformats to your sites like [[hcard|hCard]] for your contact info etc., [[hcalendar|hCalendar]] for your events, [[hatom|hAtom]] for your episodic content (e.g. blogs). See [[get-started]] for more specific examples of adding microformats to your sites.

This will help familiarize you with how [[POSH]] and [[microformats]] currently work. Such "real world" experience will greatly help you with the development a new microformat. For more on this see [[why-using-existing-microformats-matters]].

Then, ask yourself:

==Why?==
There must be a problem to be solved (i.e. a real world use case). No problem, no microformat.

Once you've found your 'problem,' ask yourself: 'is there a simpler problem here?' If so, let's solve that problem first. We want to deal with the simplest problems first and only then build up to more complex problems.

Perhaps someone else is pursuing (or has pursued) a similar problem.

Check the [[exploratory-discussion]] page, and search around on the web. Chances are that someone else has encountered the same problem as you. There are very few truly new problems.

If you still believe that you have a new and unsolved problem, post something to the [[irc]] channel, and if no one is around, then the [http://microformats.org/mailman/listinfo/microformats-new/ microformats-new] mailing list. It's better to get the community involved in the discussion. Start the discussion '''<span style="text-transform: uppercase;">before</span>''' you start creating any pages on the wiki.

We're not using the wiki as a general "scratch pad". If you can't summarize the problem you are trying to solve in a short email, and feel like you need a long document, you're probably trying to solve too big of a problem - see previous point about 'is there a simpler problem here?' and simplify until you describe your problem and real world use case in a short paragraph.

== Check Exploratory Discussions For Previous Work ==
It may be possible that someone else has tried (or is trying to) solve the same real world problems as you.

Check the [[exploratory-discussions]] page ''before'' starting new pages for your effort to see if you can add to / iterate on an existing effort before creating a new one.

==Document Current Behavior==
Document examples of current human publishing behavior.

[[why-examples|Why examples first?]] Read that. It's important and gets to the core of what makes microformats efforts different than many/most previous/other format development efforts.

We're [http://ifindkarma.typepad.com/relax/2004/12/microformats.html paving the cowpaths]- before you do that you have to ''find'' the cowpaths.

By ''cowpaths'' here we mean ''real world publishing examples''. Your [[examples]] should be a collection of real world sites and pages which are publishing the kind of data you wish to structure with a microformat. From those pages and sites, you should extract markup examples and especially the schemas implied therein, and provide analysis.

This collection of examples should be public, preferably on the microformats wiki because it's unlikely you can do it by yourself (no matter how many of you there are), and having others even just check your work will help improve its quality.

The [[reviews-formats]] page is a good example of research done before the creation of a microformat. Before developing [[hreview|hReview]], the collaborators went out, documented current practices around reviews on web sites, and provided some analysis of the schemas implied therein.

Note: these examples are about the ''content'' (and schemas ''implied'' therein) not about formats, class names, pre-existing standards etc. That comes next.

Study the examples and determine the ''implied'' (not explicit) schema of data that is being published (the conceptual properties about the data - not literal class names). Sort these by frequency and determine which appear in roughly 80% of cases (per the 80/20 rule, Pareto [[principle]]).

If you can't find real world publishing examples of the type of data you want to represent using a microformat, then stop here. It doesn't need a microformat.

==Document Previous Efforts==
Once you've documented real world publishing examples of the kinds of data you want to represent, the next step is to research efforts at developing formats for those kinds of data.

There are almost always previous efforts at formats for whatever kind of data you want to represent using microformats.

Learning from previous format efforts is important, because it helps:
* minimize repeating mistakes by others
* explore why a previous format succeeded (or didn't)
* provide a source of vocabulary to express a new microformat

In particular, ask yourself: "are there any well established, interoperably implemented standards we can look at which address this problem?"

For example, hCard and hCalendar were built on top of the IETF standards for vCard and iCal, respectively, both of which are widely interoperably implemented, and dominant in their space (there were no competing formats with anywhere near the same levels of adoption).

The developers of those standards had already spent many years in standards committees arguing about and developing their schemas. Better to leverage all the hard work that others have done before you, than to go off as a solo cowboy inventor, and waste time repeating all their mistakes. It's also much easier to start from a well established schema, and map into into semantic HTML than to develop a new schema.

It's quite possible during this step that you'll find someone else who has dealt with the problem(s) you're addressing. Perhaps even solved it/them. Do your best to open a dialog with others who have encountered the same problem(s). We don't want to build walls between competing communities - we want people to work together to develop a good solution which will cover the majority of cases.

If you can't find previous efforts at formats for the data you want to microformat, ask in [[IRC]] and on the [[mailing-lists]].

==Brainstorm Proposals==
By now you've researched previous examples and previous formats and you're finally ready to write up brainstorms towards a new microformat.

Actually, <strong style="text-transform:uppercase;">don't!</strong>

There are other things to try before developing a microformat. First, ask yourself these questions:

# Is there a standard element in HTML that would work?
# Is there a compound of HTML elements that would work?

If so, document these on the brainstorming page, and stop. There is no need for a microformat.

Let's not unnecessarily reinvent what you can already do with HTML.

For more details on semantic HTML, examples of using HTML elements, and constructing HTML (and XHTML) compounds, see [http://tantek.com/presentations/2005/03/elementsofxhtml/ The Elements of Meaningful XHTML].

Otherwise, if you can clearly and confidently answer "no" to the above two questions, we can talk about a microformat.

Before you start your act of creation, familiarize yourself [[microformats#the_microformats_principles|the microformats principles]].

There's basically two steps to writing up a brainstorm proposal:

# Go back to that list of real world publishing examples that you researched, and collect the 80/20 of the implied conceptual schema from the examples.
# Give each of those concepts a property name, re-using from, in order:
## existing microformats
## previous formats
## simple but specific human readable English words and phrases

Congratulations, you've written up a brainstorm proposal with a list of class names for a possible microformat.

You may notice that we completely skipped ''naming'' the potential new microformat itself. This is not an accident, this is deliberate. Naming is tempting, and good naming is hard. Thus naming is discussed later.

The key is, the explicit schema of the microformat (what properties and hence class names are in it) is '''more important''' than the name.

Remember, microformats should be designed for humans first and machines second. Here are few questions that may help you decide if you really need a microformat for the problem you are trying to solve:

# If I looked at this microformat in a browser that didn't support CSS or had CSS turned off, would it still be human-readable?
# Are this format's elements stylable with CSS?

If the proposed format doesn't pass these two things, it's not likely to gain much acceptance. Remember: ''humans first, machines second''.

== Iterate ==
Now that you have a simple brainstorm proposal, what do you do?

Iterate. Iterate. Iterate.

In the process of developing a microformat, you'll likely get a lot of feedback from others interested in microformats. The effort needs to be iterated and adapted. Microformat development should be open, and preferably collaborative and community-based.

Here's an ASCII-art flow diagram of where you're going
<pre>
DIAGRAM:
problem statement---->research/discussion---->proposal/draft---->specification
^________________V ^___________________V ^______________V
</pre>

Note that each stage involves iteration. That iteration consists of discussion and feedback and may result in major changes. Do not be afraid to make major changes and please don't get too attached to any particular solutions.

Feel free to explore ''multiple'' proposals one after another on the brainstorming page. The goal here is to explore reasonable microformat solutions, including multiple possibilities, alternatives etc.

== Naming considerations ==
'''DO NOT''' start with even labeling your effort "hXYZ". This is a ''very'' common mistake.

Always start with the general problem area.

Thus name the problem area (*- pages below) generically and specifically avoid starting with code name / brand name like hNewCoolFormat.

Good: '''[[product-examples]]'''. Bad: '''hProduct-examples'''.

After you've iterated your research and brainstorming at least a bit, you've likely gained sufficient understanding of the problem-space that you're solving to start looking at naming considerations.

== Pages to create ==
After a specific problem area ('''*''') has been determined (principle 1), consider creating and filling out the following pages for it, and add the first to [[exploratory-discussions]]. If you're unable to come up with material for the pages, then you should probably reconsider whether or not the problem is worth (or ready for) solving.
# '''*-examples''' Find examples on today's web of the the type of content you think needs a microformat. Document them with URLs. Document the schemas implied by the content examples. This is the action that helps follow principle 3, design for humans first, machines second ... adapt to current behaviors and usage patterns. Start by cloning the [[examples]] page and filling it out.
# <span id="formats">'''*-formats'''</span> Find widely adopted interoperable current data formats and standards that attempt to or have attempted to solve the problem previously. Document their explicit schemas. This is necessary prerequisite for following through with principle 4, "reuse building blocks from widely adopted standards".
# <span id="brainstorming">'''*-brainstorming'''</span> Use the current real-world web examples and their implicit schemas to determine an 80/20 as-simple-as-possible (principle 2) generic schema to represent their data. Yes, this means you will explicitly ''omit'' some features of some use cases, or perhaps entire use cases which are more edge-cases than representative of larger, aggregate/macro behaviors. See which existing microformats can be reused as building blocks (principle 5, modularity). Use those existing data formats and schemas as a [[existing-classes|source of names]] for the fields (principle 4). Consider how would you embed this microformat in other formats (also principle 5, embeddability). See the [[brainstorming]] page for a bit more info.<p> With an 80/20 schema, and a source of field names, write up one or more straw proposals for a microformat in the *-brainstorming page. Make sure the straw proposals encourage the decentralized distribution of data (principle 6). Postpone the choice of root class name as it often overlaps with the naming of the microformat itself. Always keep close at hand the [[naming-principles|microformats naming principles]] when choosing names.</p><p>Brainstorming about the substance of the microformat (its properties and values) should precede naming the microformat itself. Thus after proposals have been written up and are being discussed for the schema, create a naming section for the microformat itself and root class name, where various names can be considered.</p>
# '''**''' When it seems like there is rough consensus around one of the brainstorm proposals for a microformat with a specific name('''**'''), write it up as a separate wiki page as a draft specification (see [[style-guide]]), and then start creating the following pages to track it.
# '''**-faq''' There will likely be common questions about the new microformat which can/should be answered in an FAQ page.
# '''**-issues''' Folks may also raise issues about the microformat which aren't immediately addressable. An issues document helps serves to capture these issues, who raised them, and when, so that folks working on the microformat can be sure to go through and thoroughly answer them.
# '''**-examples''' Eventually there may be too many real world examples of a microformat to document them in an informative section at the end of the specification, thus the list deserves its own page.
# '''**-implementations''' Eventually there may be too many implementations of a microformat to document them in an informative section at the end of the specification, thus the list deserves its own page.
# '''**-brainstorming''' Eventually there will be non-trivial proposals/suggestions/clarifications for changes in the microformats as part of iteration. Create such a format specific [[brainstorming]] page for such suggestions.

== Moving from Stage to Stage ==
These stages of development are mirrored on the main page where microformats are divided into "Exploratory Discussions", "Drafts", and "Specifications". Based on feedback we've added a new stage: "Standards".

How do microformats move from one stage to the other?

=== Exploratory Discussions ===
Document your problem area, existing research, and brainstorm proposals on the [[exploratory-discussions]] page.
You should do it on this wiki using current items under exploratory discussion as a guide.

Then send a note to the microformats-new list to get the attention of others who are interested in microformats. This is probably a good chance to pull in people from outside the current microformats community who may also be experiencing the same issue.

Feedback will probably range the gamut. Others may challenge your problem statement, the need for a microformat, concur, or add. All constructive feedback is good.

As a result of feedback, you may decide to abandon your microformat idea or substantially modify it or add more alternatives to brainstorm proposals to consider.

One thing you want to be sure to do at this stage is to avoid [[reinvented-wheels|reinventing the wheel]].

Are there elemental microformats you can reuse as building blocks? Doing this will save you effort and help you get implemented later because implementers will have less work to do.

=== Drafts ===
Once there seems to be rough consensus around a particular brainstorm proposal, including a specific schema and list or properties, write that brainstorm proposal into a draft.

Summary of what is a draft:

* '''draft''' - experimental new microformat
** '''preconditions:'''
*** rough consensus has been reached among the various *-brainstorming proposals
** '''actions:'''
*** determine a name for the new microformat (**)
*** write-up consensus brainstorm into a stand-alone draft
*** create **-issues page for collecting feedback
** '''means:'''
*** ready for publishers to start experimenting with on their public pages
*** ready for consumers to start experimenting with consuming such publishers
*** and both providing feedback for draft iteration accordingly
** '''stability:'''
*** major changes can still occur
*** e.g. add/drop/rename arbitrary features (per research/feedback from publishers/consumers)

Drafts are written up on the wiki using the draft template. Upon writing up a draft, send a note to the microformats-new mailing list to alert people that something new has happened. Continue encouraging feedback from relevant resources both inside and outside the community. Drafts need to include at least the following:

* Statements regarding the fact that you will not patent and are adopting appropriate copyright (preferably PUBLIC DOMAIN) as illustrated by current drafts.
* An XMDP stating explicit property and value names. You may want to place this on a separate wiki page and link to it. In that case use the naming convention *-profile, e.g. [[hcard-profile]].
* Examples from current practice that show how the microformat would be used. Keep an eye out for how the microformat is actually improving things. If it's not, that might be an indication that you either need to abandon or change a lot.
* Use of [[rfc-2119]] terms.
* References that back up your design decisions for the microformat. To the extent possible, you do not want to invent things from whole cloth. This should be relatively easy if you have followed the process so far with proper research.
* A list of implementations (if any).
* An issues section for people to feed back to you with detailed objections.

=== Specifications ===
You will usually need at least one iteration to get past the draft stage.

By the time something becomes a specification, it should be stable so that developers can pick it up and write to it. This in turn implies that there are at least a couple of implementations.

This in turn implies that there are at least a couple of sites/implementations that have shown interest beyond the creator/editors of the specification.

Summary of what is a specification:

* '''specification''' - a stable and mature draft
** '''preconditions:'''
*** all outstanding **-issues resolved (hit zero issues for a few weeks)
*** 1+ solid real world publisher(s) that
**** are not the editor(s) of the spec (demonstrates some breadth of interest)
**** benefit end users (i.e. not just artificial data published for data's sake)
*** 1+ solid real world consumer(s) that
**** are not the editor(s) of the spec (demonstrates some breadth of interest)
**** successfully consume the microformats published by the publisher(s).
**** provide real world end user benefits / solve use-cases
**** (libraries/opensource are nice as enablers but insufficient for this)
** '''actions:'''
*** update draft to use specification template
*** create **-examples-in-wild, **-implementations pages to collect them
** '''means:'''
*** ready for publishers to start depending on
*** ready for consumers to start depending on
** '''stability:'''
*** minor changes can still occur
*** e.g. dropping of properties and values (e.g. to reach "standard" - see below)
*** iteration based on real-world publisher/consumer experience
** '''actions:'''
*** encourage widespread adoption by all publishers and consumers
*** evaluate properties published by <2 publishers
*** evaluate properties consumed by <2 consumers
**** such properties block advancement from specification to standard.
**** drop such under-supported property(ies) - insufficient market support to keep them. properties which fail in the real world should be and get dropped (per the simplify [[principle]]). features may be reconsidered for future versions.
**** or wait for more additional publisher(s)/consumer(s) to support them. up to editor's preference.
** '''example microformats to advance:'''
*** [[hReview]] and [[hAtom]] can become "specifications" with a bit of work:
**** resolve issues, incorporate into spec updates (0.4, 0.2 respectively)
**** *-examples-in-wild *-implementations pages show publisher(s)/consumer(s) support

Before moving to the specifications section, you must have resolved all outstanding issues.

Then, drop a note to microformats-new noting that all issues have been resolved, and encourage discussion and major objections. Since this may elicit additional feedback, allow some time (editor discretion, 3 weeks suggested), for more issues, resolutions, fixes.

If none are forthcoming, suggest moving the microformat to the specifications area. If there is sufficient explicit positive support from the community to do so, then do so. If not, then leave as draft. The absence of feedback is not approval and should be noted instead as a lack of interest.

=== Standard ===

This is a new document stage to represent not only stability, but market acceptance.

Summary of what is a standard:

* '''standard''' - market proven microformat
** '''preconditions:'''
*** test suite with 1+ test per feature (e.g. property) (should be easy)
*** 2+ solid real world publishers as defined above for "specification"
*** 2+ solid real world consumers as defined above for "specification" that:
**** pass the test suite tests
**** interoperably consume microformats published by the publishers.
*** each property is published by 2+ of those publishers
*** each property is consumed by 2+ of those consumers
** '''actions:'''
*** bump the version # to 1.0 (if it isn't there already)
** '''means:'''
*** the market is interoperably publishing and consuming this microformat
** '''stability:'''
*** the microformat is considered stable
*** minor errata expected per real world publishing/consuming experience
** '''example microformats to advance:'''
*** [[hCard]] and [[hCalendar]] can become "standards" with a bit of work:
**** incorporate resolved issues into 1.0.1 releases (use 1.0.1 due to how long we left them a 1.0)
**** write up remaining missing test cases for a full property (not necessarily value) coverage test suite
**** drop insufficiently supported properties (e.g. "class", "key")

==== documenting implementation support ====
Ideally implementation support should be documented with '''test suite results''':
* '''implementation test suite report''': list all tests and whether an implementation passes them or not
** these can be added to entries for each implementation in the '''**-implementations''' wiki page
* '''test suite implementation summary report''': list all tests and implementations that pass each one
** see the [[value-class-date-time-tests#results|value class pattern date and time test results]] table for an example.

'''Claimed implementation''': it's also useful to document:
* '''what properties/values/features''' an implementation ''claims'' to support
** with links to supporting documentation from the implementer's site
** list properties/values an implementation claims to support on the implementation's entry in the '''**-implementations''' wiki page

=== related issues questions regarding document stages ===

<div class="discussion">
* '''if/when does it make sense to demote a microformat spec to a lower level?'''
** '''can a standard be undone?''' we haven't seen any examples of this, but it is certainly possible that a sufficient implementations/publishers of a ''standard'' could disappear until it no longer meets requirements, should (and when should) it be demoted to just a ''specification'' or perhaps even a ''draft''?
** '''from spec back to draft''' it's possible that implementations or publishers may disappear, and thus what used to qualify as a ''specification'' no longer meets the requirements, when should it be demoted explicitly back to a ''draft''?
** '''undrafts''' e.g. there are plenty of drafts that never got any traction, should we have another category for "uninteresting-draft" that means no one other than the editor(s)/author(s) really cared for it, and thus it isn't a priority for the community. maybe we could call these "undrafts" - where drafts go when they don't make it to spec after some amount of time. From there it's probably best to simply use them for more brainstorming, and not encumber any future microformat effort with their legacy. This is likely important to keep the list of drafts as accurate/recent, and will also likely be challenging case-by-case judgment calls.
*** Perhaps rather than ‘undraft’, which is a slightly horrendous word, or ‘uninteresting’ which carries a subjective judgement, we could instead approach this with a kind of archiving strategy. After some period of non-progress/non-involvement/instability a draft becomes ‘Archived’ (or ‘Archived Draft’) to indicate the stagnation. It could become a regular draft again if someone finds it an interesting base. --[[User:BenWard|BenWard]] 00:48, 20 September 2011 (UTC)
</div>

== Other Documents ==
=== Patterns ===
What about other types of pages on the wiki, like "patterns" (e.g. [[include-pattern]])?

How do those get created?

The short explanation is this:

The patterns are not formats at all. They do not stand on their own. They are merely documentation of pieces of other formats that are expected to (or are) being reused by other formats.

The real world examples for includes in particular were documented in the context of [[resume-examples]], [[resume-formats]], and [[resume-brainstorming]] (as noted at the very top of [[include-pattern|the document]]) "Initially developed as part of resume-brainstorming..." Later, real world examples for reviews were found to need the include pattern as well.

When real world examples for ''multiple'' microformats require the solution of the same or a similar problem, then it is worth exploring the creation of a pattern that solves the problem across microformats.

== Related ==
* [[process-faq]]
* [[process-issues]]
* [[process-brainstorming]]

microformats2-prefixes

2011-09-19T22:05:56Z

BenWard: /* prefixes for future consideration */ @benward note about e- vs. p-

<entry-title>microformats 2 prefix conventions</entry-title>

[[microformats 2]] uses a small number of prefixes to distinguish microformats 2 class names from other class names.

== motivating causes ==
As described on the [[microformats 2]] page.

=== distinguishing properties from other classes ===
Current microformats properties re-use generic terms like "summary", "photo", "updated" both for ease of use and understanding.

However, through longer term experience, we've seen sites that accidentally drop (or break) their microformats support (e.g. Upcoming.org, Facebook) because web authors sometimes rewrite all their class names, and either are unaware that microformats were in the page, or couldn't easily distinguish microformats property class names from other site-specific class names.

This issue has been reported by a number of web authors:
* [http://html5doctor.com/microformats/#comment-10241 Wim's comment on HTML5Doctor] "Authors use classes like 'url' or 'region' all the time ... All sorts of markup might look like a microformat."
* ...

There has also been an anecdotal report of a design firm who was not (yet) familiar with microformats seeing the "extra" classes that "that don't seem to be used" (without corresponding CSS rules) and asking if they "can remove them". By making microformats class names different from generic words, authors unfamiliar with microformats may at least notice such distinction and infer special functionality accordingly.

Thus microformats 2 uses ''prefixes'' for property class names, e.g.:
* '''p-summary''' instead of ''summary''
* '''u-photo''' instead of ''photo''
* '''dt-updated''' instead of ''updated''

Such prefixing of all microformats class names was first suggested by Scott Isaacs of Microsoft to Tantek on a visit to Microsoft sometime in 2006/2007, but specifically aimed at making microformats easier to parse. At the time the suggestion was rejected since microformats were focused on web authors rather than parsers.

However, since experience has shown that distinguishing property class names is an issue for '''both web authors and parser developers''', this is a key change that microformats 2 is adopting. See the next section for details.

=== existing microformats parsing requirements ===
A non-trivial number of parser and tools developers have been sufficiently frustrated with some general issues with microformats that they've done the significant extra work to support very different and less friendly alternatives (microdata, RDFa). Based on this real-world data (market behavior), it behooves us to address these general issues with microformats for this constituency.

COMMUNITY and TOOLS (that) USE MICROFORMATS
* parser / parsing
* structured
* getting the data out
* json - 1:1 mapping

[[parsing]] microformats currently requires
# a list of root class names of each microformat to be parsed
# a list of properties for each specific microformats, along with knowledge of the type of each property in order to parse their data from potentially different portions of the HTML markup
# some number of format-specific specific rules (markup/content optimizations)

This has meant that whenever a new microformat is drafted/specificied/adopted, parsers need to updated to handle it correctly, at a minimum to parse them when inside other microformats and avoid errantly implying properties from one to the other (containment, [[mfo]] problem).

== microformats 2 prefixes ==
=== naming conventions for generic parsing ===
There is a fairly simple solution to #1 and #2 from the above list, and we can make progress towards minimizing #3. In short:

'''Proposal: a set of naming conventions for microformat root class names and properties that make it obvious when:'''
* a class name represents a microformat root class name
* a class name represents a microformat property name
* a class name represents a microformat property that needs special parsing (specific type of property).

In particular - derived from the real world examples of existing proven microformats (rather than any abstraction of what a schema should have)
* '''"h-*" for root class names''', e.g. "h-card", "h-event", "h-entry"
** The 'h-' prefix is based on the existing microformats naming pattern of starting with 'h'.
* '''"p-*" for simple (text) properties''', e.g. "p-fn", "p-summary"
** vocabulary generic parsing, element text in general, treat certain HTML element/attribute combination as special and use those first, e.g. img/alt, abbr/title.
** The 'p-' prefix is based on the word "property" starting with 'p'.
* '''"u-*" for URL properties''', e.g. "u-url", "u-photo", "u-logo"
** special parsing required: prefer a/href, img/src, object/data etc. attributes to element contents.
** The 'u-' prefix is based on URL/URI starting with the letter 'u', which is the type of most of these related properties.
* '''"dt-*" for datetime properties''', e.g. "dt-start", "dt-end", "dt-bday"
** special parsing required: [[value-class-pattern]], in particular separate date time value parsing for better human readabillity / DRY balance.
** The 'dt-' prefix is based on "date time" having the initials "dt" and the preponderance of existing date time properties starting with "dt", e.g. dtstart, dtend, dtstamp, dtreviewed.
*** Initially I had proposed "dt-*" but Chris Messina suggested reducing it to "d-*" so that all prefixes were a single letter - made sense.
*** However, I've noticed that Google+ is using "d-*" class names on [https://plus.google.com/109182513536739786206 profile pages], thus we can't really use 'd-' as a microformats 2 property parsing prefix. [[User:Tantek|Tantek]] 03:00, 22 July 2011 (UTC)
*** Frankly I also think this provides a simpler transition/education story for existing microformats authors/publishers: "h*" to "h-*", "dt*" to "dt-*", url type properties to "u-*", and "p-*" for all others.

See [[microformats-2-prefixes]] for further thoughts and discussions on these and other class prefixes.

==== prefixes for future consideration ====
possibly also:
* '''"e-*" for properties''' where the entire contained element hierarchy is the value, e.g. "e-content" (formerly "entry-content") for [[hAtom]].
** unclear if this is necessary in general. and if so, if this is only for hAtom, that's insufficient to justify putting it in the generic syntax.
** Would be sufficient to have all <code>p-</code> properties parse the complete content, including any nested mark-up if present, and then implementations to sanitize/run a <code>strip_tags</code> style function (as per data input best practice) as appropriate. --[[User:BenWard|BenWard]] 22:05, 19 September 2011 (UTC)
* '''"i-*" for ID properties''', e.g. "i-uid" (if this is the only one, then perhaps we just always re-use "uid" or collapse with "u-*" into "u-id".)
** parsing is no different than "u-*" parsing, thus no need to introduce for now.
* '''"n-*" for numbers''', e.g. "n-rating", "n-geo", where the numbers may have different human-readable-friendly and decimal/machine values (e.g. with geo lat/long degrees minutes seconds vs decimal).
** requires definition of how would different parsing work before worthy of consideration.
* '''"t-*" for time duration''', e.g. "t-duration" in [[hCalendar]], [[hAudio]], [[hRecipe]] (note also Google's hRecipe extensions "preptime", "cooktime", "totaltime")
** requires definition of how would different parsing work before worthy of consideration.

==== reserving other prefixes ====
We should '''reserve all other single-letter-dash prefixes for future use.'''

In practice we have seen little (if any) use of single-letter-dash prefixing of class names by web developers/designers, and thus in practice we think this will have little if any impact/collisions. Certainly far fewer than existing generic microformat property class names like "title", "note", "summary".

==== existing single letter class prefixes ====
We should document existing usage of single/double letter prefixed names:
** Google+ (e.g. [https://plus.google.com/109182513536739786206 profile page], others) uses:
*** '''a-'''
*** '''d-'''
*** '''g-''', '''gb*'''
** Yahoo
*** '''y-'''
** others? please add alphabetical by company/org name.

== microformats 2 example ==
Example: taking that simple heading hCard example forward:

<source lang=html4strict>
<h1 class="h-card">Chris Messina</h1>
</source>

As part of microformats 2.0 we would immediately define root class names and property names for all existing microformats and drafts consistent with this naming convention, and require support thereof from all new implementations, as well as strongly encouraging existing implementations to adopt the simplified microformats 2.0 syntax and mechanism. Question: which microformats deserve explicit backward compatibility?

As a community we would continue to use the microformats [[process]] both for researching and determining the need for new microformats, and for naming new microformat property names for maximum re-use and interoperability of a shared vocabulary.

If it turns out we need a new property type in the future, we can use one of the remaining single-letter-prefixes to add it to microformats 2.0. This would require updating of parsers of course, but in practice the number of different types of properties has grown very slowly, and we know from other schema/programming languages that there's always some small limited number of scalar/atomic property types that you need, and using those you can create compound types/objects that represent richer / more complicated types of data.

=== ADVANTAGES ===
This has numerous advantages:
* '''better maintainability''' - much more obvious to web authors/designers/publishers which class names are for/from microformats.
* '''no chance of collision''' - for all practical purposes with existing class names and thus avoiding any need to add more complex CSS style rules to prevent unintended styling effects.
* '''simpler parsing''' - parsers can now do a simple stream-parse (or in-order DOM tree walk) and parse out '''all''' microformat objects, properties, and values, without having to know anything about any specific microformats.
* '''separation of syntax and vocabulary''' - by abstracting microformats 2 syntax independent of any vocabulary, it allows and encourages development of shared vocabularies that can work in alternative syntaxes.

More examples: here is that same heading example with name components:

<source lang=html4strict>
<h1 class="h-card">
<span class="p-fn">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</span>
</h1>
</source>

with a hyperlink to Chris's URL:

<source lang=html4strict>
<h1 class="h-card">
<a class="p-fn u-url" href="http://factoryjoe.com/">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</a>
</h1>
</source>

=== COMPATIBILITY ===

microformats 2.0 is backwards compatible in that in permits content authors to markup with both old and new class names for compatibility with old tools.

Here is a simple example:

<source lang=html4strict>
<h1 class="h-card vcard">
<span class="fn">Chris Messina</span>
</h1>
</source>

a microformats 2.0 parser would see the class name "h-card" and imply the one required property from the contents, while a microformats 1.0 parser would find the class name "vcard" and then look for the class name "fn". no data duplication is required. this is a very important continuing application of the <abbr title="don't repeat yourself">DRY</abbr> [[principle]].

And the above hyperlinked example with both sets of class names:

<source lang=html4strict>
<h1 class="h-card vcard">
<a class="p-fn u-url n fn url" href="http://factoryjoe.com/">
<span class="p-given-name given-name">Chris</span>
<abbr class="p-additional-name additional-name">R.</abbr>
<span class="p-family-name family-name">Messina</span>
</a>
</h1>
</source>

== vendor extensions ==
(this section was only discussed verbally and not written up during discussions - capturing here as it is topical)

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties has in recent years allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

There have been times when specific sites have wanted to extend microformats beyond what the set of properties in the microformat, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

'''Proposal:'''
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension OR
** OR "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-)
** e.g.
** "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "onering" microformat root class name.
** "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)
** "p-x-prep-time" - a possible experimental property name to be added to hRecipe upon consideration/documentation of real-world usage/uptake.

Background - this proposal is a composition of the following (at least somewhat) successful vendor extension syntaxes
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

== issues ==
=== Hungarian prefixing issues ===
Raised by [[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)

Microformats 2.0 proposes using an explicit <code>[a-z]-</code> prefix on properties, to differentiate them from other uses of the class attribute, and identify them as microformat properties, such that they can be parsed generically.

* The differentiation use case is supported by anecdotal evidence of sites (such as Facebook, Twitter, Yahoo) removing microformats or breaking objects in page edits. The addition of a prefix assists self-documentation of code.
* The generic parsing use case is supported by Google Rich Snippets, Yahoo Search Monkey, and extensible plugins like Operator and the Firefox microformats parser. Although these extract microformats from the page, they are intermediate systems between the page content and the actual interpretation of the data. They need to parse all objects from a page, and then another developer or application will interpret some of them into something else.

(Note: the theoretical assertion "they need to parse all objects from a page" is not actually backed by *any* existing use of microformats/microdata/RDFa parsing - *none* of those parse "all objects from a page" if you consider every markup element an "object" - rather, one of the strength of microformats (mimicked by the others) is that the publisher is able to markup *just* the data to be extracted, rather than perhaps purely "presentational" content, ads, UI widgets etc. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )

The µf2 proposal goes further, though, into a small vocabulary of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian] prefixes of properties based on data type. This increases the level of understanding required to read microformats, and reduces the benefit of all microformat properties having a consistent identifying prefix.

(Debatable assertion:"increases the level of understanding required to read microformats" - how? In microformats 2.0, authors/developers know that any single-letter-and-hyphen prefixed class name is for microformats 2.0, in contrast to today - developers have consistently given feedback that's hard to tell which generic class names (other than h* names) are microformat related and which are not. As for specific prefixes, "h-*" is special and follows the pattern of existing microformats. p = generic (p)roperty, and the other prefixes have trivial mnemonics as well, d for (d)atetimes etc. (so far, hopefully we can keep that up). -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )

Hungarian notation itself is controversial amongst programmers.
Plenty find it uglifies their code, can be a cause of confusion (especially when very-short prefixes are used, or esoteric types, or where the declared set of types differs from the available types in other programming languages.) Others support its benefits to type identification.

(Programmers are not the priority here, rather, designers/authors/publishers are. We design microformats for them first as they're the common use case, and we should avoid making statements that seem to imply any priority for the aesthetic preferences of programmers. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC))

Critically, however, there is no clear indication that either of the above use cases requires types to be strongly identified.

<div class="discussion">
* For identifying µf in pages, a differentiator is required from regular classnames. There is no evidence of further requirement to differentiate between properties beyond their name (and existing criticisms of Hungarian notation suggest it can harm understandability.)
** There is such evidence, and perhaps thus this would be a good FAQ topic. The derivation is quite simple - it comes directly from minimally affecting existing markup, and maximally using existing semantic information. Example of special purpose parsing, URL-like properties use the value of the 'href' (or equivalent) attribute because that's where that data already is in pages. Similarly with dates and datetimes - special parsing rules for that data type have permitted us to design the [[value-class-pattern]] to take advantage of specially parsing date and time separation. By re-using data *where publishers already put it, including attributes vs inline* we minimize the risk of data drift. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
** Additionally, this special type-specific parsing of microformats properties conveys microformats advantages of markup brevity that other syntaxes lack. E.g. you can convey *multiple* properties and values from a single existing element, e.g. the *very* common real-world pattern <code><br/><nowiki><a href="http://example.com/user">User Name</a></nowiki><br/></code> is minimally marked up as <code><br/><nowiki><span class="h-card"><a class="p-name u-url" href="http://example.com/user">User Name</a></span></nowiki><br/></code>
* For generic parsing, there is no requirement that datatypes be established at extraction time. Data types will instead be applied by the developers of apps and widgets that build on the generic parsers.
** There are requirements based on experience with actual markup. In order to support the patterns of where content publishers put the data we want to extract, we have determined (based on those publishing patterns) a few different ways (types) of parsing this data. This is all captured in the [[hcard-parsing]] property-specific parsing rules each of which were added one at a time as Brian Suda and myself encountered real world sites wanting to use [[hCard]] but not wanting to have to rewrite their markup (adding one span and some class names was about the limit, moving tags/attributes around was a showstopper in many/most cases), and each of the microformats 2.0 "types" are directly derived from such special purpose data/type parsing across *multiple* microformats. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
* A counter argument may be that special properties in microformats—such as URLs, or images—need to be identified because in microformats it is common to parse an attribute (href, or src) rather than inner text of an element for these properties. However, in the context of extracting and then interpreting HTML in other contexts this is insufficient: For example, though an image only exists as a single property in vcard, in HTML it is both a URL to a resource ''and'' and text string (alt) representing an accessible fallback. A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context. Likewise, an application interpreting a URL may also consider using the original inner text as an inferred label. Both pieces of data are useful, and a generic parser should not discard elemental semantics at the extraction level.
** It's not just "*common* to parse an attribute rather than inner text of an element for these properties" - it is the vast overwhelming majority - if not all - such cases!
** One misconception: "image only exists as a single property". No, there is both 'photo' and 'logo'. The 'url' and 'sound' properties are also of type 'url'. For all of these, when parsing an "object" element, you must use the 'data' attribute first for example. hCalendar has "attachment" as well. Etc.
** Theoretical assertion: "A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context." Why? There is no existing nor demonstrated use case for this requirement, even across other formats. While I agree it "might be nice" to develop a new "structured image" type - that's brand new work (deserving of research per the [[process]] etc.), and not a good source of reasoning to reject existing working patterns. I reject blocking microformats 2.0 on an as-yet-to-be-researched-enhancement. This is certainly a case where "better" is an enemy of the good.
** Theoretical assertion: "a generic parser should not discard elemental semantics at the extraction level" - already does for other syntaxes like both microdata and RDFa - so clearly this is not a reasonable "should not" assertion (and thus unnecessary) for development of a minimally competitive syntax. RDFa kind of cheats by overloading the 'rel' attribute in attempt to solve the name+url case as mentioned above, but that's only two types - and existing real world use of microformats has demonstrated utility of a few more. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
</div>

Given this, hungarian prefixes are of no benefit to parsers (and may in fact harm applications down the chain if parsing is prematurely strict.) It would be sufficient then not to concern embedding data types in property names, and instead settle on one single property prefix to differentiate all properties consistently. This would reduce the prefixes to just 3:

* <code>h</code> would indicates a root class name. An ‘object in HTML’.
* <code>p</code> would indicates a property within an object.
* <code>x</code> would indicates an experimental extension to an object.

--[[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)

The primary benefit of type-specific parsing is *not* for parsers, but rather, publishers (who we still hold in higher priority than parsers).

I will also note that *each* of the type-specific parsing methods in [[hcard-parsing]] was added both conservatively, reluctantly, and only when it became clear that such type-specific publishing patterns existing across *multiple* sites that would otherwise be unable to change their markup to work with microformats (Yes, I'm wishing now that I better documented exactly *which* sites, precisely *when*, but like many startups, early on we didn't exactly know how much to document vs get things done - frankly I think we documented far more than any other comparable such efforts, e.g. we managed to at least capture/grow both an explicit [[process]] and [[principles]] in *far* greater detail than anything remotely comparable either before microformats or since!). The type-specific parsing features are certainly not overdesigned, on the contrary they've *slowly* evolved, adapting to real world data on the web.

While per the [[simplicity]] principle, I would actually *strongly* prefer to only have the three prefixes given above, or actually just *two* (I started with just two for the design of microformats 2.0 actually, just "h-*" and "p-*"), doing so would be a step *backwards* in terms of the adaptability of microformats to existing markup, and that's IMHO an unacceptable barrier, and a sufficiently high barrier to hurt the adoption/applicability of microformats 2.0.

(Aside: In addition, note that you still need h-x-* for experimental objects, and thus it's *simpler* to simply have *both* h-x-* and p-x-* rather than add x-*. Alternatively x-h-* and x-p-* is no better, in some ways worse, in that object vs. property is a more important distinction for parsers than established vs experimental, especially if/when an experimental property (or object) may be adopted. Also, mild precdent: PNG started with image/x-png, not x-image/png.).

To put it in a positive way, type-specific parsing conveys microformats a publisher-markup-density (and re-use) advantage which neither microdata nor RDFa have, and it would behoove us to *keep* this significant real-world advantage as we evolve microformats.

-- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)

== see also ==
* [[microformats-2]]
* [[microformats-2-brainstorming]]
* [[microformats-2-prefixes]]
* [[microformats-2-faq]]

microformats2

2011-04-11T01:16:54Z

BenWard: /* VENDOR EXTENSIONS */ Added new section against Hungarian notation, proposes reduced number of prefixes (3) for generic extraction and class usage differentiation only.

2004: In early February microformats were introduced as a concept at eTech, and in September [[hCard]] and [[hCalendar]] were proposed at FOO Camp.

2010:
* 34% of webdevs use microformats ([http://www.webdirections.org/sotw10/markup/#semantics 2010 State of Web Development survey])
* 1.88 billion hCards (per [[Yahoo]] SearchMonkey)
* 36 million hCalendar events (ibid)

* XFN -> Social Graph API -> Web as Social Network / Address Book

=== AUTHORS and PUBLISHING ===

'''How can we make it easier for authors to publish microformats?'''

Currently the simplest hCard:
<source lang=html4strict>
<span class="vcard">
<span class="fn">
Chris Messina
</span>
</span>
</source>

requires 2 elements (nested, with perhaps at least one being pre-existing), and 2 class names

Web authors/designers are used to the simplicity of most HTML tags, e.g. to mark up a heading:

<source lang=html4strict>
<h1>Chris Messina</h1>
</source>

requires just 1 element.

'''How can we make microformats just as easy?'''

'''Proposal: allow root class name only.'''

This would enable:

<source lang=html4strict>
<h1 class="vcard">Chris Messina</h1>
</source>

requiring only 1 class name for the simplest case.

'''Can we do even better?'''

One of the most common questions asked about hCard is:

[[hcard-faq#Why_does_hCard_use_vcard_as_the_root_class_name|Why does hCard use vcard as the root class name?]]

This slight inconsistency between the name of the format and the name of the root class name consistently causes confusion in a large percentage of newcomers to microformats.
* Looks like a typo (just one letter difference)
* Ambiguity in discussions, e.g. put "vcard" in your HTML - meaning, class name, or a link to a .vcf file?
* Extra bit to remember when marking up a microformat
** in contrast to [[hReview]], [[hListing]], [[hRecipe]], etc. which all have root class name same as name of microformat (lowercased).

Though in microformats we believe very strongly in the [[principle]] of [[reuse]], we have to admit that in this case experience/evidence has shown that this may be a case where we re-used something too far beyond it's original meaning. Thus:

'''Proposal: use root class name "hcard" instead of "vcard" for future hCards.'''

This would result in:

<source lang=html4strict>
<h1 class="hcard">Chris Messina</h1>
</source>

making the simple case even simpler:

Just 1 additional class name, named the same as the format you're adding. Think hCard, markup class="hcard".

It's very important for the simple case to be as simple as possible, to enable the maximum number of people to get started with minimum effort.

From there on, it's ok to require incremental effort for incremental return.

E.g. to add any addition information about a person, add explicit property names.

'''How does this simple root-only case work?'''

* root class name reflects name of the microformat
* every microformat must require at most 1 property (preferably 0)
** admit that requiring a field in an application just results in noise (the 90210 problem - apps which require zip code get lots of false 90210 entries), and specify that any application use cases which appear to "require" specific properties must instead define how to imply sensible defaults for them.
* when only a root class name is specified, imply the entire text contents of the element as the value of the primary property of the microformat. e.g.
** "hcard" implies "fn"
** hcalendar event - "hevent" - implies "summary"
** "hreview" implies "summary"
** "hentry" implies "entry-summary" (perhaps collapse into "summary" - in practice they're not sufficiently semantically distinct to require separate property names)

==== Additional simplifications ====

'''What more can we simplify about microformats?'''

Numerous individuals have provided the feedback that whenever there is more than one level of hierarchy in a microformat, many (most?) developers get confused - in particular Kavi Goel of Google / Rich Snippets provided this feedback at a microformats dinner. Thus depending on multiple levels of hierarchy is likely resulting in a loss of authorability, perhaps even accuracy as confusion undoubtedly leads to more errors. Thus:

'''Proposal: simplify all microformats to flat sets of properties. '''

What this means:
* all microformats are simply an object with a set of properties with values.
* no more subproperties- drop the notion of subproperties.
* use composition of multiple microformats for any further hierarchy, e.g. the "location" of an hCalendar even can be an hCard, or the "agent" of one hCard can be another hCard.

For example for hCard this would mean the following specific changes to keep relevant functionality:
* drop "n", promote all "n" subproperties to full properties
** given-name, family-name, additional-name, honorific-prefix, honorific-suffix
* treat "geo" as a nested microformat
* treat "adr" as a nested microformat (what to do about adr's "type"?)
* treat "org" as a flat string and drop "organization-name" and "organization-unit" (in practice rarely used, also not revealed or ignored in contact management user interfaces - e.g. Address Book)

Example: add a middle initial to the previous example Chris Messina's name, and markup each name component:

<source lang=html4strict>
<h1 class="hcard">
<span class="fn">
<span class="given-name">Chris</span>
<abbr class="additional-name">R.</abbr>
<span class="family-name">Messina</span>
</span>
</h1>
</source>

Note:
# use of an explicit span with "fn" to markup his entire formatted name
# use of the abbr element to explicitly indicate the semantic that "R." is merely an abbreviation for his additional-name.

=== COMMUNITY and TOOLS ===
(that) USE MICROFORMATS
* parser / parsing
* structured
* getting the data out
* json - 1:1 mapping

[[parsing]] microformats currently requires
# a list of root class names of each microformat to be parsed
# a list of properties for each specific microformats, along with knowledge of the type of each property in order to parse their data from potentially different portions of the HTML markup
# some number of format-specific specific rules (markup/content optimizations)

This has meant that whenever a new microformat is drafted/specificied/adopted, parsers need to updated to handle it correctly, at a minimum to parse them when inside other microformats and avoid errantly implying properties from one to the other (containment, [[mfo]] problem).

I think there is a fairly simple solution to #1 and #2 from the above list, and we can make progress towards minimizing #3. In short:

'''Proposal: a set of naming conventions for microformat root class names and properties that make it obvious when:'''
* a class name represents a microformat root class name
* a class name represents a microformat property name
* a class name represents a specific type of microformats property

In particular - derived from the real world examples of existing proven microformats (rather than any abstraction of what a schema should have)
* '''"h-*" for root class names''', e.g. "h-card", "h-event", "h-entry"
* '''"p-*" for simple (text) properties''', e.g. "p-fn", "p-summary"
* '''"u-*" for URL properties''', e.g. "u-url", "u-photo", "u-logo"
* '''"d-*" for datetime properties''', e.g. "d-start", "d-end", "d-bday" (initially I had proposed "dt-*" but Chris Messina suggested reducing it to "d-*" so that all prefixes were a single letter - made sense).
* '''"n-*" for (one or more) numbers''', e.g. "n-rating", "n-geo", leaving the semantics of more than one number up to specific format. e.g. for an "n-rating" inside an "h-review", the first number would presumably be the rating value, when only two numbers the second would be the "best" value (e.g. rated <code><span class="n-rating">3 out of 4</span></code>), when three numbers the second would be the "worst" and the third would be the "best" (e.g. <code><span class="n-rating">7.5 out of 1 to 10</span></code>). similarly "n-geo" would specify the first number to be the latitude and the second to be the longitude.
possibly also:
* '''"e-*" for properties''' where the entire contained element hierarchy is the value, e.g. "e-content" (formerly "entry-content") for [[hAtom]].
* '''"i-*" for ID properties''', e.g. "i-uid" (if this is the only one, then perhaps we just always re-use "uid" or collapse with "u-*" into "u-id".)
* '''"t-*" for time duration''', e.g. "t-duration" in [[hCalendar]], [[hAudio]], [[hRecipe]] (note also Google's hRecipe extensions "preptime", "cooktime", "totaltime")
and:
* '''reserve all other single-letter-dash prefixes for future use.''' In practice we have seen very little (if any) use of single-letter-dash prefixing of class names by web developers/designers, and thus in practice we think this will have little if any impact/collisions. Certainly far fewer than existing generic microformat property class names like "title", "note", "summary".

Example: taking that simple heading hCard example forward:

<source lang=html4strict>
<h1 class="h-card">Chris Messina</h1>
</source>

As part of microformats 2.0 we would immediately define root class names and property names for all existing microformats and drafts consistent with this naming convention, and require support thereof from all new implementations, as well as strongly encouraging existing implementations to adopt the simplified microformats 2.0 syntax and mechanism.

As a community we would continue to use the microformats [[process]] both for researching and determining the need for new microformats, and for naming new microformat property names for maximum re-use and interoperability of a shared vocabulary.

If it turns out we need a new property type in the future, we can use one of the remaining single-letter-prefixes to add it to microformats 2.0. This would require updating of parsers of course, but in practice the number of different types of properties has grown very slowly, and we know from other schema/programming languages that there's always some small limited number of scalar/atomic property types that you need, and using those you can create compound types/objects that represent richer / more complicated types of data.

==== ADVANTAGES ====
This has numerous advantages:
* '''better maintainability''' - much more obvious to web authors/designers/publishers which class names are for/from microformats.
* '''no chance of collision''' - for all practical purposes with existing class names and thus avoiding any need to add more complex CSS style rules to prevent unintended styling effects.
* '''simple universal parsing''' - parsers can now do a simple stream-parse (or in-order DOM tree walk) and parse out '''all''' microformat objects, properties, and values, without having to know anything about any specific microformats.

More examples: here is that same heading example with name components:

<source lang=html4strict>
<h1 class="h-card">
<span class="p-fn">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</span>
</h1>
</source>

with a hyperlink to Chris's URL:

<source lang=html4strict>
<h1 class="h-card">
<a class="p-fn u-url" href="http://factoryjoe.com/">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</a>
</h1>
</source>

==== COMPATIBILITY ====

microformats 2.0 is backwards compatible in that in permits content authors to markup with both old and new class names for compatibility with old tools.

Here is a simple example:

<source lang=html4strict>
<h1 class="h-card vcard">
<span class="fn">Chris Messina</span>
</h1>
</source>

a microformats 2.0 parser would see the class name "h-card" and imply the one required property from the contents, while a microformats 1.0 parser would find the class name "vcard" and then look for the class name "fn". no data duplication is required. this is a very important continuing application of the <abbr title="don't repeat yourself">DRY</abbr> [[principle]].

And the above hyperlinked example with both sets of class names:

<source lang=html4strict>
<h1 class="h-card vcard">
<a class="p-fn u-url n fn url" href="http://factoryjoe.com/">
<span class="p-given-name given-name">Chris</span>
<abbr class="p-additional-name additional-name">R.</abbr>
<span class="p-family-name family-name">Messina</span>
</a>
</h1>
</source>

==== VENDOR EXTENSIONS ====

(this section was only discussed verbally and not written up during discussions - capturing here as it is topical)

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties has in recent years allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

There have been times when specific sites have wanted to extend microformats beyond what the set of properties in the microformat, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

'''Proposal:'''
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension OR
** OR "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-)
** e.g.
** "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "onering" microformat root class name.
** "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)
** "p-x-prep-time" - a possible experimental property name to be added to hRecipe upon consideration/documentation of real-world usage/uptake.

Background - this proposal is a composition of the following (at least somewhat) successful vendor extension syntaxes
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)

==== FURTHER THOUGHTS REGARDING HUNGARIAN PREFIXING ====

Microformats 2.0 proposes using an explicit <code>[a-z]-</code> prefix on properties, to differentiate them from other uses of the class attribute, and identify them as microformat properties, such that they can be parsed generically.

* The differentiation use case is supported by anecdotal evidence of sites (such as Facebook, Twitter, Yahoo) removing microformats or breaking objects in page edits. The addition of a prefix assists self-documentation of code.
* The generic parsing use case is supported by Google Rich Snippets, Yahoo Search Monkey, and extensible plugins like Operator and the Firefox microformats parser. Although these extract microformats from the page, they are intermediate systems between the page content and the actual interpretation of the data. They need to parse all objects from a page, and then another developer or application will interpret some of them into something else.

The µf2 proposal goes further, though, into a small vocabulary of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian] prefixes of properties based on data type. This increases the level of understanding required to read microformats, and reduces the benefit of all microformat properties having a consistent identifying prefix.

Hungarian notation itself is controversial amongst programmers. Plenty find it uglifies their code, can be a cause of confusion (especially when very-short prefixes are used, or esoteric types, or where the declared set of types differs from the available types in other programming languages.) Others support its benefits to type identification.

Critically, however, there is no clear indication that either of the above use cases requires types to be strongly identified.

* For identifying µf in pages, a differentiator is required from regular classnames. There is no evidence of further requirement to differentiate between properties beyond their name (and existing criticisms of Hungarian notation suggest it can harm understandability.)
* For generic parsing, there is no requirement that datatypes be established at extraction time. Data types will instead be applied by the developers of apps and widgets that build on the generic parsers.
* A counter argument may be that special properties in microformats—such as URLs, or images—need to be identified because in microformats it is common to parse an attribute (href, or src) rather than inner text of an element for these properties. However, in the context of extracting and then interpreting HTML in other contexts this is insufficient: For example, though an image only exists as a single property in vcard, in HTML it is both a URL to a resource ''and'' and text string (alt) representing an accessible fallback. A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context. Likewise, an application interpreting a URL may also consider using the original inner text as an inferred label. Both pieces of data are useful, and a generic parser should not discard elemental semantics at the extraction level.

Given this, hungarian prefixes are of no benefit to parsers (and may in fact harm applications down the chain if parsing is prematurely strict.) It would be sufficient then not to concern embedding data types in property names, and instead settle on one single property prefix to differentiate all properties consistently. This would reduce the prefixes to just 3:

* <code>h</code> would indicates a root class name. An ‘object in HTML’.
* <code>p</code> would indicates a property within an object.
* <code>x</code> would indicates an experimental extension to an object.

--[[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)

=== USERS ===
Need more tools and interfaces that:
* publish
* copy/paste
* right-click on a microformat
* share
* search results

discussed some existing like: [[H2VX]] converts hCard to vCard, hCalendar to iCalendar

how would we re-implement Live Clipboard today, making it easier for publishers and developers?

events/2011-03-sxsw

2011-02-04T22:14:56Z

BenWard: /* Subjects to Cover */ New round of contributions from BenWard

<entry-title>South By Southwest Interactive 2011</entry-title>

Microformats events, content and so forth at SXSWi.

==The Future of Microformats Panel==

Featuring:

* Frances Berriman
* Ben Ward
* Tantek Çelik
* Paul Tarjan

=== 140 Character Summary for SXSW documentation===

What is the future of structured data on the web? A look at new implementations, tools and hacks, plus updates on the microformats project.

=== Social media hashtag ===

hashtag: #futuremf

===Brainstorming the Panel===

Figure out the direction, content and general flow of the panel.

====Subjects to Cover====

<div class="discussion">
* Summarize the state of Microformats
** “Are microformats dead?” (not necessarily in those terms…)
*** I'm curious about the self-consciousness behind this question. Is it an actual concern? One you have heard? Or just an ironic opener? [[User:Tantek|Tantek]] 19:28, 30 January 2011 (UTC)
**** I've had it asked of me repeatedly, for a while now. The blog is neglected, there've been no new formats promoted (which is an external impression of progress), none of us work actively on it, supposedly stable specs like hAtom remain at sub-1.0 versions, the mailing lists are deserted. It is an entirely legitimate impression that the effort has folded into irrelevance. — [[User:BenWard|BenWard]] 22:14, 4 February 2011 (UTC)
**** I've genuinely been asked if HTML 5 (various new elements) / Microdata replace microformats [[User:Phae|Phae]] 14:21, 31 January 2011 (UTC)
***** If the context is one of comparison, then let's handle that in comparison discussions (see below). - [[User:Tantek|Tantek]] 23:35, 31 January 2011 (UTC)
** Major implementations (to date)
*** Show an overview slide with logos of all the sites publishing microformats
*** Google search results - screenshots of rich snippets
*** [[RelMeAuth]]
**** There's no way this can be framed as a ‘major implementation’. It's a brilliant experiment, a great proof of concept. It's not a major implementation. Given Glenn's new hacks too, maybe we need to break this into two sections; actual major implementations and then hot new experiments that demonstrate how the data which is now out there and stable can be used. — [[User:BenWard|BenWard]] 22:14, 4 February 2011 (UTC)
*** Could demonstrate Twitter Tweet Button using <code>rel=me</code> to infer data from embedding pages.
**** It's a tiny small use, but it is also all over the web. Not worth much time, but a nice frame of the concept of using microformats for progressive enhancement. — [[User:BenWard|BenWard]] 22:14, 4 February 2011 (UTC)
*** Glenn Jones has a few neat things too
**** Possibly demo each very quickly? Glenn was asking about doing a demo too.
** What microformats are there which are stable, ‘complete’?
*** This might be a good time to discuss potential thoughts about more formally defined microformats spec stages, e.g. draft (brainstorm consensus, ready for publishers), specification (stable multiple publisher support, implementations recommended), standard (multiple interoperable implementations) - I've brainstormed this a bit with Kevin Marks, perhaps worth further discussion at a dinner and capturing on its own wiki page).
* Cover structured data in general (perhaps briefly, just to clear up confusion)
** do a slide comparing microformats, microdata, RDFa (when you use it, which vocabs in use) - I think this might be a good lead in for the "Microformats 2.0" introduction.
** What's microdata? What's it for? Where is it supported?
** RDFa: Depending on further checking of the figures cited in Peter Mika's blog post (http://tripletalk.wordpress.com/2011/01/25/rdfa-deployment-across-the-web), what vocabularies are emerging in the RDFa space?
*** If the figures are wrong though, or there aren't any major vocabularies, then can probably skip over this. — Ben
**** Yeah, I'm a little tired of the deceptive marketing by the RDFa crowd (that article, and Ben's and Kevin Marks' trivial critiques (c.f. their twitters) are a prime example) and frankly in such a short session we shouldn't give such deceptions any time. However I *would* suggest a backup slide to debunk it (e.g. showing adoption of the class attribute or meta keyword in comparison to RDFa) when the inevitable one RDFa question comes up from the one RDFa person in the crowd. [[User:Tantek|Tantek]]
**** We check the figures and if they are actually backed by a growth in particular vocabularies using RDFa, we mention them because they are relevant to structured data on the web. — [[User:BenWard|BenWard]] 22:14, 4 February 2011 (UTC)
* What's happening this year?
** Any new vocabularies expected to be stable?
** vCard 4.0, and how that will tie into hCard
*** updates to hCard in general hCard 1.0.1, 1.1 - [[User:Tantek|Tantek]]
** HTML5, and how the time element affects hCalendar, hAtom, etc.
*** Good to mention X2V/H2VX update to support HTML5 and time/datetime here. - [[User:Tantek|Tantek]]
** “Microformats 2” (datatype prefixes, generic tree parsing.)
*** If this is mentioned at all, assuming Tantek is even continuing this work at all(?), I am firmly of the view that it needs to framed as an exploration around a use case, not an accepted progression of microformats as a whole. — Ben
**** Yes it is continuing :) I agree with the general thinking behind Ben's framing, that is, we need to stay practical. Direct use cases are one subset of real world problems (which is how microformats started) that microformats solve. What's driving Microformats 2.0 *is* the solving of specific real world problems that sufficient developers have encountered (i.e. not just hypothetical) that it's now finally worth spending the time to solve them. And yes, the goal would be to have Microformats 2.0 "ready to use/parse" for introduction at this session, possibly with some publisher/parser support already available (thinking Twitter, Facebook, X2V, Operator offhand). - [[User:Tantek|Tantek]]
***** I don't see how it's feasible to take ‘Microformats 2’ from its current rough draft documentation, without consensus, into a deployed and consumable state in the space of a month. Especially given how slowly and sporadically things move here. — [[User:BenWard|BenWard]] 22:14, 4 February 2011 (UTC)
***** Additionally (and, I should stress, unrelated to my personal scepticism of the µf2 proposal) there's no way Twitter will be able to ship anything related to it before SXSW.
** If we're covering individually led efforts though, Ben would like to frame up the concept of rich data containers and expanding parsing rules for those (<code>vcalendar</code> TV listings and the like.)
*** You know the drill, start an exploration wiki page on the subject :) - [[User:Tantek|Tantek]]
**** That's existed for a while actually: [[container-brainstorming]]
* Community Management? Being that this has been (is?) one of the larger challenges the microformats community has had, is it worth bringing up, lessons learned etc.?
** It's been on my mind a lot recently - particularly the reduction of traffic to mailing lists and potential stagnation of some proposals. I think we've got a tricky balance to strike. [[User:Phae|Phae]] 14:33, 31 January 2011 (UTC)
*** I think what essentially happened, to be blunt, is that the trolls "won". We had a sufficient # of trolls who overwhelmed the cognitive surplus of the admins (and the rest of the community, none of which were experienced with community management), that people (including myself) lost a lot of motivation and daily participation, IRC, etc. dropped off. I've been thinking a lot about this lately, and I think we actually have an opportunity to fix this, that is, to set up much stricter (and upfront) participation guidelines and consequences, and then act swiftly, and fairly merciless to ban those that are even minimally disruptive, because frankly, we don't have the staff to deal with educating (i.e. teaching better online manners etc.) those who are either new, immature, or just obsessive (i.e. can't help themselves from sending repeated emails to the lists, they're welcome to get such training on W3C lists where there are paid staff to deal with such folks). At that point, we can re-engage editors to step up activity, and then as admins very vigilantly patrol the lists and keep the clear of trolls. I would rather have higher quality traffic from a few productive folks, than noise from drive-by emailers. We need to act more like a meritocratic, hierarchical open source project (e.g. Mozilla) than the semi-free-for-all perceived flat "democracy" that so many standards lists (e.g. W3C) have. - [[User:Tantek|Tantek]] 23:35, 31 January 2011 (UTC)
*** I think it's a bit much to pin all of this on trolls at this point. We banned them, they went away. After that—which was multiple years ago, remember—no one has done any major spec or community work with any visibility. There hasn't been any activity to draw people in or stimulate interest. We need to avoid playing some sort of excuses game here and focus on positive future effort, reasons why people should consider participating — [[User:BenWard|BenWard]] 22:14, 4 February 2011 (UTC)
*** Relatedly, hNews might count as a valid effort which did have activity around it, but which was hosted around a different place than microformats.org — [[User:BenWard|BenWard]] 22:14, 4 February 2011 (UTC)
* Accessibility? Since the value-class-pattern has solved these problems, is this worth mentioning at all?
** May be worth a mention, if only because I think the date-pattern debacle put a few souls off. [[User:Phae|Phae]] 14:33, 31 January 2011 (UTC)
*** Phae, that was 2 years ago - literally - we covered accessibility and the [[value-class-pattern]] at the SXSW 2009 session. What's left to do is debunk the out-of-date Wikipedia article on microformats and any other place the debate resurfaces. Not sure why it would be worth spending time on this at SXSW 2011 except in response to Q&A perhaps. - [[User:Tantek|Tantek]] 23:35, 31 January 2011 (UTC)
**** Fair enough, just thinking out loud :) [[User:Phae|Phae]]
**** We don't even need to do that concerning dates. At this point it's sufficient just to show HTML5 time elements in action. It may be reasonable at this point to consider updating all the specs to use time in the examples rather than old forms. — [[User:BenWard|BenWard]] 22:14, 4 February 2011 (UTC)
</div>

====Subjects not to cover at all====
* meta keywords
* microdata on its own
* RDFa on its own
* ontology/ontologies (lose most the crowd just by mentioning the word)
* why invisible metadata fails (perhaps backup slides for Q&A response only)

events/2011-03-sxsw

2011-01-30T10:14:45Z

BenWard: Started the brainstorm page.

social-network-anti-patterns

2010-07-19T20:45:38Z

BenWard: /* Facebook see if more friends have joined */

<entry-title>Social Network Anti-patterns</entry-title>
{{TOC-right}}

While [[social-network-portability]] documents what to do to put your site on the open social web and be a good user-centric service in general, it's been noted that not everyone follows such advice and instead opts for a bunch of alternative either one-off (wasteful) or downright user-unfriendly tactics. This page documents such [[anti-patterns]] of social network design and implementation and provides (unfortunately) real world examples of such badly designed sites.

== Spam your contacts ==
Many social networking sites ask you to <span id="Upload_your_Address_Book">upload your address book</span>, or "Find Your Friends", when what the feature really does is '''Spam your contacts'''.

These sites seem to use your uploading of an address book as tacit/implied permission to spam all your friends with invites, which will annoy your friends, and make you look foolish.
* [http://twitter.com/spiller2/statuses/811960394 Stephen Spillane apologized on 2008-05-15] to his friends for what sounds like involuntary spamming due to a social network invite: <blockquote><p>"apologies to anyone who got an annoying invite from me to some stupid social network. The things men make me do"</p></blockquote>

Making users annoy, look dumb to their friends, and feel compelled to apologize is not good design.

This spamming behavior is now so bad, that users are creating new email accounts to knowingly avoid the problem:
* [http://twitter.com/lisamac/statuses/239777272 Lisa McMillan on Twitter 2007-08-31] <blockquote><p>"getting a special email account with no contacts for signing up to social networks. Then, I won't mind when they hijack my address book."</p></blockquote>

Apparently this contact spam has in at least one case taken the form of instant-message spam (spim) which is then used to spread a contact-based virus!

* [http://twitter.com/theinfonaut/status/1246859290 Leslie Chicoine on Twitter 2009-02-24] <blockquote><p>There's a contacts based virus going around, don't give your IM, Yahoo, Google Contacts etc. info to any website!</p></blockquote>

Solution: support [[social-network-portability]] instead, not address book spamming.

Read more about why this is an anti-pattern:
* 2007-12-19 [http://factoryjoe.com/blog/2007/12/19/public-nuisance-1-importing-your-contacts/ Chris Messina: Public nuisance #1: Importing your contacts]

Here are some sites that are currently doing this:

=== Bebo invites===
Bebo appears to have a user interface that makes it too easy for users to unintentionally spam everyone in their address book.

Evidence that users have unintentionally sending invite spam to their contacts:

As [http://twitter.com/walelia/statuses/771302864 noted by user Valerie Noble on 2008-03-13]: <blockquote><p>"What the hell, I stupidly sent bebo invites to eveyone in my address book. Boo!"</p></blockquote>

and [http://twitter.com/cksthree/statuses/773542421 user C.K. Sample III on 2008-03-18]: <blockquote><p>"signed up for bebo. sorry to everyone in my address book who got spammed by the sign up. I thought it would work more like twitter"</p></blockquote>

Evidence that users are receiving Bebo invite spam:

[http://twitter.com/frankensite/statuses/774020094 Brian Alvey notes on 2008-03-19]: <blockquote><p>"Considering deleting the duplicate Bebo invitations I'm getting. Everyone has 3+ addresses for me. Another address book spam engine. Hurray!"</p></blockquote>

Still a problem as of May 2008:

[http://twitter.com/cmpayne/statuses/811938598 Cameron Payne was unpleasantly surprised on 2008-05-15]: <blockquote><p>"goddamn Bebo just invited *everyone* in my Yahoo address book. I don't think I told it to do that. WTF!? Beware!"</p></blockquote>

=== Goodreads are your friends already on ===
Goodreads also has a user interface that misleads even very web-savvy users into unintentionally spamming everyone in their address book.

[http://flickr.com/photos/redcarpet/2619408018/in/photostream/ http://farm4.static.flickr.com/3114/2619408018_25c0147054.jpg]

[http://www.mickipedia.com/ Micki Krimmell] wrote both [http://www.mickipedia.com/?p=1174 a blog post] and a [http://getsatisfaction.com/goodreads/topics/why_did_goodreads_trick_me_into_spamming_my_entire_address_book post on GetSatisfaction] describing her experience with being tricked into spamming all her friends.

A representative from Goodreads has followed up on both Micki's blog post and Getsatisfaction post, however, as far as is known, Goodreads' user interface has not been changed/improved accordingly to be less misleading.

=== Quechup find your friends on ===
[http://www.flickr.com/photos/chrishambly/1302362704/ http://farm2.static.flickr.com/1339/1302362704_63d97a8930.jpg]

Quechup has a feature to "find your friends" which, even if it says "no contact present" will spam all your contacts in your address book and thus annoy all your friends and embarrass you. Clearly it is not just ''finding your friends from'' your address book, it is ''inviting everyone in'' your address book.
* 2007-07-31 [http://www.ibert.be/2007/07/quechup-disaster.html BERT VAN WASSENHOVE: Quechup disaster]
* 2007-09-02 [http://www.chrishambly.com/content/quechup-and-mass-hysteria Chris Hambly: Quechup And Mass Hysteria]
* 2007-09-02 [http://mashable.com/2007/09/02/quechup/ Mashable: Are You Getting Quechup Spammed?]
* 2007-09-05 [http://www.brianoberkirch.com/2007/09/05/should-google-help-us-stop-quechup-spam/ Brian Oberkirch: should google help us stop quechup spam?]

=== Spock scan my address book ===
* 2007-12-17 [http://beth.typepad.com/beths_blog/2007/12/beware-of-spock.html Beth Kanter: Beware of Spock is not Star Trek 2.0 .... Beware]

== Enter your other site login and password ==
Also known as:
* "<span id="Enter_your_email_login_and_password">Enter your email login and password</span>" anti-pattern.
* Third Party Password Antipattern ([http://flickr.com/photos/tags/3ppantipattern 3ppantipattern], tppantipattern)
* Password Antipattern

Giving any site your login credentials/permissions for another site or service is a <strong>very bad idea.</strong> You cannot trust that the site will treat your login credentials with proper care (e.g. Quechup uses this antipattern to implement the [[#Spam_your_contacts|spam everyone your the address book antipattern above]]).

It is also very bad user interface design. These sites that ask for your login (whether gmail or other services) are teaching users a very bad habit, a habit that is akin to what phishing sites depend on. Essentially you are teaching a user that this type of form is safe whereas it actually presents quite the danger given the number of phishing sites out there.

Don't ask users for their login and password to another site like gMail etc.

Solution:
* drop import support for the sites that don't offer hCard+XFN friends lists and/or [[OAuth]].
** Note that last.fm dropped support for their password anti-pattern support in the recent (2008 June) redesign!
* support [[social-network-portability]].
* and if you must, support site-specific proprietary APIs which depend on OAuth, e.g. Google Address Book API, Yahoo Address Book API.

=== Posts ===
Read more about why this is an anti-pattern:
* 2007-08-14 [http://www.brianoberkirch.com/2007/08/14/two-social-system-design-trends-that-should-really-really-stop-like-now/ Brian Oberkirch: Two social system design trends that should really, really stop. like now.]
* 2007-10-11 [http://adactio.com/journal/1357 Jeremy Keith: The password anti-pattern]
* 2008-01-04 [http://www.brianoberkirch.com/2008/01/04/this-antipattern-is-kryptonite-to-the-open-social-web/ Brian Oberkirch: this antipattern is kryptonite to the open social web]
* 2008-03-15 [http://adactio.com/journal/1421/ Jeremy Keith: Anti-pattern begone] (mentions Google announcement of their Contacts Data API)
* 2008-06-04 [http://adactio.com/journal/1475/ Jeremy Keith: Making contact] (mentions the Yahoo announcement of the release of their Address Book API).
* 2008-07-15 [http://getsatisfaction.com/pownce/topics/why_does_pownce_keep_killing_kittens_with_the_password_anti_pattern Jeremy Keith: Why does Pownce keep killing kittens with the password anti-pattern?]
* 2008-09-23 [http://pownce.com/adactio/notes/3571554/ Jeremy Keith pownces Either the password anti-pattern goes or I do.]
* 2008-09-25 [http://adactio.com/journal/1513/ Jeremy Keith: Anti-pattern recognition]

=== Excuses and responses===
* Some major players are not helping the cause.
** Just because someone/something else big is misbehaving, that is no excuse for you to do so.
* We are following pretty common practice.
** Just because many other folks are misbehaving, that is no excuse for you to.
* Variant: We are implementing the same code as Facebook and Twitter so we went for best practices.
** Implementing the same code is not best practice. Implementing the same code in this case is the lowest common denominator.
* We aren't in a terribly strong position to drop support.
** Of course you are! Precisely because you *are* small. You have less to lose.
** If you pick a public fight with a misbehaving big player over this, guess who wins? If the press covers it as little guy vs the big guy etc. narrative.
* Our growth is flat!
** Exactly - this won't affect it. But maybe a little positive publicity will help.
* We could implement the OAuth-based proprietary address book APIs, but we'd have to invest the development time to do Facebook, Yahoo, and Google.
** Disable the the password anti-pattern code in the meantime.
* The pragmatic downside is that our growth is stagnant, we need to do features that'll benefit us, and this isn't at the top of the list of features that can do that for us.
** This is the opportunity cost argument. It is the same problem with fixing polluting factories vs. building new factories.
* Why are people threatening to leave us or worse?
** Without community pressure/embarrassment, companies don't change.
* I think we've earned a little benefit of the doubt that we're not 'the industry'.
** Having a "polluting" interface that is on every day means no benefit of the doubt.

==== Pollution analogy ====
The password anti-pattern = teaching people to pollute themselves.
* Just because everyone else pollutes, doesn't mean it makes it right for you to do so.
* Polluting factories need to be fixed just as much as new factories need to be built.
* Without environmentalist pressure/embarrassment, polluting companies don't change.
* Why not focus your efforts on the huuuuuuge polluters like instead of my small company?
** Because easier to apply enough pressure to get smaller guys to change first. Same tactics worked for environmentalists. Then they would use smaller victories to earn bigger victories, until they had racked up enough victories to make the big guys look *really* bad.

Here are some sites that are currently doing this:

=== Blipfm is better with friends ===
[http://www.flickr.com/photos/tantek/3199489045/ http://farm4.static.flickr.com/3389/3199489045_7169ea1a63.jpg]

'''[http://blip.fm Blip.fm]''' - Their "Import Address Book" functionality requests that you enter your username and password for your email provider(s): yahoo, gmail, hotmail, aol, msn.

=== Facebook Connect ===
Per [http://micro.ben-ward.co.uk/post/65425363/facebook-connect Ben Ward's post on Facebook Connect], this user interface:

[http://micro.ben-ward.co.uk/post/65425363/facebook-connect http://5.media.tumblr.com/5vUVOHNMPhm1sj7138AlwQXho1_400.png]

Appears to encourage users to enter their email address and password into something visually resembling (but easy to mimic) a Facebook popup window on ''any'' site.

Thus all a malicious site would have to do is put up a button saying "Login with Facebook Connect", then display an identically styled virtual popup, and the user, who has been taught by the Facebook Connect UI, will simply enter their email address and password.

There's also a more detailed follow up on Ben's views of the Facebook Connect UI [http://ben-ward.co.uk/blog/oauth-flow/ on his blog] — and complements for the alternate version, whereby it uses the iframe to improve the UX for users who are ''already logged in'' to Facebook. There's a bit more snark as well, for those who are into that.

Update: This issue was '''fixed''' by Facebook. They now use a separate pop-up window, complete with browser chrome, to log in when you're not already signed in to Facebook.

=== Facebook see if more friends have joined ===
[http://flickr.com/photos/factoryjoe/2110461562/ http://farm3.static.flickr.com/2324/2110461562_e624ab4175.jpg]

[http://blog.benward.me/post/825760204 http://28.media.tumblr.com/tumblr_l5qcn44Rxg1qzt3x8o1_500.png]

'''[http://facebook.com Facebook]''' - Their "see if more friends have joined Facebook" feature provides you with a popup menu to enter passwords for numerous sites.

=== GetSatisfaction Twitter This widget ===
As [http://twitter.com/adactio/status/1020708247 reported by Jeremy Keith], apparently the [http://getsatisfaction.com GetSatisfaction] "Twitter This" widget requests your Twitter username and password. <strong>(screenshot needed)</strong>

See the support thread on GetSatisfaction "[http://getsatisfaction.com/getsatisfaction/topics/stop_asking_for_twitter_passwords Stop asking for Twitter passwords]" for more.

=== Nsyght import your profile and friends ===
[http://www.flickr.com/photos/tantek/2254537667/ http://farm3.static.flickr.com/2035/2254537667_d831c1fb3a.jpg]

'''[http://nsyght.com Nsyght]''' - Register for an account to import from Digg, Pownce, Last.fm, and Twitter (site is in public alpha)
* Unfortunately the "import from Digg, Pownce, Last.fm, and Twitter" feature depends on entering your username and password to those sites, which is ironic since those sites support microformats and [[social-network-portability]]!

=== Plaxo - Let's look for your friends in your address book ===
[http://www.flickr.com/photos/manveru/3215481930/ http://farm4.static.flickr.com/3088/3215481930_979c0a7f61.jpg]

'''[http://plaxo.com plaxo]''' - Asks in several forms for passwords of different mail services.

=== Plinky - Find Your Friends ===
[http://www.flickr.com/photos/tantek/3218629483/ http://farm4.static.flickr.com/3335/3218629483_e40019cac9.jpg]

'''[http://plinky.com Plinky]''''s "Find Your Friends" feature, which it presents to every newly signed up user, asks for your email address and password for a variety of services.

As [http://twitter.com/dewitt/status/1145448221 DeWitt tweeted]: <blockquote><p>Google, Yahoo, and Microsoft all support browser-based delegated authorization apis for contacts. Plinky should use those apis.</p></blockquote>

See also [http://friendfeed.com/e/6ff1f9ce-df01-4250-05de-c7009f31925f/Wow-Plinky-usernames-are-going-faster-than/ this thread by Jason Shellen (CEO of Plinky)] who says some hopeful things: <blockquote><p>DeWitt - You make a good point. I'll discuss it with the team Monday. In other news, we do support OAuth for posting to Blogger.</p></blockquote>

=== Quechup which friends already use ===
[http://mashable.com/2007/09/02/quechup/ http://mashable.com/wp-content/uploads/2007/09/quechupsignup.PNG]

=== ShareThis import your contact lists ===
[http://flickr.com/photos/factoryjoe/1344414673/ http://farm2.static.flickr.com/1088/1344414673_8e306e265d_o.png]
[http://flickr.com/photos/factoryjoe/1345315346/ http://farm2.static.flickr.com/1143/1345315346_8eb2cf4d7c_o.png]

ShareThis asks for your username and password to email services and social network sites.

=== SlideShare signup form ===
As [http://twitter.com/adactio/status/1020670561 reported by Jeremy Keith], apparently the [http://www.slideshare.net/signup SlideShare signup form] asks for your (in this order)
* Username
* Email Address
* Password
* Confirm Password
<strong>(screenshot needed)</strong>

Because of the proximity of "Email Address" and "Password" input fields it is easy to mistake this for asking for your email address and email password. Perhaps it is asking for your email password? Or perhaps it asks for that later in the process? Screenshots would help.

See the GetSatisfaction support thread "[http://getsatisfaction.com/slideshare/topics/asking_for_3rd_party_passwords Asking for 3rd party passwords]" for more.

=== StockTwits login ===
[http://www.flickr.com/photos/factoryjoe/3061262427/ http://farm4.static.flickr.com/3010/3061262427_3775189375.jpg]

StockTwits.com asks you to "Login" with your Twitter username and password. StockTwits is not run by Twitter, therefore they are asking you for your username and password to another site.

=== Twitpic login to twitter ===
[http://flickr.com/photos/ronin691/2368324013/ http://farm3.static.flickr.com/2166/2368324013_0a15d337c0.jpg]

Twitpic asks you to enter your Twitter username and password. They are not the same site, nor are they run by the same people or company.

=== Twitter are your friends on ===
[http://www.flickr.com/photos/ronin691/2110909518/ http://farm3.static.flickr.com/2179/2110909518_fde956c2ee.jpg]

'''[http://twitter.com/ Twitter]''' is a service that many users (including many of us active with microformats) love and adore and use constantly. Plus they implement microformats (e.g. [[hcard supporting user profiles]] and [[hcard xfn supporting friends lists]])!

However, we still need to call them out for supporting the third-party password anti-pattern.

As co-authors of [[Oauth]], please Twitter, implement and evangelize that path (perhaps even on that "are your friends on" page), rather than this anti-pattern.

=== TwitterNotes ===
[http://flickr.com/photos/guspim/2138354357/ http://farm3.static.flickr.com/2221/2138354357_0c566fd62e.jpg]

'''[http://twitternotes.com/ TwitterNotes]''' asks you to "login with your Twitter account" username and password. They are not the same site, nor are they run by the same people or company.

== Join to fix your profile ==
Some social network sites create public profiles for you without you having any contact with them. If there are any mistakes, they make you join in order to fix them. This sounds like blackmail: Join our service or else we'll continue to publish inaccurate information about you and therefore spam websearch results about you with misinformation.

=== Spock join to fix ===
* 2007-08-15 [http://www.wired.com/techbiz/startups/news/2007/08/spock_reputation Wired News: Astonishing! Spock Thinks You're a Pedophile]
* 2007-12-16 [http://www.fullcirc.com/wp/2007/12/16/please-dont-invite-me-to-spock/ Full Circle Associates: Please, don’t invite me to Spock]
* 2007-12-16 [http://ourfounder.typepad.com/leblog/2007/12/it-may-be-the-e.html Jim Benson: It May Be the Evil Spock] (and [http://ourfounder.typepad.com/leblog/2007/12/an-initial-resp.html An Initial Response to Spock])

== One Unified Social Network ==
Several companies are trying to build the "one unified social network" (to rule them all) where they own/control the social network, and you're "allowed to" build applications on top of their proprietary platform. The most recent example of this is perhaps [http://facebook.com/ Facebook].

This is a bad idea for the same reason you don't see "one universal blogging service".

Other examples of folks walking down this path:
* [http://hcii.cmu.edu/M-HCI/2006/SocialstreamProject/index.php Socialstream] - a [http://google.com/ Google] sponsored project at CMU. Key quote: "a unified social network that, as a service, provides social data to many other applications". See also references in this Forbes article: [http://www.forbes.com/technology/2007/08/28/google-brazil-network-tech-cx_ag_0828orkut.html Google's Secret Society].
* ...

The hope is that these services will see the potential upside of providing open user profiles and social networks through [[social network portability]] and thus enable syndication of such data, as popular blogging services do.

== related ==
* [[social-network-portability]]
* [[anti-patterns]]

social-network-anti-patterns

2010-07-19T20:44:06Z

BenWard: /* Facebook see if more friends have joined */ Added new Facebook password antipattern friend finder UI

<entry-title>Social Network Anti-patterns</entry-title>
{{TOC-right}}

While [[social-network-portability]] documents what to do to put your site on the open social web and be a good user-centric service in general, it's been noted that not everyone follows such advice and instead opts for a bunch of alternative either one-off (wasteful) or downright user-unfriendly tactics. This page documents such [[anti-patterns]] of social network design and implementation and provides (unfortunately) real world examples of such badly designed sites.

== Spam your contacts ==
Many social networking sites ask you to <span id="Upload_your_Address_Book">upload your address book</span>, or "Find Your Friends", when what the feature really does is '''Spam your contacts'''.

These sites seem to use your uploading of an address book as tacit/implied permission to spam all your friends with invites, which will annoy your friends, and make you look foolish.
* [http://twitter.com/spiller2/statuses/811960394 Stephen Spillane apologized on 2008-05-15] to his friends for what sounds like involuntary spamming due to a social network invite: <blockquote><p>"apologies to anyone who got an annoying invite from me to some stupid social network. The things men make me do"</p></blockquote>

Making users annoy, look dumb to their friends, and feel compelled to apologize is not good design.

This spamming behavior is now so bad, that users are creating new email accounts to knowingly avoid the problem:
* [http://twitter.com/lisamac/statuses/239777272 Lisa McMillan on Twitter 2007-08-31] <blockquote><p>"getting a special email account with no contacts for signing up to social networks. Then, I won't mind when they hijack my address book."</p></blockquote>

Apparently this contact spam has in at least one case taken the form of instant-message spam (spim) which is then used to spread a contact-based virus!

* [http://twitter.com/theinfonaut/status/1246859290 Leslie Chicoine on Twitter 2009-02-24] <blockquote><p>There's a contacts based virus going around, don't give your IM, Yahoo, Google Contacts etc. info to any website!</p></blockquote>

Solution: support [[social-network-portability]] instead, not address book spamming.

Read more about why this is an anti-pattern:
* 2007-12-19 [http://factoryjoe.com/blog/2007/12/19/public-nuisance-1-importing-your-contacts/ Chris Messina: Public nuisance #1: Importing your contacts]

Here are some sites that are currently doing this:

=== Bebo invites===
Bebo appears to have a user interface that makes it too easy for users to unintentionally spam everyone in their address book.

Evidence that users have unintentionally sending invite spam to their contacts:

As [http://twitter.com/walelia/statuses/771302864 noted by user Valerie Noble on 2008-03-13]: <blockquote><p>"What the hell, I stupidly sent bebo invites to eveyone in my address book. Boo!"</p></blockquote>

and [http://twitter.com/cksthree/statuses/773542421 user C.K. Sample III on 2008-03-18]: <blockquote><p>"signed up for bebo. sorry to everyone in my address book who got spammed by the sign up. I thought it would work more like twitter"</p></blockquote>

Evidence that users are receiving Bebo invite spam:

[http://twitter.com/frankensite/statuses/774020094 Brian Alvey notes on 2008-03-19]: <blockquote><p>"Considering deleting the duplicate Bebo invitations I'm getting. Everyone has 3+ addresses for me. Another address book spam engine. Hurray!"</p></blockquote>

Still a problem as of May 2008:

[http://twitter.com/cmpayne/statuses/811938598 Cameron Payne was unpleasantly surprised on 2008-05-15]: <blockquote><p>"goddamn Bebo just invited *everyone* in my Yahoo address book. I don't think I told it to do that. WTF!? Beware!"</p></blockquote>

=== Goodreads are your friends already on ===
Goodreads also has a user interface that misleads even very web-savvy users into unintentionally spamming everyone in their address book.

[http://flickr.com/photos/redcarpet/2619408018/in/photostream/ http://farm4.static.flickr.com/3114/2619408018_25c0147054.jpg]

[http://www.mickipedia.com/ Micki Krimmell] wrote both [http://www.mickipedia.com/?p=1174 a blog post] and a [http://getsatisfaction.com/goodreads/topics/why_did_goodreads_trick_me_into_spamming_my_entire_address_book post on GetSatisfaction] describing her experience with being tricked into spamming all her friends.

A representative from Goodreads has followed up on both Micki's blog post and Getsatisfaction post, however, as far as is known, Goodreads' user interface has not been changed/improved accordingly to be less misleading.

=== Quechup find your friends on ===
[http://www.flickr.com/photos/chrishambly/1302362704/ http://farm2.static.flickr.com/1339/1302362704_63d97a8930.jpg]

Quechup has a feature to "find your friends" which, even if it says "no contact present" will spam all your contacts in your address book and thus annoy all your friends and embarrass you. Clearly it is not just ''finding your friends from'' your address book, it is ''inviting everyone in'' your address book.
* 2007-07-31 [http://www.ibert.be/2007/07/quechup-disaster.html BERT VAN WASSENHOVE: Quechup disaster]
* 2007-09-02 [http://www.chrishambly.com/content/quechup-and-mass-hysteria Chris Hambly: Quechup And Mass Hysteria]
* 2007-09-02 [http://mashable.com/2007/09/02/quechup/ Mashable: Are You Getting Quechup Spammed?]
* 2007-09-05 [http://www.brianoberkirch.com/2007/09/05/should-google-help-us-stop-quechup-spam/ Brian Oberkirch: should google help us stop quechup spam?]

=== Spock scan my address book ===
* 2007-12-17 [http://beth.typepad.com/beths_blog/2007/12/beware-of-spock.html Beth Kanter: Beware of Spock is not Star Trek 2.0 .... Beware]

== Enter your other site login and password ==
Also known as:
* "<span id="Enter_your_email_login_and_password">Enter your email login and password</span>" anti-pattern.
* Third Party Password Antipattern ([http://flickr.com/photos/tags/3ppantipattern 3ppantipattern], tppantipattern)
* Password Antipattern

Giving any site your login credentials/permissions for another site or service is a <strong>very bad idea.</strong> You cannot trust that the site will treat your login credentials with proper care (e.g. Quechup uses this antipattern to implement the [[#Spam_your_contacts|spam everyone your the address book antipattern above]]).

It is also very bad user interface design. These sites that ask for your login (whether gmail or other services) are teaching users a very bad habit, a habit that is akin to what phishing sites depend on. Essentially you are teaching a user that this type of form is safe whereas it actually presents quite the danger given the number of phishing sites out there.

Don't ask users for their login and password to another site like gMail etc.

Solution:
* drop import support for the sites that don't offer hCard+XFN friends lists and/or [[OAuth]].
** Note that last.fm dropped support for their password anti-pattern support in the recent (2008 June) redesign!
* support [[social-network-portability]].
* and if you must, support site-specific proprietary APIs which depend on OAuth, e.g. Google Address Book API, Yahoo Address Book API.

=== Posts ===
Read more about why this is an anti-pattern:
* 2007-08-14 [http://www.brianoberkirch.com/2007/08/14/two-social-system-design-trends-that-should-really-really-stop-like-now/ Brian Oberkirch: Two social system design trends that should really, really stop. like now.]
* 2007-10-11 [http://adactio.com/journal/1357 Jeremy Keith: The password anti-pattern]
* 2008-01-04 [http://www.brianoberkirch.com/2008/01/04/this-antipattern-is-kryptonite-to-the-open-social-web/ Brian Oberkirch: this antipattern is kryptonite to the open social web]
* 2008-03-15 [http://adactio.com/journal/1421/ Jeremy Keith: Anti-pattern begone] (mentions Google announcement of their Contacts Data API)
* 2008-06-04 [http://adactio.com/journal/1475/ Jeremy Keith: Making contact] (mentions the Yahoo announcement of the release of their Address Book API).
* 2008-07-15 [http://getsatisfaction.com/pownce/topics/why_does_pownce_keep_killing_kittens_with_the_password_anti_pattern Jeremy Keith: Why does Pownce keep killing kittens with the password anti-pattern?]
* 2008-09-23 [http://pownce.com/adactio/notes/3571554/ Jeremy Keith pownces Either the password anti-pattern goes or I do.]
* 2008-09-25 [http://adactio.com/journal/1513/ Jeremy Keith: Anti-pattern recognition]

=== Excuses and responses===
* Some major players are not helping the cause.
** Just because someone/something else big is misbehaving, that is no excuse for you to do so.
* We are following pretty common practice.
** Just because many other folks are misbehaving, that is no excuse for you to.
* Variant: We are implementing the same code as Facebook and Twitter so we went for best practices.
** Implementing the same code is not best practice. Implementing the same code in this case is the lowest common denominator.
* We aren't in a terribly strong position to drop support.
** Of course you are! Precisely because you *are* small. You have less to lose.
** If you pick a public fight with a misbehaving big player over this, guess who wins? If the press covers it as little guy vs the big guy etc. narrative.
* Our growth is flat!
** Exactly - this won't affect it. But maybe a little positive publicity will help.
* We could implement the OAuth-based proprietary address book APIs, but we'd have to invest the development time to do Facebook, Yahoo, and Google.
** Disable the the password anti-pattern code in the meantime.
* The pragmatic downside is that our growth is stagnant, we need to do features that'll benefit us, and this isn't at the top of the list of features that can do that for us.
** This is the opportunity cost argument. It is the same problem with fixing polluting factories vs. building new factories.
* Why are people threatening to leave us or worse?
** Without community pressure/embarrassment, companies don't change.
* I think we've earned a little benefit of the doubt that we're not 'the industry'.
** Having a "polluting" interface that is on every day means no benefit of the doubt.

==== Pollution analogy ====
The password anti-pattern = teaching people to pollute themselves.
* Just because everyone else pollutes, doesn't mean it makes it right for you to do so.
* Polluting factories need to be fixed just as much as new factories need to be built.
* Without environmentalist pressure/embarrassment, polluting companies don't change.
* Why not focus your efforts on the huuuuuuge polluters like instead of my small company?
** Because easier to apply enough pressure to get smaller guys to change first. Same tactics worked for environmentalists. Then they would use smaller victories to earn bigger victories, until they had racked up enough victories to make the big guys look *really* bad.

Here are some sites that are currently doing this:

=== Blipfm is better with friends ===
[http://www.flickr.com/photos/tantek/3199489045/ http://farm4.static.flickr.com/3389/3199489045_7169ea1a63.jpg]

'''[http://blip.fm Blip.fm]''' - Their "Import Address Book" functionality requests that you enter your username and password for your email provider(s): yahoo, gmail, hotmail, aol, msn.

=== Facebook Connect ===
Per [http://micro.ben-ward.co.uk/post/65425363/facebook-connect Ben Ward's post on Facebook Connect], this user interface:

[http://micro.ben-ward.co.uk/post/65425363/facebook-connect http://5.media.tumblr.com/5vUVOHNMPhm1sj7138AlwQXho1_400.png]

Appears to encourage users to enter their email address and password into something visually resembling (but easy to mimic) a Facebook popup window on ''any'' site.

Thus all a malicious site would have to do is put up a button saying "Login with Facebook Connect", then display an identically styled virtual popup, and the user, who has been taught by the Facebook Connect UI, will simply enter their email address and password.

There's also a more detailed follow up on Ben's views of the Facebook Connect UI [http://ben-ward.co.uk/blog/oauth-flow/ on his blog] — and complements for the alternate version, whereby it uses the iframe to improve the UX for users who are ''already logged in'' to Facebook. There's a bit more snark as well, for those who are into that.

Update: This issue was '''fixed''' by Facebook. They now use a separate pop-up window, complete with browser chrome, to log in when you're not already signed in to Facebook.

=== Facebook see if more friends have joined ===
[http://flickr.com/photos/factoryjoe/2110461562/ http://farm3.static.flickr.com/2324/2110461562_e624ab4175.jpg]

[http://28.media.tumblr.com/tumblr_l5qcn44Rxg1qzt3x8o1_500.png]

'''[http://facebook.com Facebook]''' - Their "see if more friends have joined Facebook" feature provides you with a popup menu to enter passwords for numerous sites.

=== GetSatisfaction Twitter This widget ===
As [http://twitter.com/adactio/status/1020708247 reported by Jeremy Keith], apparently the [http://getsatisfaction.com GetSatisfaction] "Twitter This" widget requests your Twitter username and password. <strong>(screenshot needed)</strong>

See the support thread on GetSatisfaction "[http://getsatisfaction.com/getsatisfaction/topics/stop_asking_for_twitter_passwords Stop asking for Twitter passwords]" for more.

=== Nsyght import your profile and friends ===
[http://www.flickr.com/photos/tantek/2254537667/ http://farm3.static.flickr.com/2035/2254537667_d831c1fb3a.jpg]

'''[http://nsyght.com Nsyght]''' - Register for an account to import from Digg, Pownce, Last.fm, and Twitter (site is in public alpha)
* Unfortunately the "import from Digg, Pownce, Last.fm, and Twitter" feature depends on entering your username and password to those sites, which is ironic since those sites support microformats and [[social-network-portability]]!

=== Plaxo - Let's look for your friends in your address book ===
[http://www.flickr.com/photos/manveru/3215481930/ http://farm4.static.flickr.com/3088/3215481930_979c0a7f61.jpg]

'''[http://plaxo.com plaxo]''' - Asks in several forms for passwords of different mail services.

=== Plinky - Find Your Friends ===
[http://www.flickr.com/photos/tantek/3218629483/ http://farm4.static.flickr.com/3335/3218629483_e40019cac9.jpg]

'''[http://plinky.com Plinky]''''s "Find Your Friends" feature, which it presents to every newly signed up user, asks for your email address and password for a variety of services.

As [http://twitter.com/dewitt/status/1145448221 DeWitt tweeted]: <blockquote><p>Google, Yahoo, and Microsoft all support browser-based delegated authorization apis for contacts. Plinky should use those apis.</p></blockquote>

See also [http://friendfeed.com/e/6ff1f9ce-df01-4250-05de-c7009f31925f/Wow-Plinky-usernames-are-going-faster-than/ this thread by Jason Shellen (CEO of Plinky)] who says some hopeful things: <blockquote><p>DeWitt - You make a good point. I'll discuss it with the team Monday. In other news, we do support OAuth for posting to Blogger.</p></blockquote>

=== Quechup which friends already use ===
[http://mashable.com/2007/09/02/quechup/ http://mashable.com/wp-content/uploads/2007/09/quechupsignup.PNG]

=== ShareThis import your contact lists ===
[http://flickr.com/photos/factoryjoe/1344414673/ http://farm2.static.flickr.com/1088/1344414673_8e306e265d_o.png]
[http://flickr.com/photos/factoryjoe/1345315346/ http://farm2.static.flickr.com/1143/1345315346_8eb2cf4d7c_o.png]

ShareThis asks for your username and password to email services and social network sites.

=== SlideShare signup form ===
As [http://twitter.com/adactio/status/1020670561 reported by Jeremy Keith], apparently the [http://www.slideshare.net/signup SlideShare signup form] asks for your (in this order)
* Username
* Email Address
* Password
* Confirm Password
<strong>(screenshot needed)</strong>

Because of the proximity of "Email Address" and "Password" input fields it is easy to mistake this for asking for your email address and email password. Perhaps it is asking for your email password? Or perhaps it asks for that later in the process? Screenshots would help.

See the GetSatisfaction support thread "[http://getsatisfaction.com/slideshare/topics/asking_for_3rd_party_passwords Asking for 3rd party passwords]" for more.

=== StockTwits login ===
[http://www.flickr.com/photos/factoryjoe/3061262427/ http://farm4.static.flickr.com/3010/3061262427_3775189375.jpg]

StockTwits.com asks you to "Login" with your Twitter username and password. StockTwits is not run by Twitter, therefore they are asking you for your username and password to another site.

=== Twitpic login to twitter ===
[http://flickr.com/photos/ronin691/2368324013/ http://farm3.static.flickr.com/2166/2368324013_0a15d337c0.jpg]

Twitpic asks you to enter your Twitter username and password. They are not the same site, nor are they run by the same people or company.

=== Twitter are your friends on ===
[http://www.flickr.com/photos/ronin691/2110909518/ http://farm3.static.flickr.com/2179/2110909518_fde956c2ee.jpg]

'''[http://twitter.com/ Twitter]''' is a service that many users (including many of us active with microformats) love and adore and use constantly. Plus they implement microformats (e.g. [[hcard supporting user profiles]] and [[hcard xfn supporting friends lists]])!

However, we still need to call them out for supporting the third-party password anti-pattern.

As co-authors of [[Oauth]], please Twitter, implement and evangelize that path (perhaps even on that "are your friends on" page), rather than this anti-pattern.

=== TwitterNotes ===
[http://flickr.com/photos/guspim/2138354357/ http://farm3.static.flickr.com/2221/2138354357_0c566fd62e.jpg]

'''[http://twitternotes.com/ TwitterNotes]''' asks you to "login with your Twitter account" username and password. They are not the same site, nor are they run by the same people or company.

== Join to fix your profile ==
Some social network sites create public profiles for you without you having any contact with them. If there are any mistakes, they make you join in order to fix them. This sounds like blackmail: Join our service or else we'll continue to publish inaccurate information about you and therefore spam websearch results about you with misinformation.

=== Spock join to fix ===
* 2007-08-15 [http://www.wired.com/techbiz/startups/news/2007/08/spock_reputation Wired News: Astonishing! Spock Thinks You're a Pedophile]
* 2007-12-16 [http://www.fullcirc.com/wp/2007/12/16/please-dont-invite-me-to-spock/ Full Circle Associates: Please, don’t invite me to Spock]
* 2007-12-16 [http://ourfounder.typepad.com/leblog/2007/12/it-may-be-the-e.html Jim Benson: It May Be the Evil Spock] (and [http://ourfounder.typepad.com/leblog/2007/12/an-initial-resp.html An Initial Response to Spock])

== One Unified Social Network ==
Several companies are trying to build the "one unified social network" (to rule them all) where they own/control the social network, and you're "allowed to" build applications on top of their proprietary platform. The most recent example of this is perhaps [http://facebook.com/ Facebook].

This is a bad idea for the same reason you don't see "one universal blogging service".

Other examples of folks walking down this path:
* [http://hcii.cmu.edu/M-HCI/2006/SocialstreamProject/index.php Socialstream] - a [http://google.com/ Google] sponsored project at CMU. Key quote: "a unified social network that, as a service, provides social data to many other applications". See also references in this Forbes article: [http://www.forbes.com/technology/2007/08/28/google-brazil-network-tech-cx_ag_0828orkut.html Google's Secret Society].
* ...

The hope is that these services will see the potential upside of providing open user profiles and social networks through [[social network portability]] and thus enable syndication of such data, as popular blogging services do.

== related ==
* [[social-network-portability]]
* [[anti-patterns]]

social-network-anti-patterns

2010-07-19T20:42:47Z

BenWard: /* Facebook Connect */ Facebook have fixed Connect UI

<entry-title>Social Network Anti-patterns</entry-title>
{{TOC-right}}

While [[social-network-portability]] documents what to do to put your site on the open social web and be a good user-centric service in general, it's been noted that not everyone follows such advice and instead opts for a bunch of alternative either one-off (wasteful) or downright user-unfriendly tactics. This page documents such [[anti-patterns]] of social network design and implementation and provides (unfortunately) real world examples of such badly designed sites.

== Spam your contacts ==
Many social networking sites ask you to <span id="Upload_your_Address_Book">upload your address book</span>, or "Find Your Friends", when what the feature really does is '''Spam your contacts'''.

These sites seem to use your uploading of an address book as tacit/implied permission to spam all your friends with invites, which will annoy your friends, and make you look foolish.
* [http://twitter.com/spiller2/statuses/811960394 Stephen Spillane apologized on 2008-05-15] to his friends for what sounds like involuntary spamming due to a social network invite: <blockquote><p>"apologies to anyone who got an annoying invite from me to some stupid social network. The things men make me do"</p></blockquote>

Making users annoy, look dumb to their friends, and feel compelled to apologize is not good design.

This spamming behavior is now so bad, that users are creating new email accounts to knowingly avoid the problem:
* [http://twitter.com/lisamac/statuses/239777272 Lisa McMillan on Twitter 2007-08-31] <blockquote><p>"getting a special email account with no contacts for signing up to social networks. Then, I won't mind when they hijack my address book."</p></blockquote>

Apparently this contact spam has in at least one case taken the form of instant-message spam (spim) which is then used to spread a contact-based virus!

* [http://twitter.com/theinfonaut/status/1246859290 Leslie Chicoine on Twitter 2009-02-24] <blockquote><p>There's a contacts based virus going around, don't give your IM, Yahoo, Google Contacts etc. info to any website!</p></blockquote>

Solution: support [[social-network-portability]] instead, not address book spamming.

Read more about why this is an anti-pattern:
* 2007-12-19 [http://factoryjoe.com/blog/2007/12/19/public-nuisance-1-importing-your-contacts/ Chris Messina: Public nuisance #1: Importing your contacts]

Here are some sites that are currently doing this:

=== Bebo invites===
Bebo appears to have a user interface that makes it too easy for users to unintentionally spam everyone in their address book.

Evidence that users have unintentionally sending invite spam to their contacts:

As [http://twitter.com/walelia/statuses/771302864 noted by user Valerie Noble on 2008-03-13]: <blockquote><p>"What the hell, I stupidly sent bebo invites to eveyone in my address book. Boo!"</p></blockquote>

and [http://twitter.com/cksthree/statuses/773542421 user C.K. Sample III on 2008-03-18]: <blockquote><p>"signed up for bebo. sorry to everyone in my address book who got spammed by the sign up. I thought it would work more like twitter"</p></blockquote>

Evidence that users are receiving Bebo invite spam:

[http://twitter.com/frankensite/statuses/774020094 Brian Alvey notes on 2008-03-19]: <blockquote><p>"Considering deleting the duplicate Bebo invitations I'm getting. Everyone has 3+ addresses for me. Another address book spam engine. Hurray!"</p></blockquote>

Still a problem as of May 2008:

[http://twitter.com/cmpayne/statuses/811938598 Cameron Payne was unpleasantly surprised on 2008-05-15]: <blockquote><p>"goddamn Bebo just invited *everyone* in my Yahoo address book. I don't think I told it to do that. WTF!? Beware!"</p></blockquote>

=== Goodreads are your friends already on ===
Goodreads also has a user interface that misleads even very web-savvy users into unintentionally spamming everyone in their address book.

[http://flickr.com/photos/redcarpet/2619408018/in/photostream/ http://farm4.static.flickr.com/3114/2619408018_25c0147054.jpg]

[http://www.mickipedia.com/ Micki Krimmell] wrote both [http://www.mickipedia.com/?p=1174 a blog post] and a [http://getsatisfaction.com/goodreads/topics/why_did_goodreads_trick_me_into_spamming_my_entire_address_book post on GetSatisfaction] describing her experience with being tricked into spamming all her friends.

A representative from Goodreads has followed up on both Micki's blog post and Getsatisfaction post, however, as far as is known, Goodreads' user interface has not been changed/improved accordingly to be less misleading.

=== Quechup find your friends on ===
[http://www.flickr.com/photos/chrishambly/1302362704/ http://farm2.static.flickr.com/1339/1302362704_63d97a8930.jpg]

Quechup has a feature to "find your friends" which, even if it says "no contact present" will spam all your contacts in your address book and thus annoy all your friends and embarrass you. Clearly it is not just ''finding your friends from'' your address book, it is ''inviting everyone in'' your address book.
* 2007-07-31 [http://www.ibert.be/2007/07/quechup-disaster.html BERT VAN WASSENHOVE: Quechup disaster]
* 2007-09-02 [http://www.chrishambly.com/content/quechup-and-mass-hysteria Chris Hambly: Quechup And Mass Hysteria]
* 2007-09-02 [http://mashable.com/2007/09/02/quechup/ Mashable: Are You Getting Quechup Spammed?]
* 2007-09-05 [http://www.brianoberkirch.com/2007/09/05/should-google-help-us-stop-quechup-spam/ Brian Oberkirch: should google help us stop quechup spam?]

=== Spock scan my address book ===
* 2007-12-17 [http://beth.typepad.com/beths_blog/2007/12/beware-of-spock.html Beth Kanter: Beware of Spock is not Star Trek 2.0 .... Beware]

== Enter your other site login and password ==
Also known as:
* "<span id="Enter_your_email_login_and_password">Enter your email login and password</span>" anti-pattern.
* Third Party Password Antipattern ([http://flickr.com/photos/tags/3ppantipattern 3ppantipattern], tppantipattern)
* Password Antipattern

Giving any site your login credentials/permissions for another site or service is a <strong>very bad idea.</strong> You cannot trust that the site will treat your login credentials with proper care (e.g. Quechup uses this antipattern to implement the [[#Spam_your_contacts|spam everyone your the address book antipattern above]]).

It is also very bad user interface design. These sites that ask for your login (whether gmail or other services) are teaching users a very bad habit, a habit that is akin to what phishing sites depend on. Essentially you are teaching a user that this type of form is safe whereas it actually presents quite the danger given the number of phishing sites out there.

Don't ask users for their login and password to another site like gMail etc.

Solution:
* drop import support for the sites that don't offer hCard+XFN friends lists and/or [[OAuth]].
** Note that last.fm dropped support for their password anti-pattern support in the recent (2008 June) redesign!
* support [[social-network-portability]].
* and if you must, support site-specific proprietary APIs which depend on OAuth, e.g. Google Address Book API, Yahoo Address Book API.

=== Posts ===
Read more about why this is an anti-pattern:
* 2007-08-14 [http://www.brianoberkirch.com/2007/08/14/two-social-system-design-trends-that-should-really-really-stop-like-now/ Brian Oberkirch: Two social system design trends that should really, really stop. like now.]
* 2007-10-11 [http://adactio.com/journal/1357 Jeremy Keith: The password anti-pattern]
* 2008-01-04 [http://www.brianoberkirch.com/2008/01/04/this-antipattern-is-kryptonite-to-the-open-social-web/ Brian Oberkirch: this antipattern is kryptonite to the open social web]
* 2008-03-15 [http://adactio.com/journal/1421/ Jeremy Keith: Anti-pattern begone] (mentions Google announcement of their Contacts Data API)
* 2008-06-04 [http://adactio.com/journal/1475/ Jeremy Keith: Making contact] (mentions the Yahoo announcement of the release of their Address Book API).
* 2008-07-15 [http://getsatisfaction.com/pownce/topics/why_does_pownce_keep_killing_kittens_with_the_password_anti_pattern Jeremy Keith: Why does Pownce keep killing kittens with the password anti-pattern?]
* 2008-09-23 [http://pownce.com/adactio/notes/3571554/ Jeremy Keith pownces Either the password anti-pattern goes or I do.]
* 2008-09-25 [http://adactio.com/journal/1513/ Jeremy Keith: Anti-pattern recognition]

=== Excuses and responses===
* Some major players are not helping the cause.
** Just because someone/something else big is misbehaving, that is no excuse for you to do so.
* We are following pretty common practice.
** Just because many other folks are misbehaving, that is no excuse for you to.
* Variant: We are implementing the same code as Facebook and Twitter so we went for best practices.
** Implementing the same code is not best practice. Implementing the same code in this case is the lowest common denominator.
* We aren't in a terribly strong position to drop support.
** Of course you are! Precisely because you *are* small. You have less to lose.
** If you pick a public fight with a misbehaving big player over this, guess who wins? If the press covers it as little guy vs the big guy etc. narrative.
* Our growth is flat!
** Exactly - this won't affect it. But maybe a little positive publicity will help.
* We could implement the OAuth-based proprietary address book APIs, but we'd have to invest the development time to do Facebook, Yahoo, and Google.
** Disable the the password anti-pattern code in the meantime.
* The pragmatic downside is that our growth is stagnant, we need to do features that'll benefit us, and this isn't at the top of the list of features that can do that for us.
** This is the opportunity cost argument. It is the same problem with fixing polluting factories vs. building new factories.
* Why are people threatening to leave us or worse?
** Without community pressure/embarrassment, companies don't change.
* I think we've earned a little benefit of the doubt that we're not 'the industry'.
** Having a "polluting" interface that is on every day means no benefit of the doubt.

==== Pollution analogy ====
The password anti-pattern = teaching people to pollute themselves.
* Just because everyone else pollutes, doesn't mean it makes it right for you to do so.
* Polluting factories need to be fixed just as much as new factories need to be built.
* Without environmentalist pressure/embarrassment, polluting companies don't change.
* Why not focus your efforts on the huuuuuuge polluters like instead of my small company?
** Because easier to apply enough pressure to get smaller guys to change first. Same tactics worked for environmentalists. Then they would use smaller victories to earn bigger victories, until they had racked up enough victories to make the big guys look *really* bad.

Here are some sites that are currently doing this:

=== Blipfm is better with friends ===
[http://www.flickr.com/photos/tantek/3199489045/ http://farm4.static.flickr.com/3389/3199489045_7169ea1a63.jpg]

'''[http://blip.fm Blip.fm]''' - Their "Import Address Book" functionality requests that you enter your username and password for your email provider(s): yahoo, gmail, hotmail, aol, msn.

=== Facebook Connect ===
Per [http://micro.ben-ward.co.uk/post/65425363/facebook-connect Ben Ward's post on Facebook Connect], this user interface:

[http://micro.ben-ward.co.uk/post/65425363/facebook-connect http://5.media.tumblr.com/5vUVOHNMPhm1sj7138AlwQXho1_400.png]

Appears to encourage users to enter their email address and password into something visually resembling (but easy to mimic) a Facebook popup window on ''any'' site.

Thus all a malicious site would have to do is put up a button saying "Login with Facebook Connect", then display an identically styled virtual popup, and the user, who has been taught by the Facebook Connect UI, will simply enter their email address and password.

There's also a more detailed follow up on Ben's views of the Facebook Connect UI [http://ben-ward.co.uk/blog/oauth-flow/ on his blog] — and complements for the alternate version, whereby it uses the iframe to improve the UX for users who are ''already logged in'' to Facebook. There's a bit more snark as well, for those who are into that.

Update: This issue was '''fixed''' by Facebook. They now use a separate pop-up window, complete with browser chrome, to log in when you're not already signed in to Facebook.

=== Facebook see if more friends have joined ===
[http://flickr.com/photos/factoryjoe/2110461562/ http://farm3.static.flickr.com/2324/2110461562_e624ab4175.jpg]

'''[http://facebook.com Facebook]''' - Their "see if more friends have joined Facebook" feature provides you with a popup menu to enter passwords for numerous sites.

=== GetSatisfaction Twitter This widget ===
As [http://twitter.com/adactio/status/1020708247 reported by Jeremy Keith], apparently the [http://getsatisfaction.com GetSatisfaction] "Twitter This" widget requests your Twitter username and password. <strong>(screenshot needed)</strong>

See the support thread on GetSatisfaction "[http://getsatisfaction.com/getsatisfaction/topics/stop_asking_for_twitter_passwords Stop asking for Twitter passwords]" for more.

=== Nsyght import your profile and friends ===
[http://www.flickr.com/photos/tantek/2254537667/ http://farm3.static.flickr.com/2035/2254537667_d831c1fb3a.jpg]

'''[http://nsyght.com Nsyght]''' - Register for an account to import from Digg, Pownce, Last.fm, and Twitter (site is in public alpha)
* Unfortunately the "import from Digg, Pownce, Last.fm, and Twitter" feature depends on entering your username and password to those sites, which is ironic since those sites support microformats and [[social-network-portability]]!

=== Plaxo - Let's look for your friends in your address book ===
[http://www.flickr.com/photos/manveru/3215481930/ http://farm4.static.flickr.com/3088/3215481930_979c0a7f61.jpg]

'''[http://plaxo.com plaxo]''' - Asks in several forms for passwords of different mail services.

=== Plinky - Find Your Friends ===
[http://www.flickr.com/photos/tantek/3218629483/ http://farm4.static.flickr.com/3335/3218629483_e40019cac9.jpg]

'''[http://plinky.com Plinky]''''s "Find Your Friends" feature, which it presents to every newly signed up user, asks for your email address and password for a variety of services.

As [http://twitter.com/dewitt/status/1145448221 DeWitt tweeted]: <blockquote><p>Google, Yahoo, and Microsoft all support browser-based delegated authorization apis for contacts. Plinky should use those apis.</p></blockquote>

See also [http://friendfeed.com/e/6ff1f9ce-df01-4250-05de-c7009f31925f/Wow-Plinky-usernames-are-going-faster-than/ this thread by Jason Shellen (CEO of Plinky)] who says some hopeful things: <blockquote><p>DeWitt - You make a good point. I'll discuss it with the team Monday. In other news, we do support OAuth for posting to Blogger.</p></blockquote>

=== Quechup which friends already use ===
[http://mashable.com/2007/09/02/quechup/ http://mashable.com/wp-content/uploads/2007/09/quechupsignup.PNG]

=== ShareThis import your contact lists ===
[http://flickr.com/photos/factoryjoe/1344414673/ http://farm2.static.flickr.com/1088/1344414673_8e306e265d_o.png]
[http://flickr.com/photos/factoryjoe/1345315346/ http://farm2.static.flickr.com/1143/1345315346_8eb2cf4d7c_o.png]

ShareThis asks for your username and password to email services and social network sites.

=== SlideShare signup form ===
As [http://twitter.com/adactio/status/1020670561 reported by Jeremy Keith], apparently the [http://www.slideshare.net/signup SlideShare signup form] asks for your (in this order)
* Username
* Email Address
* Password
* Confirm Password
<strong>(screenshot needed)</strong>

Because of the proximity of "Email Address" and "Password" input fields it is easy to mistake this for asking for your email address and email password. Perhaps it is asking for your email password? Or perhaps it asks for that later in the process? Screenshots would help.

See the GetSatisfaction support thread "[http://getsatisfaction.com/slideshare/topics/asking_for_3rd_party_passwords Asking for 3rd party passwords]" for more.

=== StockTwits login ===
[http://www.flickr.com/photos/factoryjoe/3061262427/ http://farm4.static.flickr.com/3010/3061262427_3775189375.jpg]

StockTwits.com asks you to "Login" with your Twitter username and password. StockTwits is not run by Twitter, therefore they are asking you for your username and password to another site.

=== Twitpic login to twitter ===
[http://flickr.com/photos/ronin691/2368324013/ http://farm3.static.flickr.com/2166/2368324013_0a15d337c0.jpg]

Twitpic asks you to enter your Twitter username and password. They are not the same site, nor are they run by the same people or company.

=== Twitter are your friends on ===
[http://www.flickr.com/photos/ronin691/2110909518/ http://farm3.static.flickr.com/2179/2110909518_fde956c2ee.jpg]

'''[http://twitter.com/ Twitter]''' is a service that many users (including many of us active with microformats) love and adore and use constantly. Plus they implement microformats (e.g. [[hcard supporting user profiles]] and [[hcard xfn supporting friends lists]])!

However, we still need to call them out for supporting the third-party password anti-pattern.

As co-authors of [[Oauth]], please Twitter, implement and evangelize that path (perhaps even on that "are your friends on" page), rather than this anti-pattern.

=== TwitterNotes ===
[http://flickr.com/photos/guspim/2138354357/ http://farm3.static.flickr.com/2221/2138354357_0c566fd62e.jpg]

'''[http://twitternotes.com/ TwitterNotes]''' asks you to "login with your Twitter account" username and password. They are not the same site, nor are they run by the same people or company.

== Join to fix your profile ==
Some social network sites create public profiles for you without you having any contact with them. If there are any mistakes, they make you join in order to fix them. This sounds like blackmail: Join our service or else we'll continue to publish inaccurate information about you and therefore spam websearch results about you with misinformation.

=== Spock join to fix ===
* 2007-08-15 [http://www.wired.com/techbiz/startups/news/2007/08/spock_reputation Wired News: Astonishing! Spock Thinks You're a Pedophile]
* 2007-12-16 [http://www.fullcirc.com/wp/2007/12/16/please-dont-invite-me-to-spock/ Full Circle Associates: Please, don’t invite me to Spock]
* 2007-12-16 [http://ourfounder.typepad.com/leblog/2007/12/it-may-be-the-e.html Jim Benson: It May Be the Evil Spock] (and [http://ourfounder.typepad.com/leblog/2007/12/an-initial-resp.html An Initial Response to Spock])

== One Unified Social Network ==
Several companies are trying to build the "one unified social network" (to rule them all) where they own/control the social network, and you're "allowed to" build applications on top of their proprietary platform. The most recent example of this is perhaps [http://facebook.com/ Facebook].

This is a bad idea for the same reason you don't see "one universal blogging service".

Other examples of folks walking down this path:
* [http://hcii.cmu.edu/M-HCI/2006/SocialstreamProject/index.php Socialstream] - a [http://google.com/ Google] sponsored project at CMU. Key quote: "a unified social network that, as a service, provides social data to many other applications". See also references in this Forbes article: [http://www.forbes.com/technology/2007/08/28/google-brazil-network-tech-cx_ag_0828orkut.html Google's Secret Society].
* ...

The hope is that these services will see the potential upside of providing open user profiles and social networks through [[social network portability]] and thus enable syndication of such data, as popular blogging services do.

== related ==
* [[social-network-portability]]
* [[anti-patterns]]

value-class-pattern

2010-03-10T19:19:26Z

BenWard: /* Parsing machine-data value-title */ Updated language regarding microformats which *must* advise on value-class-pattern support, and refer to the subsequent documentation for retroactive support.

<entry-title>Value Class Pattern</entry-title>

The value class pattern is derived from [[hCard#Value_excerpting|value-excerpting]] in hCard.

''The editors believe the value-class-pattern to be feature complete and ready for use in markup. Implementers are encouraged to update accordingly and provide [[value-class-pattern-feedback|feedback]]. '''Note''', the precise parsing behavior could change in response to implementer feedback, but the core methods are stable. You should watch this page for updates.''

See also, the [http://microformats.org/blog/2009/05/12/value-class-pattern/ blog announcement].

__TOC__
; Editors
: <span class="vcard"><span class="fn">[[User:BenWard|Ben Ward]]</span></span>
: <span class="vcard"><span class="fn">[[User:Tantek|Tantek Çelik]]</span></span>
; Short URL
: <kbd>http://tr.im/valueclass</kbd>

Sometimes, only a part of an element's content is to be used as the value of a microformat property. This may occur when a property has optional subproperties, such as <code>tel: type</code> and <code>tel: value</code> in [[hCard]]. Other times, the most appropriate structure for a property may include other content.

For these purposes, the special class name <code>value</code> is used to mark-up the relevant data excerpt from larger element content.

==Simple Examples==

Here is markup for a home phone number:

vCard fragment:

<source lang=text>TEL;TYPE=HOME:+1.415.555.1212</source>

hCard fragment:

<source lang=html4strict>
<span class="tel">
<span class="type">Home</span>:
<span class="value">+1.415.555.1212</span>
</span>
</source>

In this case, the <code>value</code> of <code>tel</code> is <code>+1.415.555.1212</code>, not <code>Home: +1.415.555.1212</code>.

Sometimes the value for a microformats property must be split into multiple pieces in the content of the element representing that property. Multiple elements with a class name of "value" (value elements) can be used to extract and concatenate these pieces into a single value for microformats properties which expect simple strings or tel values.

Another example, this time using a localized (British) telephone number:

<source lang=html4strict>
<span class="tel">
<span class="type">Home</span>:
<span class="value">+44</span> (0) <span class="value">1223 123 123</span>
</span>
</source>

In this case, the valid ''data'' for the telephone number is <samp>+441223123123</samp>, but the way in which phone number is presented in Britain will include the <samp>(0)</samp>, for local dialling. That is, from anywhere in the world you may dial <kbd>+441223123123</kbd>, or from within Britain you may dial <kbd>01223123123</kbd>. Common local publishing interferes with the data, since dialling <kbd>'''+440'''1223123123</kbd> is an invalid number.

In the mark-up, two <code>value</code> classes target the part of the telephone number string that makes an international, valid number, whilst allowing conventional presentation.

Another example, adding a place name to a [[geo]] co-ordinate:

<source lang=html4strict>
<p>I'm loitering outside The Bricklayer's Arms
<span class="geo">
51° 30' 48.45", -0° 8' 53.23"
(<span class="value">51.513458;-0.14812</span>)
</span>
</p>
</source>

Whilst the entire string is a geo point, it's only the decimal encoded co-ordinates which must be consumed by a microformats parser, so the <code>value</code> class isolates it from the degrees form, which the publisher includes for completeness.

==Basic Parsing==
# The value class pattern only applies to properties which are simple strings, enumerated values, telephone numbers, and datetimes. The value class pattern does not affect parsing of properties of type email, URL, URI, UID.
# Where an element with such a microformat property class name has a descendant with class name <code>value</code> (a "value" element), parsers should use the following portion of that element:
## if the value element is an <code>img</code> or <code>area</code> element, then use the element's <code>alt</code> attribute value.
## if the value element is an <code>abbr</code> element, then use the element's <code>title</code> attribute value.
## for any other element, use its inner-text.
# Where there are multiple descendants of a property with class name of <code>value</code> (multiple value elements)
## if the microformats property expects a simple string, enumerated value, or telephone number, then the values extracted from the value elements should be concatenated ''without'' inserting additional characters or white-space.
## if the microformats property expects a datetime value, see the [[#Date_and_time_parsing|Date Time Parsing]] section.
# Descendants with class of <code>value</code> must not be parsed deeper than one level. That is, where an element <code>foo</code> with class <code>value</code> has a <em>descendant</em> <code>bar</code> with class <code>value</code>, the content of <strong><code>foo</code></strong> is taken as the <code>value</code>. Nesting additional elements with class of <code>value</code> cannot be used to further isolate a property's value.

e.g.

<source lang=html4strict>
<p class="description">
<span class="value">
<em class="value">Puppies Rule!</em>
<strong>But kittens are better!</strong>
</span>
</p>
</source>

In this example, <code>description</code> has a child ‘<code>value</code>’, and that child has a ''grandchild'' ‘<code>value</code>’. However, the parsing of <code>value</code> classes stops at the first level, so the data for <code>description</code> is: <samp><code><em class="value">Puppies Rule!</em><strong>But kittens are better!</strong></code></samp>, not just <samp>Puppies Rule!</samp>.

== Date and time values ==
=== Summary ===
Some microformats properties expect an ISO8601 datetime value, e.g. [[hCalendar]] <code>dtstart</code> and <code>dtend</code> or [[hAtom]] <code>published</code>.

Authors may use the value class pattern to separately specify the date and the time, which are then combined to specify a single datetime value.

Example, this hCalendar 'dtstart' property with 'value' elements:

<source lang=html4strict>
<p>The weekly dinner will be on
<span class="dtstart">
<abbr class="value" title="2008-06-24">this Tuesday</abbr>
at <span class="value">18:30</span>
</span>
</p>
</source>

produces the following 'dtstart' value:

<source lang=text>
2008-06-24T18:30:00
</source>

and iCalendar converters produce the following DTSTART:

<source lang=text>
DTSTART:20080624T183000
</source>

The lack of a timezone indicates a "floating" datetime, that is a datetime independent of any particular timezone. Examples of floating datetimes could be an alarm clock you set to ring at 7am, or the common 9am-5pm workday.

=== Date and time parsing ===
For all date time properties (as defined in their respective microformats specifications), the following rules apply in addition to (and in some cases replacing) the above value class pattern parsing rules.

When a "value" element is found, parse a value from the element as follows:
* if the element is an <code>img</code> or <code>area</code> element, then use the element's <code>alt</code> attribute value.
* if the element is an <code>abbr</code> element, then use the element's <code>title</code> attribute value.
* for any other element, use its inner-text.
* if the value has both a specific ISO8601 date and a specific time, use those and stop looking for "value" elements.
* if the value has *only* a specific date, specifically, fits the following ISO8601 date patterns (i.e. as documented in the [http://en.wikipedia.org/wiki/ISO_8601 Wikipedia summary of ISO8601])
** YYYY-MM-DD
** YYYY-DDD
** then use that as the date value. For the purposes of the value class pattern, the hyphens "-" separating the year, month, day and/or ordinal day are required.
** ignore any further "value" elements that specify the date.
* if the value has *only* a specific time (with or without timezone), parse it for a time value that can match any of the following:
** HH:MM:SS-XX:YY
** HH:MM:SS+XX:YY
** HH:MM:SS-XXYY
** HH:MM:SS+XXYY
** HH:MM:SSZ
** HH:MM:SS
** HH:MM-XX:YY
** HH:MM+XX:YY
** HH:MM-XXYY
** HH:MM+XXYY
** HH:MMZ
** HH:MM
** HH is the 24 hour "hours" in the time, from 00 to 24, with optional leading 0 for values less than 10.
** MM are the minutes from 00 to 59
** SS are the optional seconds from 00 to 59 (60 for a leap second). If omitted, infer 00 seconds.
** XX is the time zone hours offset, from 00 to 12 with optional leading 0 for values less than 10.
** YY is the time zone minutes offset, from 00 to 59, though in practice only 00, 15, 30, 45 minute offsets are used in global timezones.
** Z is the literal 'Z' to indicate GMT.
** For the purposes of the value class pattern, the colons ":" separating the hour, minutes, seconds are required.
** However the colons ":" separating the hours and minutes of any timezone offset are ''optional'' and discouraged in order to make it less likely that a timezone offset will be confused for a time.
** Case insensitive { }"am"|{ }"a.m." suffix to treat an HH value of 12 as 00, or a case-insensitive { }"pm"|{ }"p.m." suffix to add 12 to HH value less than 12 - per [http://en.wikipedia.org/wiki/12-hour_clock Wikipedia article on the 12 hour clock]. Note: [[X2V]] has implemented this.
*** HH:MM:SSam
*** HH:MM:SSpm
*** HH:MMam
*** HH:MMpm
*** HHam
*** HHpm
*** where "am" and "pm" mean "am or a.m." and "pm or p.m."
*** when MM is omitted, infer 00 minutes.
** ignore any further "value" elements that specify the time.
* if the value has *only* a specific timezone, parse it for a time zone value that can match any of the following:
** -XX:YY
** +XX:YY
** -XXYY
** +XXYY
** -XX
** +XX
** Z
** XX is the time zone hours offset, from 00 to 12 with optional leading 0 for values less than 10.
** YY is the time zone minutes offset, from 00 to 59, though in practice only 00, 15, 30, 45 minute offsets are used in global timezones.
** Z is the literal 'Z' to indicate GMT.
** ignore any further "value" elements that specify the timezone.

If by parsing the "value" element(s), at least a specific date has been found, then the "value" is overall valid, and the parser assembles the overall datetime value by concatenating the specific date, "T" and specific time (if time was specified, with 00 seconds implied if no seconds are provided), and specific timezone (if timezone and a specific time was specified).
* YYYY-MM-DD - no time specified
* YYYY-MM-DDTHH:MM:SS - time specified but no timezone. This is a floating time.
* YYYY-MM-DDTHH:MM:SS-XXYY or
* YYYY-MM-DDTHH:MM:SSZ or
* YYYY-MM-DDTHH:MM:SS+XXYY - both time and timezone were specified.

=== format specific details ===
The following are format specific details and <span id="format_specific_optimizations">optimizations</span> that make use of the value-class-pattern.

;<span style="font-size:smaller">short URL for this section</span>
:http://tr.im/vcpfso

==== hCalendar dtend implied date ====
Typically events that start and end the same day only display the date of the event once (makes sense per the DRY [[principle]]) (real world examples: [http://upcoming.yahoo.com/event/3010807/ Upcoming], ... more examples with URLs would help for thoroughness).

Thus it would be convenient if we could imply an [[hCalendar]] event "dtend" date from its "dtstart" date when only the time (and optionally timezone) was specified for its "dtend", e.g.:

<source lang=html4strict>
<span class="vevent">
The <span class="summary">party</span> will be on
<span class="dtstart">
<span class="value">2009-06-26</span>, from
<span class="value">19:00</span></span> to
<span class="dtend"><span class="value">22:00</span></span>.
</span>
</source>

To simplify this further for authors, hCalendar processors could treat the specifying of just the time per the value-class-pattern date and time value rules, and thus eliminate the need for the "value" span inside the "dtend" span:

<source lang=html4strict>
<span class="vevent">
The <span class="summary">party</span> will be on
<span class="dtstart">
<span class="value">2009-06-26</span>, from
<span class="value">19:00</span></span> to
<span class="dtend">22:00</span>.
</span>
</source>

hCalendar to iCalendar converters should produce the following iCalendar fragment (as part of a valid .ics file) from either of the above two examples:

<source lang=text>
BEGIN:VEVENT
SUMMARY:party
DTSTART:20090626T190000
DTEND:20090626T220000
END:VEVENT
</source>

Note: [[X2V]] has implemented dtend implied date from dtstart.

Examples "in the wild":
* http://microformats.org/wiki/events/2009-08-12-nyc-workshop (real world example, but on this wiki).

==== iCalendar generators ====
microformats implementations which consume [[hCalendar]] and generate iCalendar {{must}} in addition:
# remove any dash "-" separators in the date.
# remove any colon ":" separators in the time.
# add a whole day to any date-only (lacking a specified time) (date inclusive) hCalendar <code>dtend</code> property values in order to generate an (date exclusive) iCalendar <code>DTEND</code> property value with the same meaning, per the resolution to the [[dtend-issue]].
# perform datetime math on any +/- relative timezone value, and produce an effective UTC value ending with "Z".

==== hAtom updated implied date ====
Similarly, in blog posts that indicate both when they were "published" and "updated", the date is usually only displayed once, typically when "published" (real world examples with URLs would help for thoroughness).

Thus it would be convenient if we could imply an [[hAtom]] entry "updated" date from its "published" date when only the time (and optionally timezone) was specified for its "updated", e.g. for a blog post that was updated the same day:

<source lang=html4strict>
<span class="hentry">
<span class="entry-summary">short blog post example</span>
was published on <span class="published">
<span class="value">2009-08-01</span> at <span class="value">12:06</span></span>
and updated at <span class="updated"><span class="value">12:10</span></span>.
</span>
</source>

To simplify this further for authors, hAtom processors could treat the specifying of just the time per the value-class-pattern date and time value rules, and thus eliminate the need for the "value" span inside the "updated" span:

<source lang=html4strict>
<span class="hentry">
<span class="entry-summary">short blog post example</span>
was published on <span class="published">
<span class="value">2009-08-01</span> at <span class="value">12:06</span></span>
and updated at <span class="updated">12:10</span>.
</span>
</source>

==== Atom generators ====
microformats implementations which consume [[hAtom]] and generate
Atom {{must}} in addition:
* normalize all date and datetime values to [[RFC3339]].

=== derivation and tests ===
This section is <em>informative</em>.

The handling of date and time values in the value class pattern was originally [[value-excerption-pattern-brainstorming#date_and_time_separation|brainstormed on the value-excerption-pattern-brainstorming]] page and derived from that analysis and feedback. For the curious, historical details may be found there, along with additional thoughts for extension.

See [[value-class-date-time-tests]] for test cases.

==Parsing value from a <code>title</code> attribute==
The <code>value-title</code> class name allows the publisher to indicate the data value for a parent property is contained in the <code>title</code> attribute of an element, rather than the inner-text.

This can be used to provide a synonym within content, or used to quietly publish alternate forms of information for microformats parsing, without affecting the consumption of content.

For example, you can use casual localization with dates:

<source lang=html4strict>
<p>It was
<span class='dtstart'>
<span class='value-title' title='2008'>last year</span>
</span>
that I realised my addiction to cashew nuts would cost this country so dear.
</p>
</source>

Parsing rules for <code>value-title</code> are the same as for <code>value</code> above, with the following change:

* Where a microformats property has a child element with class name of <code>value-title</code>, the content of the <code>title</code> attribute of that element must be parsed, rather than the portion of the element that would be parsed for a class name of <code>value</code>.

===Using <code>value-title</code> to publish machine-data===

The initial usage of <code>value-title</code> is used to publish alternate, parsable forms of property values in a visible context without the use of the <code>abbr</code> element whose semantics already support interpretation of the 'title' attribute as an expanded, more precise form of the content.

Experience has found that there are some cases in microformats where a number of publishers want to include a precisely accurate and parsable value for a property but do not want it to be visible in their page, even as a tooltip.

For example, full [[ISO8601]] datetimes may be confusing to readers of the page (as a tooltip or when read aloud by a screen reader), and enumerated values such as the <code>type</code> subproperty of hCard's <code>tel</code> property use US-English terms, which are not part of pages in any other language.

Since both of those scenarios have shown to be obstacles for a number of publishers, for these cases, and these alone, there exists a further extension of value-excerption. This extension allows the parsable form of the property to be published ‘silently’ immediately adjacent with the respective local visible content.

Here is an example, with the required use of a first child element with class name <code>value-title</code>:

<source lang=html4strict>
<p class='tel' lang='en-gb'>
<span class='type'>
<span class='value-title' title='cell'> </span>
mobile
</span>
<span class='value'>+44 7773 000 000</span>
</p>
</source>

The <samp>cell</samp> value is parsed for the 'type' subproperty, but <samp>mobile</samp> is presented to the user.

In the case of dates:

<source lang=html4strict>
<p class='dtstart'>
<span class='value-title' title='2009-03-14T16:28-0600'> </span>
March 14th 2009, around half-past four
</p>
</source>

A microformats parser will read the ISO8601 format datetime <samp>2009-03-14T16:28-0600</samp>, but users will only see <samp>March 14th 2009, around half-past four</samp>. Testing has shown that the ISO8601 datetime above does not get exposed to any user at all.

===Parsing machine-data <code>value-title</code>===

Browsers collapse the <code>value-title</code> span down to a width of <code>0</code>, effectively providing no visual rendering, whilst keeping the element in the DOM. With no physical dimensions, there is no ‘hover’ state, so no tooltip is revealed. Furthermore, the empty element is not passed to assistive technology layers such as VoiceOver. Screen readers do not read the contents of the title attribute of an empty <code>span</code> element.

We conducted [[value-excerption-value-title-test|thorough testing]] of these parsing behaviors to ensure accessibility.

''Note: Whilst the <code>value-title</code> element is more gracefully written without whitespace inner-text (or as self-closing <code><foo /></code> element in XHTML), some tools such as WYSIWYG editors and HTML-Tidy will erroneously discard such elements, resulting in parsable data being thrown away by some tools. As such, <code><span class='value-title'> </span></code>, including a single whitespace character between the opening and closing tag, may also be used. In some situations, this whitespace may be rendered by the browser, and authors should test their output.''

Parsing this final <code>value-title</code> extension imposes some stricter restrictions on usage. These restrictions exist to reduce the impact of <abbr title="Don't Repeat Yourself">DRY</abbr> violations, reduce the opportunity for sites to spoof data, and encourage best practice for maintaining both forms of data accurately.

Where an element with class <code>value-title</code> is to be parsed as data for a property, and that element also contains no non-whitespace content (hereafter referred to as ‘empty’), the following rules apply:

* The ‘empty’ value-title element must be the '''first, non-whitespace child''' of the property element. That is, it should follow immediately after the property is declared, before the human-readable form, and without any additional nesting.
* The ‘empty’ value-title element can only be used for specific properties. Future microformat specifications (and updates to existing microformats) must explicitly state which properties may be used with this extension of the value-class-pattern. (Retroactive property support for existing microformats is documented below.)
* Where an ‘empty’ value-title element is to be used as the single property value, it must be the ''only'' such <code>value</code> content. That is, the first instance of a conforming <code>value-title</code> element overrides all other <code>value</code> and <code>value-title</code> siblings and/or cousins.
* Tools written to perform Conformance Testing and/or Validation of microformats ''should'' attempt to compare the machine-data and human-legible forms of the property data, and warn authors if the forms do not match.

=== limited use of value-title ===
Due to the fact that the value-title pattern hides some amount of data which tends to be a machine-specific duplicate of data that is provided in the human readable content, there are two microformats [[principles]] being compromised: '''visibility''' and '''<abbr title="Don't Repeat Yourself">DRY</abbr>'''. Thus the applicability of this pattern is deliberately restricted to properties that have demonstrated through experience a need for it, with no known better alternative.

In general authors should:

# First, try to directly specify microformats property values inline (the most visible, no duplication),
# Then consider using the value-class pattern
## Including multiple value elements for date and time properties
# and then only if those methods are insufficient, consider the value-title pattern.

This document post-dates other microformat specifications, such that they may not yet indicate which properties permit use of this pattern. In the interim, '''only''' the following types of properties should allow the value-title pattern.

* ISO8601 date, datetime, timezone, and duration values
* Enumerated values (such as the hCard tel/email/adr 'type' subproperties)
* Co-ordinates (such as the [[geo]] 'latitude' and 'longitude' properties)
* Telephone number properties (e.g. the hCard 'tel' property)

The [[machine-data]] page has documentation of some of the properties of some specs which experience has shown need a solution like the value-title pattern.

There are some simple reference examples and tests for this pattern on [[value-class-pattern-tests]].

In future use, ''specification authors'' may inherit use of <code>value-title</code> by use of ISO8601 date and time formats, or reuse of other microformats, but specifications should _avoid_ introducing new data structures that depend on or encourage this pattern. New specifications are themselves expected to adhere to the principals of visible data and <abbr>DRY</abbr>.

== Test cases ==
See [[value-class-pattern-tests]].

== <abbr title='Frequently Asked Questions'>FAQ</abbr>==
This section is '''informative'''.

Frequently asked questions about the value-class-pattern. Once this section grows too big, we'll make a separate wiki page (like [[value-class-faq]]).

<div class='discussion'>
* '''Why use an 'empty' element? Why not embed data in the class attribute?'''
** The class attribute is inappropriate for embedded data values, as per the HTML4 specification, which states <code>class</code> is for ‘general purposing processing’, which is defined as ‘e.g. for identifying fields when extracting data from HTML pages into a database, translating HTML documents into other formats, etc.’. ‘General purpose processing’ does not extend to data itself. Furthermore, this method avoids inventing a new string pattern for embedding data.
* '''Why use an 'empty' element? Why not make up a new attribute, like ‘data’?'''
** Microformats exist and function in ''valid'' HTML4 and XHTML1. Those are the current standards for web development, and microformats exist for use ''now''. In the future, perhaps revisions of HTML will offer up another solution. For now, this method has been tested against browsers, and creates a consistent document structure (where machine-form and human-form data are siblings).
* '''The <code>title</code> attribute should only be used for content!'''
** The <code>title</code> attribute ''is'' used for content and is read by microformats parsers. This exists for cases where data cannot be parsed with sufficient precision from just the commonly published, visible information. This pattern allows both forms of content to be included, whilst keeping it invisible to human consumers.
</div>

You can also refer to the general [[faq|Microformats FAQ]] and [[principles]].

== Examples in the wild ==
This section is '''informative'''.

The following sites and pages have started marking up content with the value-class-pattern, and are thus good places to go for examples with real world content to test with implementations (i.e. parsers). If you use the value-class-pattern in your content, feel free to add it to the '''top''' of this list. Once the list grows too big, we'll make a separate wiki page (like [[value-class-examples-in-wild]]).

* [http://visitmix.com/labs/oomph/2.0/tests/test.html Test Harness For Oomph] This pages uses a whole range of different patterns for both hCard and hCalendar, using both value and value-title, mostly derived from the specification above
* [http://georgebrock.com/ George Brocklehurst's activity stream] and [http://blog.georgebrock.com/ blog] use "value-title" for hAtom <code>published</code> property
* [http://ben-ward.co.uk/ Ben Ward's home page] uses:
** "value-title" for hCard <code>bday</code> property
** "value-title" for hAtom <code>updated</code> property
* [http://microformats.org/ microformats.org] uses:
** "value-title" for hAtom <code>updated</code> property in [[http://microformats.org/ microformats.org blog postss]]]
** date and time value separation for hCalendar <code>dtstart</code> property in [[events|microformats.org recent and upcoming events wiki page]]

''Add your site/page(s) that use the value-class-pattern here, along with a brief description of what value-class-pattern features you use, with which microformat(s) and which of its/their properties.''

== Implementations ==

This section is '''informative'''.

The following implementations have been developed which either generate or parse value-class-pattern property values. If you have an value-class-pattern implementation, feel free to add it to the '''top''' of this list. Once the list grows too big, we'll make a separate wiki page (like [[value-class-implementations]]).

* [[Oomph]] Version 2 passes [[value-class-pattern-tests#Date_and_time_values|Date and time values test cases]] and is a thorough implementation of the value class pattern.
* [[X2V]] v0.9.3 and later:
** implements [[#Date_and_time_values|Date and time values parsing]], including am/pm time values
*** thus passes [[value-class-pattern-tests#Date_and_time_values|Date and time values test cases]].
** implements [[#hCalendar_dtend_implied_date|hCalendar implied dtend date]]
* [[Operator]] has *some* implementation of the value-class-pattern according to Michael Kaply, but precisely how much is implemented, for which properties (property types) and which microformats is not currently known.
* [[Optimus]] v0.8 and later implements <code>value-title</code> as [http://twitter.com/DmitryBaranovsk/status/1891253248 announced by Dmitry Baranovskiy].
* ... add your implementation(s) that parse or generate the value-class-pattern here, along with which features you support (hopefully all!) and note any limitations if any.

== Articles ==
Articles and <span id="Blog_Posts">blog posts</span> discussing the value class pattern, most recent first.
When this section gets too big, create a separate page like: [[value-class-pattern-articles]]
* <span class="hentry"><span class="published">2009-08-25</span> <span class="entry-summary">MIX Online: <span class="entry-title">[http://visitmix.com/Articles/The-Value-Class-Pattern The Value Class Pattern]</span></span> by <span class="author vcard"><span class="fn">Jeremy Keith</span></span></span>
* [http://ablognotlimited.com/s/106 Getting Semantic With Microformats, Part 8: Value Class Pattern] -- A very thorough writeup by Emily Lewis on the value class pattern
* [http://adactio.com/journal/1579/ 2009-05-17 Adactio: Microformation]
* [http://forabeautifulweb.com/blog/about/value_class_pattern/ For A Beautiful Web: Value Class Pattern]
* [http://microformats.org/blog/2009/05/12/value-class-pattern/ 2009-05-12 microformats.org: Value Class Pattern]

==Related Pages==
This section is '''informative'''.

* [[value-class-pattern-tests]]
* [[value-excerption-pattern-issues]]
* [[hcard#Value_excerpting|hCard: Value Excepting]]
* [[value-excerption-pattern-brainstorming]]
* [[machine-data|Machine Data in Microformats]]

== References ==
This section is '''informative'''.
* [http://www.useit.com/alertbox/9608.html Jakob Nielsen: International Web Usability]

User:BenWard

2010-02-12T08:42:16Z

BenWard: /* Contact */

{{DISPLAYTITLE:Foo}}

http://ben-ward.co.uk/static/identity/BenWard.jpg

Engineer at the Yahoo! Developer Network, based in San Francisco.

'''I am a microformats.org admin'''. Please contact me with regard to community issues, but if it's a ‘todo’ item, first add it to the [[todo]] page for reference. Also note that my contributions to microformats.org, active work and draft pages represent my views alone and not the microformats admins as a collective.

==Active Work==

* Microformats.org administrator
* Responsible for maintenance and development of the microformats.org [http://microformats.org/ blog], [[wiki-2|wiki]] and other infrastructure.
** Wiki 2.1 updates will probably follow at some point in the next few months, since there are some formatting gaps.
** Issue Tracking is a larger problem for the first half of this year.
** µf activity streaming experiments come soon, too.
* Editor of the [[include-pattern]]
* Editor of the [[value-class-pattern]]

==Drafts==

Some work that will get proposed to the microformats community once I've written up the proposal for consumption. Be aware that anything you find here will be incomplete, or just brain dumps.

* [[User:BenWard/drafts/embed-brainstorming|embed-brainstorming]] - Can we microformat ‘embed this video/picture/sound/media in your blog post/website’ code snippet?
* [[User:BenWard/drafts/communcation-preferences-brainstorming]] - Can we microformat people's communication preferences? e.g. Email invitations to new events, XMPP me about changes to event timing/cancellations, twitter ‘introductions’, have conversations over XMPP, etc.

==Armchair Roles==

Work I'm involved with, touched, fiddled with or otherwise contributed to, but not dedicatedly contributing to.

* Co-author and some-time editor of [[recipe]]

==Archived Work==

These things I've done before, but aren't active projects any more:

* Major implementor of [[hListing]] at Yahoo! (Spring 2007)
* Wrote hCards + XFN themed post on [http://www.digital-web.com/articles/portable_social_networks_building_blocks_of_a_social_web/ Portal Social Networks, The Building Blocks of a Social Web] at Digital Web magazine:

==Contact==

* Personal site at http://benward.me/
* Email ben at benward dot me
* XMPP/Jabber: xmpp://talk@ben-ward.co.uk
* [http://twitter.com/benward @benward] on Twitter

==Contributions are Public==

{{public-domain-release}}

[[Category:Microformats Admins]]
[[Category:Editors]]

hreview-advocacy

2010-02-12T08:40:48Z

BenWard: Reverted edits by Grace100 (Talk) to last version by Tantek

<h1> hReview advocacy</h1>
{{TOC-right}}
Part of the larger microformats [[advocacy]] effort. Adding [[hreview|hReview]] to these sites would improve their usability and ambient findability.

== general review sites ==
* [http://www.listal.com/ Listal] for all reviews including [http://www.listal.com/reviews/books/1/books books].
** Requested by e-mail, 2007-05-29. [[User:DavidMead|David Mead]]
* [http://pownce.com Pownce]
** Requested a "rating" note-type which would produce hReview markup (see comment by pownce.com/t [http://pownce.com/leahculver/notes/621117/ in this thread]) [[User:Tantek|Tantek]] 13:12, 3 Sep 2007 (PDT)

== food and restaurant reviews ==
* <span id="Foodbuzz">[http://www.foodbuzz.com/ Foodbuzz]</span> - a food, restaurant review, afficionado site
** primarily [[hreview|hReviews]] for reviews, and also
** [[hcard|hCards]] for restaurant listings e.g. [http://www.foodbuzz.com/restaurants/us/california/saratoga/14039-plumed-horse Plumed Horse]
** [[hcard-supporting-user-profiles|hCards for user profiles]] e.g. [http://www.foodbuzz.com/profile/ryanthegirl ryanthegirl]
** [[hcard-xfn-supporting-friends-lists|hCard+XFN for friends lists]] e.g. [http://www.foodbuzz.com/profile/ryanthegirl/foodies foodies list]
** [[hatom|hAtom]] for blog posts
** a potential [[recipe]] microformat for recipes
** a potential [[media-info]] microformat for photos and videos
** ... all '''Requested''' in person to site founder Scott Thorpe at [http://upcoming.yahoo.com/event/270906 SuperHappyDevHouse 20] [[User:Tantek|Tantek]] 21:18, 13 Oct 2007 (PDT)
* [http://www.mealme.com/ Meal Me] for all food reviews such as [http://www.mealme.com/browse.php?mealid=754].
** Requested by e-mail, 2008-01-03. [[User:DavidMead|David Mead]]
* [http://yelp.com/ Yelp] - lots of restaurants
** Anyone have contacts at Yelp?

== wine reviews ==
Similar to http://corkd.com/ the following sites could very much benefit from being marked up with [[hreview|hReview]]:
* http://winecast.net/2007/07/25/wine-ratings-revisited-2/
* http://goodwineunder20.blogspot.com/2007/08/how-we-buy-wine.html
* http://www.winelifetoday.com/

== camera reviews ==
* [http://www.dpreview.com/ Digital Photography Review]
** Requested by feedback form, 2007-01-18. [[User:AndyMabbett|Andy Mabbett]]
* [http://www.steves-digicams.com/ Steve's Digicams]
** Requested by e-mail, 2007-01-18. [[User:AndyMabbett|Andy Mabbett]]

== government reviews ==
*[http://petitions.pm.gov.uk/ E-petitions] (in draft, and asking for suggested improvements}
** Requested by e-mail, 2006-12-01 [[User:AndyMabbett|Andy Mabbett]] 11:48, 1 Dec 2006 (PST)
*** reply: "I've added it to our list of ideas." 2006-12-04 [[User:AndyMabbett|Andy Mabbett]] 11:08, 4 Dec 2006 (PST)

== movie reviews ==
* [http://www.imdb.com/ Internet Movie Database] (IMDb)
** anyone have contacts at IMDB?
** primarily hReview for all the review data, and in addition hCard for all the people, rel-tags for film/plot/other tags
** [http://tantek.com/microformats/2007/imdb-title-tt0413267uf.html title/tt0413267 with microformats] - hReview for the whole page for the item with overall rating, name, photo, tags. hCards for the directors/actors. [[User:Tantek|Tantek]] 19:20, 21 May 2007 (PDT)
***Could also use tag on year (also on Sound Mix, Certification and actor-names if URLs allowed this). [[User:AndyMabbett|Andy Mabbett]] 02:23, 22 May 2007 (PDT)
** [[media-info]] microformat once there is one.
** '''Requested''' 2007-08-31; received only a generic boilerplate reply. '''Does anyone have a direct contact there?''' [[User:AndyMabbett|Andy Mabbett]]

== music reviews ==
*[http://www.discogs.com/ Discogs]
**hReview for album ratings, hCard for artist bios + record company details, hCard for user profiles, audio microformat, when ready, for discographies requested 2007-08-30 [[User:AndyMabbett|Andy Mabbett]]

== book reviews ==
* [http://www.librarything.com/ LibraryThing]
** e.g. [http://www.librarything.com/catalog.php?view=trealawboy]

== successes ==
*[http://www.birderslibrary.com/ The Birder's Library]
**[http://www.birdforum.net/showthread.php?p=779886#post779886 Requested]; confirmed under development, 2006-12-18.
** '''Success''' e.g. [http://www.birderslibrary.com/reviews/dvd/audubon_video_guide.htm Audubon VideoGuide to 505 Birds of North America]. Apparently from 2007-01-18 [[User:AndyMabbett|Andy Mabbett]]

== see also ==
* [[advocacy]]

hatom-issues

2010-01-21T08:46:11Z

BenWard: Added issue looking for explicit support for <ins> and <del> `datetime` markup for the `updated` properties.

<entry-title> hAtom issues </entry-title>
These are externally raised issues about [[hAtom]] with broadly varying degrees of merit. Thus some issues are REJECTED for a number of obvious reasons (but still documented here in case they are re-raised), and others contain longer discussions. Some issues may be ACCEPTED and perhaps cause changes or improved explanations in the spec.

'''IMPORTANT''': Please read the [[hatom-faq|hAtom FAQ]] and the [[hatom-issues-resolved|hAtom resolved issues]] ''before'' giving any feedback or raising any issues as your feedback/issues may already be resolved/answered.

Submitted issues may (and probably will) be edited and rewritten for better terseness, clarity, calmness, rationality, and as neutral a point of view as possible. Write your issues well. — [http://tantek.com/ Tantek]

== closed issues ==
See: [[hatom-issues-closed]]

== resolved issues ==
See: [[hatom-issues-resolved]]

== issues ==
<span id="Issues">Please add new issues</span> to the '''bottom''' of the list by copy and pasting the [[#Template|Template]]. Please follow-up to resolved/rejected issues with new information rather than resubmitting such issues. Duplicate issue additions will be reverted.

===2010===
==== No defined parsing rule for <code>updated</code> timestamps in <code>ins</code>elements ====
* {{OpenIssue}} 2010-01-20 raised by [[User:BenWard|BenWard]]
*# hAtom includes the <code>updated</code> property for the last modification/revision date of an entry. HTML already has an <code>ins</code> element for marking up inserted changes to text, and that element has a <code>datetime</code> attribute, to document the date and time of the change. Currently, hAtom and microformats have no model for parsing the data from that <code>datetime</code> attribute, but the document semantics suggest it would be an appropriate source for the <code>updated</code> property. Example: <http://blog.benward.me/post/250674456>
*#* Proposed resolution. Document a parsing rule for the <code>ins</code> element, stating that for an <code>ins</code> (or <code>del</code>) element with class of <code>updated</code>, the value of the <code>datetime</code> attribute should be used as the value.
*#* Proposed extended resolution: As well as the above explicit parsing rule, an implication parsing rule stating that where <code>update</code> is not explicitly marked up, the parser may aggregate all <code>ins</code> and <code>del</code> elements in the <code>hentry</code>, and use the most recent <code>datetime</code> attribute content as the <code>updated</code> value.

===2009===
==== too many required hentry properties ====
* {{OpenIssue}} 2009-05-26 raised by [[User:Tantek|Tantek]]
*# hAtom 0.1 requires numerous properties for an hentry (often based directly on required elements from the Atom standard). Given the broad variety of situations that hAtom is used in content, many (or even most) of these properties are not already specified in such content, and thus it is poor methodology to require them because there is a good chance (experience has shown) either (a) the content author will ignore the requirement, or (b) will make something up to satisfy the requirement. A few similar/overlapping/sub-issues are noted below (e.g. [[#Author|author is required]], and not always available).
*#* Proposed resolution. Make nearly all hentry properties "optional" in hAtom 0.2. Consider keeping at most only one required property, perhaps "updated" - that is, if there is no date of update/publication in the content you are trying to mark up, then perhaps it doesn't make sense to mark up that content with hAtom, since hAtom is for episodic, time-based/stamped content.
*#** consider pattern abstraction: all microformats should minimize "required" properties for the same reason, and perhaps ''only'' require at most a single property which is indicative of what that microformat is for, that is, if the author does not publish that one required property, then perhaps they should not be using the microformat that requires that one property.
*#* I have the same problem. I'm collecting various feeds to analyse them. The sources are often RSS 0.9, but I want to put the results into an Atom feed. --[[User:Simon Brodtmann|Simon Brodtmann]] 00:51, 1 July 2009 (UTC)
*#** entry:author should be optional and could be either a hCard or a string
*#** entry lacks a [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.category category] and it shuld either use rel-tag or just be a string
* 2009-07-18 [[User:DavidJanes]] I would like to break this into a separate issue for each currently required element, as we're likely to have to define defaulting rules
* 2009-07-21 [[User:TobyInk|TobyInk]]: Why not have three levels of property: ''required'', ''recommended'' and ''optional''. There would be as few as possible ''required'' properties. Any properties which are needed to create a conformant application/atom+xml feed would be ''recommended''. Everything else would be ''optional''.'
** 2009-07-02 [[User:DavidJanes]] why not then use the RFC MUST, SHOULD and MAY terminology? I think this is a good idea though.
** 2009-09-03 [[User:Chris Cressman|Chris Cressman]] +1 to the idea of property "levels" and reusing RFC terminology.

==== entry-title optionality ====
* {{OpenIssue}} 2009-07-18 raised by [[User:DavidJanes]]
** this element should be optional
*** +1 [[User:DavidJanes]]
*** +1 [[User:WebOrganics|Martin McEvoy]] but not recommended.
*** ... your vote here ...
** if this element is not in the [[hatom#In_General|physical model]], the logical model value should be
*** the empty string
**** +1 [[User:DavidJanes]]
**** -1 [[User:WebOrganics|Martin McEvoy]]
*** the value should not be blank.
**** +1 [[User:WebOrganics|Martin McEvoy]] see: [http://www.atomenabled.org/developers/syndication/#requiredEntryElements Required Entry Elements] from Atom Enabled.
**** [[User:DavidJanes]] what should it be then, if physically representing it is optional? Since Atom makes this a SHOULD and not a MUST (I'm not shouting, just following RFC convention), and we're assuming there's a good reason for the entry-title not to be present in the first place, why not an empty string?
***** [[User:WebOrganics|Martin McEvoy]] entry:title is a required attribute of atom at both feed and entry level, in both instances it says "Contains a human readable title" (a requirement) an empty string is not anything human readable (personal oppinion), maybe hAtom 0.2 should only recommend that the value of entry-title "should" not be an empty string.
*** ... your proposal here, your vote in a sublist ...
* include in hAtom 0.2
** +1 [[User:DavidJanes]]
** +1 [[User:WebOrganics|Martin McEvoy]]

==== updated optionality ====
* {{OpenIssue}} 2009-07-18 raised by [[User:DavidJanes]]
** this element should be optional
*** +1 [[User:DavidJanes]] ... the demand for optionality of the issue is high (cf the microsoft web clips) and if it remains required we're just going to reinvent hAtom without this element
*** +1 [[User:Chris Cressman|Chris Cressman]] Agree there is demand for optionality. This requirement has previously deterred me from using hAtom.
** if this element is not in the [[hatom#In_General|physical model]], the logical model should be
*** the page creation date
**** +1 [[User:DavidJanes]]
**** +1 [[User:Chris Cressman|Chris Cressman]]
*** ... your proposal here, your vote in a sublist ...
* include in hAtom 0.2
** +1 [[User:DavidJanes]]
** +1 [[User:Chris Cressman|Chris Cressman]]

==== author optionality ====
* {{OpenIssue}} 2009-07-18 raised by [[User:DavidJanes]]
** this element should be optional
*** +1 [[User:DavidJanes]] for the same reason 'updated' should be optional: we'll just reinvent hAtom slightly differently otherwise
*** +1 [[User:Chris Cressman|Chris Cressman]] Same reason as 'updated' above.
*** ... your vote here ...
** if this element is not in the [[hatom#In_General|physical model]], the logical model should be
*** "anonymous" (somewhat like [[hreview]]), except not explicit
**** +0.5 [[User:DavidJanes]]
**** 0 [[User:Chris Cressman|Chris Cressman]] Using a blog post as an example, I can determine the author from surrounding context. 'Anonymous' doesn't seem like an acceptable solution. However, I don't have the technical expertise to create a better solution and would be willing to accept 'anonymous'.
*** make this implementation defined
*** something constructed from the page's URL & other information
*** ... your proposal here, your vote in a sublist ...
* include in hAtom 0.2
** +1 [[User:DavidJanes]]
** +1 [[User:Chris Cressman|Chris Cressman]]

=== 2008 ===
==== add url property to hentry ====
* {{OpenIssue}} 2008-09-10 raised by [[User:Tantek|Tantek]]
*# hAtom 0.1 uses [[rel-bookmark]] for permalinks. Permalinks may not always be hyperlinks or hyperlinkable. Thus I propose we re-use the <code>url</code> property (from [[hCard]], [[hCalendar]], [[hReview]], etc.) as a sub-property of the <code>hentry</code> property/container/root.
*#* Proposed resolution. Add "url" sub-property to "hentry" in hAtom 0.2.
*# {{ToDo}} can anyone provide examples where this would be used? [[User:DavidJanes]]

==== misuse of address element ====
* {{OpenIssue}} 2008-06-07 raised by [[User:Tantek|Tantek]]
*# hAtom 0.1 says "an Entry Author element SHOULD be encoded in an <code><address></code> element" and "find the Nearest In Parent <code><address></code> element(s) with class name author and that is/are a valid hCard" - this is a misuse of the address element. The address element means the ''contact'' for the page or major portion thereof (see [[hcard-faq#Should_I_use_ADDRESS_for_hCards|hCard FAQ: Should I use ADDRESS for hCards]]), which ''may'' also be the ''author'' but is not necessarily. See [[hcards-and-pages]] for more details on this semantic distinction.
*#* Proposed resolution: Eliminate all requirements and recommended use of the <code><address></code> element from hAtom.
*#** +1 --[[User:Csarven|Sarven Capadisli]] 11:57, 11 Nov 2008 (PST)
*#** +1 [[User:DavidJanes]]
*#** +1 [[User:Chris Cressman|Chris Cressman]] Prefer microformat solutions that don't dictate specific elements.
* include in hAtom 0.2
** +1 [[User:DavidJanes]]
** +1 [[User:Chris Cressman|Chris Cressman]]

=== 2007 ===
==== marking up comments ====
* {{OpenIssue}} 2007-11-25 raised by [http://www.wirewd.com/ Ken Wronkiewicz].
*# There's no currently defined way to exactly handle threaded discussions. I think this is quite useful to have.
*#* The prior art is RFC [http://tools.ietf.org/html/rfc4685 4864]. The microformat solution should map fairly cleanly to this.
* include in hAtom 0.2
** -1 [[User:DavidJanes]] I think hAtom Comments should be a separate spec
*** +1 to David's -1. [[User:TobyInk|TobyInk]] They're in a separate RFC, so should be separate to hAtom too. That said, it would be nice if hAtom had a clear, documented mechanism for creating extensions.
** +1 [[User:Singpolyma|Singpolyma]] Comments are the important "next step" for hAtom. The proposal I've seen that I most liked was embedding an hfeed in an hentry.
*** [[User:DavidJanes]] would you look to explicitly write out that proposal here (or in a new section); this is my preferred solution too, but there's another proposal on the table for doing this too

==== atom:category scheme ====
* {{OpenIssue}} 2007-06-01 raised by [http://theryanking.com/ Ryan King].
*# ''[[rel-tag#Tag_Spaces|rel-tag tagspaces]] should map to atom:category schemes''
*#* hAtom already defines how to map term and label. It seems that the tagspace can easily map to scheme
*# {{ToDo}} can we get a real-world example mapping of this? [[User:DavidJanes]]

=== 2006 ===
====Geo====
* {{OpenIssue}} 2006-02-03 raised by [[BrianSuda]]
** We can use the [[geo]] microformat in [[hatom]] to represent GeoRSS element
** +1 [[User:DavidJanes]] - this is just making explicit a particular composition. is it not? Also: if there's a geo in a hfeed (outside of hentry), should it be considered to apply to all entries?
** +1 [[User:Chris Cressman|Chris Cressman]]
* include in hAtom 0.2
** +1 [[User:DavidJanes]]
** +1 [[User:Chris Cressman|Chris Cressman]]

==== Relationship of rel-bookmark to url+uid ====
The concept of permalink is available in hCard and hCalendar as the classes url and uid. This combination matches the permalink semantics by indicating that the url should be derefenced to find a more dynamic or up-to-date version of the content, and that that url is a stable unique id that can be used to identify the content.

hAtom 0.1 uses rel-bookmark for the permalink concept. The current state of [[uid-brainstorming]] indicates that the [[hCard]] and [[hCalendar]] permalink concept is likely to be used in subsequent microformats. It may be important to reconcile hAtom with that trajectory. Possible reconcilliations include:

1) To leave things as they are. The two permalink concepts are to be kept separate.

2) Treat the two concepts as equivalent. Allow both in hAtom, and consider allowing both in other formats. eg <a rel="bookmark" href="http://example.com/"> would fill out uid and url values if they are not supplied explicitly.

3) Choose one over the other for hAtom and perhaps for future microformats also. "url uid" allows for some greater freedom (uid can be pointed at a non-url uid), but it is unclear at this stage whether that freedom is warranted or advisable to permit.

* include in hAtom 0.2
** -1 [[User:DavidJanes]] (let's wait for resolution elsewhere, also would need real world examples)
** -1 [[User:Singpolyma|Singpolyma]]

==== Datetime format (atom:<i>updated</i> and atom:<i>published</i>) ====
* 2006-05-23 raised by [[User:RobertBachmann|Robert Bachmann]]
** Atom requires the use RFC3339 datetimes, while hAtom 0.1 does not specify which datetime formats may be used.
*** ACCEPTED FAQ - hAtom references datetime-design-pattern, which discusses which date format to use
** 2009-07-20 [[User:DavidJanes]] {{ToDo}} is this moot? can we move this to resolved?

==== Feed <i>id</i> (atom:<i>id</i>) ====
* {{OpenIssue}} 2006-04-01 raised by [[User:RobertBachmann|Robert Bachmann]]
*# atom:<i>id</i> is required for atom:feed. Thus it should be available in hAtom to.

It is suggested the Feed permalink should be used as the feed ID, however a piece by Mark Pilgrim (http://diveintomark.org/archives/2004/05/28/howto-atom-id) makes arguments against using permalinks and in favour of Tag URIs.

* include in hAtom 0.2
** -1 [[User:DavidJanes]] not enough development of these ideas yes

==== Feed <i>permalink</i> (atom:<i>permalink</i>) ====
* {{OpenIssue}} 2006-04-01 raised by [[User:RobertBachmann|Robert Bachmann]]</small>
** I'm proposing the following rules:
**# a Feed Permalink element is identified by [[rel-bookmark]] at the feed level (inside a Feed element but not inside an Entry element)
**# a Feed <del>SHOULD</del><ins>MAY</ins> have a Feed Permalink
**# a Feed Permalink element represents the concept of an Atom link in a feed.
**# if the Feed Permalink is missing, use the URI of the page; if the Feed has an "id" attribute, add that as a fragment to the page URI
** 2006-04-03 [[User:ChrisCasciano|ChrisCasciano]] - I'm not sure that having a rel-boomkark-able link element at the feed level / to designate a feed in an html page separate for the other content is anything close to normal usage on the web, so I'd be very hesitant on suggesting this element "SHOULD" exist. I'm also curious when this element would link to anything but the current page (or some element on the current page) for this to be useful in the context of the HTML doc. I think taking the "id" on the feed is a more workable solution in most cases.
** 2006-04-03 [[User:RobertBachmann|Robert Bachmann]]: I've replaced "SHOULD" with "MAY".
** 2006-04-24 [[User:RobertBachmann|Robert Bachmann]]: Maybe we could simplify my proposal to:
*** "''Use the URI of the page; if the Feed has an "id" attribute, add that as a fragment to the page URI''"
*** IMO this would be good enough for at least 80% of the cases.
** 2006-04-12 [[User:DavidJanes]]: {{ToDo}} can we find an example of this in the wild and if so we should add it to the -examples page.
** [[User:Singpolyma|singpolyma]] 00:05, 13 Apr 2006 (PDT) : since the link is going to be pointing to the home page for the item wouldn't [[rel-home]] make more sense? That's what I'm using in the XOXO Blog Format and my reasoning was that if hAtom ever defined this rel=home made the most sense for what you would add, because the feed's link is not to a part of the site by to the home of the site.

* include in hAtom 0.2
** -1 [[User:DavidJanes]] not enough development of these ideas yes

==== Feed <i>updated</i> (atom:<i>updated</i>) ====
* {{OpenIssue}} 2006-04-01 raised by [[User:RobertBachmann|Robert Bachmann]]
** atom:<i>updated</i> is required for atom:feed. Thus it should be available in hAtom to. I'm proposing the following rules:
**# The Feed Updated element is identified by the class name <code>updated</code> at the feed level (inside a Feed element but not inside an Entry element)
**# If no element with the class name <code>updated</code> is present, use the youngest <code>updated</code> from the feed's entries.
** 2006-04-12 [[User:DavidJanes]] I like this. And the definition of "feed level"
** 2007-06-20 [[User:MikeKaply]] The "youngest" thing is a really bad idea. If a page has 100 hAtom entries, a parser would have to go through all 100 looking for a low date. That's crazy.
*** 2008-03-20 [[User:TobyInk]] Not crazy at all. I've just implemented an hAtom to Atom converter and I do precisely this. Most (useful) hAtom parsers will "go through all 100 entries" anyway, won't they? So why not look for the youngest updated date as part of that loop. The only slight annoyance is that in RFC 4287, the <atom:updated> element must occur before the first <atom:entry> element -- this is easily solved by inserting a placeholder <atom:updated> element, looping through the entries and then going back and filling in the date. This is really, really, '''not''' a difficult thing to implement.

* include in hAtom 0.2
** +0.5 [[User:DavidJanes]]

==== Feed <i>title</i> (atom:<i>title</i>) ====
* {{OpenIssue}} 2006-04-01 raised by [[User:RobertBachmann|Robert Bachmann]]
** atom:<i>title</i> is required for atom:feed. Thus it should be available in hAtom to. I'm proposing the following rules:
**# a Feed Title element is identified by the class name <code><del>entry</del><ins>feed</ins>-title</code>
**# a Feed SHOULD have an Feed Title
**# a Feed Title element represents the concept of an Atom feed title
**# if the Feed Title is missing, use
**#* <del>the first <code><h#></code> element in the Feed, or</del>
**#* the <code><title></code> of the page, or
**#* assume it is the empty string
** 2006-04-01 [[User:ChrisCasciano|ChrisCasciano]] - I think that the fall back to using the first h# on the page is dangerous.. depending on the pge it may be something that changes often (first h# is a post title) or is otherwise ambiguous. I would think using <code><title></code> before h# would be prefered if not the most common desire of the page author.
** 2006-04-05 [[User:RobertBachmann|Robert Bachmann]]: Okay. Deleted "the first <code><h#></code> element in the Feed, or"
** 2006-04-12 [[User:DavidJanes]] Note also in support of this decision that many blogs use <code><h#></code> to encode the date for a group of postings
** 2006-04-12 [[User:DavidJanes]]: why <code>entry-title</code> for the feed title. Why not <code>fn</code> or <code>feed-title</code>?
** 2006-04-12 [[User:RobertBachmann|Robert Bachmann]]: Sorry, this was a "copy & paste" mistake. Fixed now.
** 2007-02-26 [[User:MikeKaply|Mike Kaply]]: I think a feed title should be mandatory if an hfeed is present. If you have multiple feeds on a page, there is no way in a user interface to distinguish between different feeds.

==== Feed <i>author</i> and Entry author (atom:<i>author</i>) ====
* {{OpenIssue}} 2006-04-01 raised by [[User:RobertBachmann|Robert Bachmann]]
** I'm proposing the following rules for Feed author:
**# a Feed Author element is represented by class name <code>author</code> at the feed level (inside a Feed element but not inside an Entry element)
**# a Feed Author element represents the concept of a Atom author
**# a Feed Author element MUST be encoded in a [[hcard|hCard]]
**# a Feed Author element SHOULD be encoded in a <code><address></code> element
**# a Feed MAY have more than one Feed Author elements
**# if the Feed Author is missing
**#* find the [[algorithm-nearest-in-parent|Nearest In Parent]] <code><address></code> element(s) with class name <code>author</code> and that is/are a valid [[hcard|hCard]]
**#* otherwise <del>the Feed is invalid hAtom</del> <ins>there is no Feed Author</ins>
** I'm proposing the following rules for entry author:
**# an Entry Author element is represented by class name <code>author</code>
**# an Entry Author element represents the concept of an Atom author
**# an Entry Author element MUST be encoded in an [[hcard|hCard]]
**# an Entry Author element SHOULD be encoded in an <code><address></code> element
**#<del> If a Feed has no Feed author each Entry MUST have at least one Entry Author element</del>
**# <ins>If an Entry is enclosed by a Feed and this Feed has no Feed author, each Entry MUST have at least one Entry Author element. If an Entry is not enclosed by a Feed and has no Entry Author:
**#* find the [[algorithm-nearest-in-parent|Nearest In Parent]] <code><address></code> element(s) with class name <code>author</code> and that is/are a valid [[hcard|hCard]]
**#* otherwise the Entry is invalid hAtom</ins>
**# an Entry MAY have more than one Entry Author elements
** [[User:Singpolyma|singpolyma]] 00:11, 13 Apr 2006 (PDT) : feed should not be invalid hAtom if feed-level has no author -- it should be invalid if feed-level has no author AND one or more entries have no author. Also, one or more entries may be missing an author IF feed-level has an author.
** 2006-04-17 [[User:RobertBachmann|Robert Bachmann]]: I replaced "the Feed is invalid hAtom" with "there is no Feed Author"

==== Entry <i>id</i> (atom:<i>id</i>) ====
* {{OpenIssue}}2006-04-01 raised by [[User:RobertBachmann|Robert Bachmann]]
** atom:<i>id</i> is required for atom:entry. Thus it should be available in hAtom to. The Entry permalink should be used as the entry id.
** --[[User:Federico|Federico]] 19:52, 25 Apr 2006 (PDT): I would add "Only if the id attribute is not defined for the element that contains the entry". The id attribute can be a tag uri. If you use always use the Entry permalink as the entry id and the Atom feed uses tag uris, you would end with two different ids for the same entry.
** 2006-12-31 response by [[User:ComputerKid|Emanla Eraton]] No, it shouldn't be a permalink. It should be a "tag:" id for entries.
** 2007-06-06 [[RyanKing]] - the syntax of tag URIs and html id attributes are incompatible. HTML disallows forward-slash (/) in ids [http://www.w3.org/TR/html401/types.html#type-name], while tag URIs require them [http://www.faqs.org/rfcs/rfc4151.html].

==== Author ====
===== author as an hcard is too much to require =====
The following 3 items were extracted from the conversation starting on irc with [http://rbach.priv.at/Microformats-IRC/2006-03-24#T152248 logs available starting around here]

* [[User:Fil|Fil]] If, for example, you are programming an "aggregator" of news syndicated from many sources like in [http://sedna.spip.org/sedna/ Sedna], chances are that you don't control what "authors" look like; they can be nicely microformated (if coming from an mf-enabled system), but most probably they will be internally represented by a string that contains, in some random order, a name, and/or an email, and so on. If you want to pass on this information in an hAtom feed, you can't possibly reformat it to an hCard. But you still want to pass it on in a <div class="author"> element.
** [[Tantek]] I don't believe the "can't possibly" statement. Please provide a URL to a concrete example that you think you can't possibly reformat into an hCard so we can all take a look.
** [[User:ChrisCasciano|ChrisCasciano]] details of Fil's extraction [http://rbach.priv.at/Microformats-IRC/2006-03-24#T153453 in irc logs] including sting data passed to his app in the form of "Béatrice XXXXXXX beatrice.xxxxxx@@zzzzzzzzz.com"
** [[User:Fil|Fil]] the example url was given up there (Sedna); note that the author information comes from syndication links; nobody is going to edit them to outline what is the name, what is the email and so on, as everything is flowing through automatically... so here the "author" data is dirty, and will not be cleaned into an hCard. We can force it to be in an hCard but it will be meaningless if the source (original data) wasn't built on an mf-enabled software.

* [[pnhChris]] i don't disagree.. the field often comes from places too dumb to follow these rules well; even cases like wordpress that allow users to present their name 1 of 6 or 8 difference ways (from username to LF, FN) .. its not just writing a template to output as hatom at that point... you have to go further upstream where the string to be displayed is chosen .. I also think its pointless to have 10 vcards on the same page whose only data is a generic name like "Chris"
** [[Tantek]] 10 vcards that are the same is pointless yes, but identifying who the author of 10 posts are is not pointless - that's the difference.
** [[User:ChrisCasciano|ChrisCasciano]] Agreed, but I still have concerns that "author" in hAtom does not always make for good hCards, though the situations where it does is optimal. My comments in the conversation were old comments I've made before over concerns and hardships or the lack of desire to make crappy data more portable, in neither of these cases do I think my two comments alone provide reasons to make change from the hAtom 0.1 spec
***[[User:Phae|Frances]] - Just thought I'd mention a scenario I have where the author of an entry does make a pretty useless vCard - the author in each case is an entire team ("creative team", "technical department") etc., rather than a specific, identifiable, person. Some use may be regained when URL to specific team/information is included, in this circumstance.
****[[User:TobyInk]] - A vCard (thus an hCard) does not have to represent a person -- it could represent an organisation, or a department or team.
* [[User:Fil|Fil]] for the moment, to comply losely with hAtom 0.1, I will use <code><nowiki><span class="author"><span class="vcard"><span class="fn">My Name</span></span></span></nowiki></code> ; but it's not good
** [[Tantek]] You can actually simplify that (one fewer span) with: <code><nowiki><span class="author vcard"><span class="fn">My Name</span></span></nowiki></code>

* require author as [[hCard]] (i.e. no change from 0.1)
** +2 [[User:DavidJanes]]

==== Entry <i>source</i> (atom:<i>source</i>) ====
* raised by [[User:Kevin Marks|Kevin Marks]]
** When defining hAtom 0.1, atom:source was omitted. We should consider adding this back in as a useful element for providing citations of composite feeds.
*** 2009-07-20 [[User:DavidJanes]] {{ToDo}} we need an example of how this would look in the real world

== Other Questions and Issues ==
General comments, modeling issues, algorithm issues, should have issues, etc. go here.

=== Entry Updated Required? -- Blogger Issue ===
moved to [[hatom-brainstorming]]

=== 'MAY have multiple Feed elements' -- details and viability of multiple feeds ===
moved to [[hatom-brainstorming]]

== pre 0.1 issues ==
'''This section is more or less closed, as hAtom 0.1 is out the door. If there are open issues that you are championing that didn't make it into hAtom 0.1, move them up above to the hAtom 0.2 section'''

See: [[hatom-issues-pre-0.1]]

== Template ==
{{issues-format}}

== See Also ==
* [[hatom|hAtom]] - the draft proposal
* [[hatom-faq]] - knowledge base
* [[hatom-issues-resolved]]
* [[blog-post-brainstorming]]
* [[blog-post-formats]]
* [[blog-post-examples]]
* [[blog-description-format]] - how to describe a blog (as opposed to the individual entries, which is what we're doing here)
* [[mfo-examples]]
* [[naming-principles]]

html5

2010-01-19T19:23:56Z

BenWard: h1 -> entry-title

<entry-title>Microformats in HTML 5</entry-title>

''This page is to document '''future''' use of microformats in [http://www.w3.org/html/wg/html5 HTML 5]. None of the items documented are supported now, and may change upon proper development within the microformats community, or changes in the HTML 5 specification. This page is to track HTML5 enabled enhancements to microformats, and issues that HTML5 raises. It may be used to track issues which we need to push back into the HTML 5 development process.''

If there are things that Microformats would like to mark up that aren't handled by HTML5 explicitly, please let the WHATWG know, so we can improve HTML5. This is how <code>time</code> came to be, for instance.

==New features in HTML5==

=== time element ===
'''<code>time</code> element for representing date times'''. In HTML5, the machine form of datetimes can be represented natively. It should be possible to replace the date-time design pattern with native HTML.
* <code>time</code> takes an optional <code>pubdate</code> attribute, to indicate the publication date of an <code>article</code>. Synonymous with [[hAtom]] <code>published</code>, may imply [[hAtom]] <code>updated</code>, may imply [[hReview]] <code>dtreviewed</code>, may imply [[hListing]] <code>dtlisted</code>

=== article element ===
'''<code>article</code>''' element for major, independent compositions of content within a page. Perhaps synonymous with [[hAtom]] <code>hentry</code>. Could be parsed as <code>hentry</code> within explicit <code>hfeed</code> blocks?

=== microdata ===
'''[[microdata]]'''. HTML5 provides a set of attributes and associated DOM APIs for extracting data from web pages.
* <code>itemprop</code> attribute is a more specific version of <code>class</code>, for field names
* <del><code>subject</code> attribute allows semantically linking within the page. Conceptually similar to the [[include-pattern]].</del>
* <code><itemref refid="x" /></code> allows semantically linking within the page. Conceptually similar to the [[include-pattern]].
* <code>content</code> attribute on the <code>meta</code> element can be used to invisibly include data. Conceptually similar to the [[value-class-pattern]].
* <code>itemscope</code> attribute identifies blocks to be marked as structure data. Conceptually similar to the [[mfo]] brainstorming?
* <code>itemtype</code> attribute to specify the type for an item (for example: <code><nowiki>itemtype="http://microformats.org/profile/hcard"</nowiki></code>)

==== microdata vocabularies ====
* [http://dev.w3.org/html5/mdvcard/ microdata vCard] - use [[hCard]] instead, taking into account the [[hcard-faq|hCard FAQ]] and [[hcard-issues-resolved|resolved]]+[[hcard-issues-closed|closed issues]]. hCard 1.0.1 (under development) is incorporating these errata. Avoid the "microdata vCard" vocabulary as it is an out-of-date fork/snapshot of hCard.
* [http://dev.w3.org/html5/mdvevent/ microdata vEvent] - use [[hCalendar]] instead, taking into account the [[hcalendar-faq|hCalendar FAQ]] and [[hcalendar-issues-resolved|resolved]]+[[hcalendar-issues-closed|closed issues]]. hCalendar 1.0.1 is incorporating these errata. Avoid the "microdata vEvent" vocabulary, as it is an out-of-date fork/snapshot of hCalendar's vevent root class name and applicable properties.
* [http://dev.w3.org/html5/mdwork/ microdata Licensing Works] - see also [[licensing-brainstorming]]

=== data attributes ===
'''<code>data-</code> naming convention for tag attributes'''. the draft specification states that any attribute that starts with "data-" will be treated as a storage area for private data.
* Note that the data-* stuff is explicitly <em>not</em> for microformats. Those attributes are defined in such a way that browsers will never do anything special with them, ever. They are intended for script authors to have a space in which they can play without ever clashing with anything the browser does. There may be some cases of private [[poshformats]] that are never intended for interchange that may be used in data-* attributes.

== Current microformat compatibility ==
There seems to be no issue with current implementation of the following microformats in HTML 5:
* [[hcard]]
* [[xfn]]

== Requests ==
* "how to use with HTML5" sections that include (a) microformats examples that use [[HTML5]], and (b) microformats parsing details that specify what to do (if anything special is required) with HTML5 elements (e.g. how to parse the <code>time</code> element for dates and times for microformats). See (and add to if necessary) :
** [[hcard-brainstorming#how_to_use_with_HTML5|hCard brainstorming - how to use with HTML5]]
** [[hcalendar-brainstorming#how_to_use_with_HTML5|hCalendar brainstorming - how to use with HTML5]] e.g. hCalendar with the <code>time</code> element
** [[citation-brainstorming#how_to_use_with_HTML5|citation brainstorming - how to use with HTML5]]
** if nothing special is required for HTML5, then after performing the analysis, that should be noted as well, for the purpose of clarity.

==Issues==
<div class='discussion issues'>
* '''The <code>rev</code> attribute has been removed'''. In HTML5, <code>rel</code> and <code>rev</code> are no-longer paired, and the <code>rel</code> attribute nolonger describes the direction of a relationship. Microformats which use <code>rev</code> will need to use <code>rel</code> instead.
** Or something like data-rev="vote-for"
*** As above, <code>data-</code> attributes are for application-context functionality, ''not'' shared vocabularies. Further, the HTML5 specification makes <code>rel</code> the correct attribute to use, regardless of direction, through the changed specification. --[[User:BenWard|BenWard]] 17:53, 12 May 2009 (UTC)
* '''The <code>profile</code> attribute has been removed'''. In HTML, the <code>profile</code> attribute from the <code>head</code> has been removed, with no direct replacement. This causes issues for GRDDL support. It's been suggested that profile URLs be represented in <code>link</code> elements instead, or even as a custom HTTP header. See [[grddl]] and [[profile-uris]]
** See [[rel-profile]] which is the replacement for the profile attribute. [[User:Tantek|Tantek]] 23:24, 5 November 2009 (UTC)
* '''Microdata <code>itemprop</code> duplicates <code>class</code> data'''. the new attribute itemprop is designed to hold some meaningful data about an element, but class already exists to hold this data. Unsure of reasons why itemprop required?
** This is because microdata is designed to be generically parsable, even when the parser does not understand the vocabulary. As such, property names have to be on an explicit attribute, not shared with other, non-data classnames. --[[User:BenWard|BenWard]] 21:12, 4 September 2009 (UTC)
</div>

== see also ==
* [[HTML3]]

microformateers

2010-01-12T23:01:01Z

BenWard: Documented my searches, added automated-bot spam blacklist, few other tweaks.

<entry-title>Microformateers</entry-title>

[http://twitter.com/microformateers Microformateers] is a Twitter account providing quick answers to people's questions about microformats. Twitter is full of people with short queries about syntax, or remarking upon things they've read about microformats. Microformats.org already runs the [http://twitter.com/microformats @microformats] account for pushing news and announcements, but the microformateers effort is about responding.

==What is this?==

Microformateers is a single Twitter account, shared between a number of individual contributors. They monitor Twitter searches for mentions of microformats and related terms, and respond directly and publicly to people's lazy-web questions, ideally within 140 characters. Where longer code examples are required, code snippets areposted to [http://gist.github.com gist].

==Who are the microformateers?==

<div class="vcard">
Because of the mechanics of Twitter (a single account, shared with a single password) it is not possible for the <span class="org">Microformateers</span> account to be open to all. '''The following agents are currently ‘on duty’''':

<div class="agent vcard">
===<span class="fn">Frances Berriman</span> (<span class="nickname">^FB</span>)===

https://s3.amazonaws.com/twitter_production/profile_images/58225171/17464024_N00_normal_bigger.jpg

* <span class="url">http://twitter.com/phae</span>
* [[User:Phae]]
</div>

<div class="agent vcard">
===<span class="fn">Tantek Çelik</span> (<span class="nickname">^T</span>)===

http://a1.twimg.com/profile_images/76685310/ca-sci-t_bigger.jpg

* <span class="url">http://twitter.com/t</span>
* [[User:Tantek]]
</div>

<div class="agent vcard">
===<span class="fn">Jeremy Keith</span> (<span class="nickname">^??</span>)===

https://s3.amazonaws.com/twitter_production/profile_images/65971001/avatar_bigger.jpg

* <span class="url">http://twitter.com/adactio</span>
* [[User:Adactio]]
</div>

<div class="agent vcard">
===<span class="fn">Kevin Marks</span> (<span class="nickname">^KM</span>)===

http://a1.twimg.com/profile_images/130885696/kevin300am-1_bigger.jpg
* <span class="url">http://twitter.com/kevinmarks</span>
* [[User:Kevin Marks]]
</div>

<div class="agent vcard">
===<span class="fn">Drew McLellan</span> (<span class="nickname">^??</span>)===

https://s3.amazonaws.com/twitter_production/profile_images/124177936/peek_bigger.jpg

* <span class="url">http://twitter.com/drewm</span>
* [[User:DrewMcLellan]]
</div>

<div class="agent vcard">
===<span class="fn">Matthias Pfefferle</span> (<span class="nickname">^MP</span>)===

http://a1.twimg.com/profile_images/481055128/b36983a5651df2c413e264ad4d5cc1a1.jpeg_bigger.jpg

* <span class="url">http://twitter.com/pfefferle</span>
* [[User:Pfefferle]]
</div>

<div class="agent vcard">
===<span class="fn">Ben Ward</span> (<span class="nickname">^BW</span>)===

https://s3.amazonaws.com/twitter_production/profile_images/150824912/2009-200_bigger.jpg

* <span class="url">http://twitter.com/benward</span>
* [[User:BenWard]]
</div>

</div>


==Response Process==

* Microformateers is a single Twitter identity shared between an appropriate number of trusted individuals
* When you have a free moment or the mood takes you, monitor searches for microformats terms (there's one saved in the account already)
* When you find a question to be answered, respond using the [http://twitter.com/microformateers @microformateers account]
* If you need to provide code, stick it on [http://gist.github.com gist.github.com] (or similar pastebin service) and link to it. Gist is good though, as it ties into the Github community as well.
* When you answer someone's question, add the tweet to the [http://twitter.com/microformateers/favorites @microformateers’ favorites], that we avoid inundating questioners with duplicate answers. (Most quality Twitter clients, as well as the Twitter website itself, indicate which tweets you have ‘faved’ inline.)
* Unless absolutely impossible, save 3 characters to sign the tweet with a <kbd>^XX</kbd>, using your initials, so people can reference you personally as well. (e.g. ^BW, ^T, ^JK, ^FB… something identifiable.) People can refer to this wiki page to look-up the individual. <code>^AB</code> is an existing convention on Twitter for this purpose, used by software such as Co-Tweet.
* Only use the @microformateers for answering questions. Don't use it to post or re-tweet general microformats information; that purpose is already served by @microformats.

==Searches==

Please document the searches you use to track microformats topics. For searches that exclude individual Twitter accounts, ''do not'' include any personal user blacklists.

* <code>@microformats OR @microformateers OR microformat OR microformats OR uformats OR mformats OR µformats OR µf</code>
* <code>hCard OR hCalendar OR hAtom OR hAudio OR hReview OR hResume OR hListing OR hRecipe -@hreview -#hreview</code> — covers major microformats, excludes the "@hreview" bot and hashtag (a service for creating reviews of items over Twitter.)
* <code>microdata</code> — keep an eye on the closely related microdata work from HTML5.

===Bots to Exclude===

Depending on the tool you use to track Twitter topics, you may need to add exclusions to the above searches to filter out spam; there are some automated bots on Twitter that produce odd spam. Remember that the Twitter Search API doesn't account for the blocklist of the @microformateers account.

Use this list for obscure, automated bots only, or users who are using microformat terms for non-web topics and generating collisions. ''Do not'' use this list for Twitter users that you personally disagree with or find irritating; excluding people from searches is a personal matter for individual agents, never group policy.

* @library2 - “Library 2.0 Idea Generator -- a new idea every 1,800 seconds”. A bot which generates Web 2.0 satire from a dictionary of keywords, one of which is "microformats".

==Interested List==

If you're interested in becoming an agent for the microformateers, please add your name to the list below. There are a couple of constraints on this system: First is trust and security, simply because Twitter's account model requires sharing the same master password for the @microformateers account between all participants; we have to be conservative with proliferation. The second issue is meeting volume of demand. At present, we think that 4/5 agents is about the right number to be involved given the volume of questions and content that come through Twitter. But, as agents come and go, or as question demand increases we'll refer to this list. Thanks. (Technical solutions to make sharing Twitter accounts safer and accountable are also up for future consideration.) —[[User:BenWard|BenWard]] 21:31, 26 September 2009 (UTC)

* [[User:EdwardOConnor|Ted]]
** +1 [[User:Tantek|Tantek]] 21:18, 15 October 2009 (UTC)
* [[User:EmilyLewis|Emily Lewis]]
** +1 [[User:BenWard|Ben]] 2010-01-12

User:BenWard/drafts/hcard

2009-12-26T22:51:07Z

BenWard: First pass. Restructured the property listing, redid the intro.

<entry-title>hCard 1.0 — BenWard Edition</entry-title>
''This page is a draft reworking on the hCard specification by Ben Ward. It is an attempt to better present the spec to make it easier to understand and more complete. You should not refer to this document or work from it. See the [[hcard|hCard Specification]].''

<dfn>hCard</dfn> is a simple, open, distributed format for representing people, companies, organizations, and places, using a 1:1 representation of vCard ([[rfc-2426|RFC2426]]) properties and values in [[semantic-xhtml|semantic HTML or XHTML]]. hCard is one of several open [[microformats|microformat]] standards suitable for embedding in HTML, XHTML, Atom, RSS, and arbitrary XML.

'''Want to get started with writing an [[hcard|hCard]]?''' Use the [http://microformats.org/code/hcard/creator hCard creator] to write up some contact information and publish it, or follow the [[hcard-authoring|hCard authoring tips]] to add hCard markup to your current contact page.

<div class="vcard">
; <span class="role">Editor</span>
: <span class="fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="url">http://tantek.com/</span>, and before at [http://technorati.com Technorati, Inc.], and at [http://microsoft.com/ Microsoft Corporation])
</div>
; Authors: [http://tantek.com/ Tantek Çelik] (affiliations above)
: <span class="vcard"><span class="fn">[[User:Brian|Brian Suda]]</span> (<span class="url">http://suda.co.uk/</span>)</span>
: <span class="vcard"><span class="fn">[[User:BenWard|Ben Ward]]</span> (<span class="url">http://benward.me/</span>)</span>
; Acknowledgments: See [[hcard#Inspiration_and_Acknowledgments|acknowledgments]].

[[hcard#Copyright|copyright]] and [[hcard#Patents|patents]] statements apply.

== Status ==

''hCard is a microformats.org specification.''

=== Available languages ===

The English version of this specification is the only normative version. For translations of this document see the [[#translations]] section.

=== Feedback, Errata and Updates ===

* Public discussion on hCard takes place on [[hcard-feedback]], the [[irc|#microformats irc channel]] on irc.freenode.net, and [http://microformats.org/discuss/mail/microformats-discuss/ microformats-discuss mailing list].
* Known errors and issues in this specification are corrected on [[hcard-issues-resolved|resolved issues]] and [[hcard-issues-closed|closed issues]] pages.
* New issues must be documented on [[hcard-issues|issues]].

== Introduction and Purpose==

Across the web—on blogs, newspapers, and discussion forums—people identify themselves by name, discuss friends, family and colleagues, and reference businesses and places. By adding structured mark-up to their web pages, these writers and publishers can refer to people, organizations and places in such a way that software (spiders, aggregators and web browsers) can extract this information, transform it, or expose it to users in useful ways.

This specification introduces the <dfn>hCard</dfn> format, a 1:1 representation of the properties and values of the vCard standard ([[rfc-2426|RFC2426]]), in semantic HTML. hCard enables applications to retrieve information directly from web pages, without referencing a separate file.

{{rfc-2119-intro}}

== Format ==

=== In General ===

The vCard standard ([[rfc-2426|RFC2426]]) forms the basis of hCard.

hCard uses vCard object, property and value names in lowercase as class names, and maps the nesting of vCard objects to nested HTML elements.

=== Root Class Name ===

The root class name for an hCard is <code>vcard</code>. An element with a class name <code>vcard</code> is the root node of an <dfn>hCard</dfn> object.

=== Properties and Sub-properties ===

The properties of an hCard are represented by elements inside the hCard, mapped to the vocabulary using the <code>class</code> attribute. The content of the an element with a class name of an hCard property, represents the value of that property. Some properties have sub-properties; sub-properties are represented by elements nested within a parent property element.

=== The hCard Vocabulary ===

Required fields are noted as such, but note that some required properties can be implied by special optimization patterns (see below.)

; '''<code>fn</code>'''
: ''Required''
: The ''formatted-name'' of the hCard object.
; '''<code id="property-list-n">'''n'''<sup class="footnote">[[#note1|1]]</sup></code>'''
: ''Required''
: A person's name
:; Sub-properties of <code>n</code>:
:: <code>family-name</code>
:: <code>given-name</code>
:: <code>additional-name</code>
:: <code>honorific-prefix</code>
:: <code>honorific-suffix</code>
; <code>adr</code>
: A postal address
:; Sub-properties of <code>adr</code>
:: <code>post-office-box</code>
:: <code>extended-address</code>
:: <code>street-address</code>
:: <code>locality</code>
:: <code>region</code>
:: <code>postal-code</code>
:: <code>country-name</code>
:: <code>type</code>
::; <code>label</code>
::: A unstructured form of an address, as it would be presented on an address label. You can also use <code>label</code> to mark up entire addresses in situations where you do not have structured address data available.
; <code>agent</code>
: Another person (nested hCard) authorized to represent this first hCard. For instance, a secretary or PR contact.
; <code>bday</code>
: The birth date of the the entity represented by this hCard
; <code>category</code>
: Arbitrary keywords that may group this hCard with others. See also: [[rel-tag|tagging]].
; <code>class</code>
: WHAT IS THIS?
; <code>email</code>
: An email address
: An hCard may contain multiple <code>email</code> properties.
:; Sub-properties of <code>email</code>
:: <code>type</code>
::; <code>value</code>
::: ''Required.''
::: Where no sub-properties are specified for <code>email</code>, <code>value<code> is implied.
; geo
: Decimal geographic co-ordinates representing the current location of the entity represented by the hCard.
:; Sub-properties of <code>geo</code>
:: <code>latitude</code>
:: <code>longitude</code>
: See also: [[geo|Geo microformat]]
; <code>key</code>
; <code>logo</code>
: A logo graphic associated with this entity. e.g. the logo graphic of a business, or an avatar associated with a discussion-board user.
; <code>mailer</code>
; <code>nickname</code>
:
; <code>note</code>
; <code>org</code>
: The name and unit of the organisation for this hCard.
: If no sub-properties are specified, <code>organization-name</code> is implied.
:; Sub-properties of <code>org</code>
:: <code>organization-name</code>
:: <code>organization-unit</code>
; <code>photo</code>
: A photograph of the entity represented by this hCard.
; <code>rev</code>
: The date (and optionally time) in ISO format that the hCard was last revised.
; <code>role</code>
: The occupational role of the person represented by this hCard.
; <code>sort-string</code>
; <code>sound</code>
; <code id="property-list-tel">tel<sup class="footnote">[[#note2|2]]</sup></code>
:; Sub-properties of <code>tel</code>
:: <code>type</code>
:: <code>value</code>
; <code>title</code>
: The job-title of the person represented by this hCard
; <code>tz</code>
: The time-zone the person represented by this hCard is currently located in.
; <code>uid</code>
: A unique identifier associated with this entity
; <code>url</code>
: A URL associated with this entity.
: There may be multiple URL properties on an hCard object.

=== Property Notes ===

<span id="note1">[[#property-list-n|1. ^]]</span>: The 'n' property is {{optional}} if any [[hcard#Implied_.22n.22_Optimization|implied 'n' optimization rules]] are in effect.<br />
<span id="note2">[[#property-list-tel|2. ^]]</span>: tel - Authors {{may}} follow the [http://en.wikipedia.org/wiki/E.123 E.123] standard for writing values of telephone numbers. Letter values (e.g. +1-555-FORMATS) {{must}} be converted to numbers. Use an <code>abbr</code> to display letters and provide a numerical value simultaneously, e.g. <code><nowiki><abbr title="+15553676287">+1-555-FORMATS</abbr></nowiki></code>.

=== Singular vs. Plural Properties ===
Singular properties: 'fn', 'n', 'bday', 'tz', 'geo', 'sort-string', 'uid', 'class', 'rev'. For properties which are singular, the first descendant element with that class {{should}} take effect, any others being ignored.

All other properties {{may}} be plural. Each class instance of such properties creates a new instance of that property.

=== Human vs. Machine readable ===
The human visible text contents of an element for a property represents the value of that property, with a few exceptions:

If an <code><abbr></code> element is used for a property, then the '<code>title</code>' attribute (if present) of the <code><abbr></code> element is the value of the property, instead of the contents of the element, which instead provide a more human presentable version of the value.

If an <code><a></code> element is used for one or more properties, it {{must}} be treated as follows:
# For the 'photo' property and any other property that takes a URL as its value, the <code>href="..."</code> attribute provides the property value.
# For other properties, the element's content is the value of the property.

If an <code><img></code> element is used for one or more properties, it {{must}} be treated as follows:
# For the 'photo' property and any other property that takes a URL as its value, the <code>src="..."</code> attribute provides the property value.
# For other properties, the <code><img></code> element's '<code>alt</code>' attribute is the value of the property.

If an <code><object></code> element is used for one or more properties, it {{must}} be treated as follows:
# For the 'photo' property and any other property that takes a URL as its value, the <code>data="..."</code> attribute provides the property value.
# For other properties, the element's content is the value of the property.

=== Value excerpting ===
Sometimes only part of an element which is the equivalent for a property is used for the value of the property. This typically occurs when a property has a subtype, like 'tel'. For this purpose, the special class name "<code>value</code>" is used to excerpt out the subset of the element that is the value of the property. E.g. here is an hCard fragment for marking up a home phone number:<br />

vCard:
<pre><nowiki>
TEL;TYPE=HOME:+1.415.555.1212
</nowiki></pre>

hCard:
<pre><nowiki>
<span class="tel">
<span class="type">home</span>:
<span class="value">+1.415.555.1212</span>
</span>
</nowiki></pre>

This hCard fragment could be displayed as:

<div style="border: thin dashed black; width: 95%; padding: .5em 1em;">
<span class="tel">
<span class="type">home</span>:
<span class="value">+1.415.555.1212</span>
</span>
</div>



=== Property Exceptions ===
vCard has several properties which either do not make sense on, or are already implied within the context of a web page. This section explains what to (not) do with them.

# vCard's '''NAME''', '''PROFILE''', '''SOURCE''', '''PRODID''', '''VERSION''' properties are defined in Sections 2.1.2, 2.1.3, 2.1.4, 3.6.3, 3.6.9 of [[rfc-2426|RFC2426]]. Content publishers {{must-not}} use these properties in their hCards, and as such, hCard consumers/parsers {{must}} IGNORE these properties if they are found within an hCard. Instead. hCard to vCard converters {{should}} use the title of the page where the hCard is found (e.g. the <code><title></code> element in HTML documents) to construct the NAME property, {{may}} output a PROFILE value of "<code>VCARD</code>" per [[rfc-2426|RFC2426]], {{should}} use the URL of the page where the hCard is found to construct the SOURCE property (e.g. perhaps as a parameter to a URL/service that converts hCards to vCards), for an output vCard stream (e.g. a .vcf file). Only services/applications that output actual vCards should write the PRODID property, with the product identifier for said service/application. Similarly, only such services/applications should write the VERSION property, with the value "3.0" (without quotes) per [[rfc-2426|RFC2426]] Section 3.6.9.

=== Organization Contact Info ===
If the "FN" and "ORG" (organization) properties have the exact same value (typically because they are set on the same element, e.g. class="fn org"), then the hCard represents contact information for a company, organization or place and {{should}} be treated as such. In this case the author also {{must-not}} set the "N" property, or set it (and any sub-properties) explicitly to the empty string "". Thus parsers {{should}} handle the missing "N" property, in this case by implying empty values for all the "N" sub-properties.

=== Implied "n" Optimization ===
Although vCard requires that the "N" property be present, the authors of the vCard specification ([[rfc-2426|RFC2426]]) themselves do not include "N" properties in their vCards near the end of the spec (p.38). This apparent contradiction can be resolved by simply allowing the "FN" property to imply "N" property values in typical cases provided in the spec. We do so explicitly in hCard.

If "FN" and "ORG" are not the same (see previous section), and the value of the "FN" property is exactly two words (separated by whitespace), and there is no explicit "N" property, then the "N" property is inferred from the "FN" property. For "FN"s with either one word see below, and for three or more, the author {{must}} explicitly markup the "N", except for the organization contact info case, [http://microformats.org/wiki/hcard#Organization_Contact_Info see above] for that.

# The content of "FN" is broken into two "words" separated by whitespace.
# The ''first'' word of the "FN" is interpreted as the "given-name" for the "N" property.
# The ''second/last'' word of the "FN" is interpreted as the "family-name" for the "N" property.
# Exception: If the first word ends in a "," comma OR if the second word is a single character (optionally followed by a period "."), then the first word (minus the comma at the end if any) is interpreted as the "family-name" and the second word is interpreted as the "given-name".

This allows simplification in the typical case of people stating:
* given-name (space) family-name
* family-name (comma) given-name
* family-name (comma) given-name-first-initial
* family-name (space) given-name-first-initial (optional period)

=== Implied "nickname" Optimization ===
Due to the prevalence of the use of nicknames/handles/usernames in actual content published on the Web (e.g. authors of [[hReview|reviews]]), hCard also has an implied "nickname" optimization to handle this.

Similar to the implied "n" optimization, if "FN" and "ORG" are not the same, and the value of the "FN" property is exactly one word, and there is no explicit "N" property, then:

# The content of the "FN" {{must}} be treated as a "nickname" property value.
# Parsers {{should}} handle the missing "N" property by implying empty values for all the "N" sub-properties.

Though parsers {{must}} follow the implied nickname optimization, publishers {{should}} explicitly indicate the "nickname" even in this case, e.g.:

<pre><nowiki>
<span class="vcard">
<span class="fn nickname">daveman692</span>
</span>
</nowiki></pre>

The hCard {{may}} have additional explicit "nickname" property values in addition to the implied nickname.

=== Implied "organization-name" Optimization ===
The "ORG" property has two subproperties, organization-name and organization-unit. Very often authors only publish the organization-name. Thus if an "ORG" property has no "organization-name" inside it, then its entire contents {{must}} be treated as the "organization-name".

=== Tags as Categories ===
Categories in hCard {{may}} be represented by tags with [[rel-tag]]. When a category property is a rel-tag, the tag (as defined by rel-tag) is used for that category.

=== type subproperty values ===
The 'type' subproperty in particular takes different values depending on which property it is a subproperty of. These 'type' subproperty values are case-INSENSITIVE, meaning "Home" is the same as "home", as well as multivalued, e.g. a tel can be home and preferred:

vCard:
<pre><nowiki>
TEL;TYPE=HOME,PREF:+1.415.555.1212
</nowiki></pre>

hCard:
<pre><nowiki>
<span class="tel"><span class="type">Home</span> (<span class="type">pref</span>erred):
<span class="value">+1.415.555.1212</span>
</span>
</nowiki></pre>

This could be displayed as:

<div style="border: thin dashed black; width: 95%; padding: .5em 1em; ">
<span class="tel"><span class="type">Home</span> (<span class="type">pref</span>erred):
<span class="value">+1.415.555.1212</span>
</span>
</div>

==== type with unspecified value ====
When the type of a property is specified, and there is no explicit value specified, then everything in the property except for the type is considered the value of the property. E.g.

<pre><nowiki>
<span class="tel"><span class="type">Home</span> +1.415.555.1212</span>
</nowiki></pre>

is equivalent to:

<pre><nowiki>
<span class="tel"><span class="type">Home</span><span class="value"> +1.415.555.1212</span></span>
</nowiki></pre>

And thus the type is "home" and the value is "+1.415.555.1212".

==== adr tel email types ====
The following lists are ''informative''. See [[rfc-2426|RFC2426]] sections 3.2.1 ADR, 3.3.1 TEL, and 3.3.2 EMAIL respectively for normative type values. They are repeated here for convenience. Default type subproperty value(s) is(are) first in each list and indicated in ALL CAPS. types may be multivalued.

* adr type: INTL, POSTAL, PARCEL, WORK, dom, home, pref
* tel type: VOICE, home, msg, work, pref, fax, cell, video, pager, bbs, modem, [http://flickr.com/photos/tags/carcellphone/ car], isdn, pcs
* email type: INTERNET, x400, pref

=== Profile ===
The hCard <span id="XMDP_Profile">XMDP profile</span> is at http://microformats.org/profile/hcard

Content that uses hCard {{should}} reference this profile, e.g.
<source lang=html4strict>
<head profile="http://microformats.org/profile/hcard">
</source>
or
<source lang=html4strict>
<link rel="profile" href="http://microformats.org/profile/hcard">
</source>
or
<source lang=html4strict>
This content uses <a rel="profile" href="http://microformats.org/profile/hcard">hCard</a>.
</source>
Content may combine the above methods as well.

=== Parsing Details ===

See [[hcard-parsing|hCard parsing]].

== Examples ==

This section is informative.

=== Sample vCard ===

Here is a sample vCard:

<pre><nowiki>
BEGIN:VCARD
VERSION:3.0
N:Çelik;Tantek
FN:Tantek Çelik
URL:http://tantek.com/
END:VCARD
</nowiki></pre>

and an equivalent in hCard with various elements optimized appropriately. See [[hcard-example1-steps| hCard Example 1]] for the derivation.

<pre><nowiki>
<div class="vcard">
<a class="url fn" href="http://tantek.com/">Tantek Çelik</a>
</div>
</nowiki></pre>

This hCard might be displayed as:
<div style="border: thin dashed black; width: 95%; padding: .5em 1em;">
[http://tantek.com/ Tantek Çelik]
</div>

Note: The version information is unnecessary in hCard markup directly since the version will be defined by the profile of hCard that is used/referred to in the 'profile' attribute of the <head> element.

===Live example===

Here is [http://www.commerce.net/ Commercenet]'s contact details, as a live hCard which will be detected, on this page, by microformat parsing tools:

<div class="vcard">
<div class="fn org">'''CommerceNet'''</div>
<div class="url">'''<nowiki>http://www.commerce.net/</nowiki>'''</div>
<div class="adr">'''<span class="type">Work</span>:'''
<div class="street-address">'''169 University Avenue'''</div>
<span class="locality">'''Palo Alto'''</span>, <span class="region">'''CA'''</span>  <span class="postal-code">'''94301'''</span>
<div class="country-name">'''USA'''</div>
</div>
<div class="tel">'''<span class="type">Work</span> +1-650-289-4040'''</div>
<div class="tel">'''<span class="type">Fax</span> +1-650-289-4041'''</div>
<div>'''Email <span class="email"><nowiki>info@commerce.net</nowiki></span>'''</div>
</div>

The mark-up, emboldening omitted for clarity, with the following semantic improvements:
* <code>abbr</code> to expand abbreviations
* hyperlinking the org name with the url

<pre><nowiki>
<div class="vcard">
<a class="fn org url" href="http://www.commerce.net/">CommerceNet</a>
<div class="adr">
<span class="type">Work</span>:
<div class="street-address">169 University Avenue</div>
<span class="locality">Palo Alto</span>,
<abbr class="region" title="California">CA</abbr>  
<span class="postal-code">94301</span>
<div class="country-name">USA</div>
</div>
<div class="tel">
<span class="type">Work</span> +1-650-289-4040
</div>
<div class="tel">
<span class="type">Fax</span> +1-650-289-4041
</div>
<div>Email:
<span class="email">info@commerce.net</span>
</div>
</div>
</nowiki></pre>

=== More Examples ===
See [[hcard-examples|hCard examples]] for more examples, including all examples from vCard [[rfc-2426|RFC2426]] converted into hCard.

== Examples in the wild ==
This section is '''informative'''. The number of hCard examples in the wild has expanded far beyond the capacity of being kept inline in this specification. They have been moved to a [[hcard-examples-in-wild|separate page]].

See [[hcard-examples-in-wild|hCard Examples in the wild]].

== Implementations ==
This section is '''informative'''. The number of hCard implementations has also expanded beyond the capacity of keeping them inline. They have been moved to a [[hcard-implementations|separate page]].

See [[hcard-implementations|hCard Implementations]].

== Articles ==
This section is <strong>informative</strong>. For <span id="Further_Reading">further reading</span> on hCard see [[hcard-articles]].

==Buttons==
You can use these buttons on pages with hCards. See [[buttons#hCard]] for any recent additions.

* http://www.crowley.nl/images/hcard.png (mirror: http://www.davidjanes.com/images/mf_hcard.png)
* http://rbach.priv.at/2006/buttons/hcard.png
* http://www.boogdesign.com/images/buttons/microformat_hcard.png
* CSS-powered button, as evidenced at [http://re-run.com/about/microformat-badges microformat badges @ re-run]

== Copyright ==
Per the public domain release on the authors' user pages ([[User:Tantek|Tantek Çelik]], [[User:Brian|Brian Suda]]) this specification is released into the public domain.

{{MicroFormatPublicDomainContributionStatement}}

== Patents ==
{{MicroFormatPatentStatement}}

== References ==
=== Normative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://www.ietf.org/rfc/rfc2426.txt vCard RFC2426]
* [http://www.itu.int/rec/T-REC-E.123-200102-I/en ITU recommendation E.123] format of telephone numbers (chargeable document)
* [[rfc-2119|RFC 2119]]

=== Informative References ===
This section is '''informative'''.
* [[hcard-history|hCard history]]
** [http://wiki.oreillynet.com/foocamp04/index.cgi?SimpleSemanticFormats FOO Camp 2004 Simple Semantic Formats presentation, 2004-09-10]
** [http://tantek.com/log/2004/09.html#hcard hCard term introduced and defined on the Web, 2004-09-30]
** Contributed from http://developers.technorati.com/wiki/hCard 2005-06-20
* [http://www.dante.net/np/ds/osi/9594-6-X.520.A4.ps X.520 in Postscript] ([http://72.14.253.104/search?q=cache:FjqzsFu4h20J:www.dante.net/np/ds/osi/9594-6-X.520.A4.ps HTMLization courtesy of Google Cache]) - vCard refers to ROLE as being "based on the X.520 Business Category explanatory attribute".
* [http://www.w3.org/2002/12/cal/rfc2426 HTML reformatted version of RFC2426]
* [http://w3.org/TR/REC-CSS1 CSS1]
* [http://www.w3.org/TR/xhtml11 XHTML 1.1]
* [http://en.wikipedia.org/wiki/E.123 Wikipedia summary of ITU-T Recommendation E.123] - for "TEL" values.
* [http://www.imc.org/pdi/ Internet Mail Consortium Personal Data Interchange vCard and vCalendar]
* [[iso-8601|ISO8601]]

==== Specifications That Use hCard ====
* [[adr]]
* [[geo]]
* [[hcalendar|hCalendar]]
* [[hreview|hReview]]

==== Similar Work ====
This section is '''informative'''.
* [http://www.intertwingly.net/wiki/pie/PaceBetterPersonElement Atom PaceBetterPersonElement]
* [http://www.jabber.org/jeps/jep-0054.html JEP-0054: vcard-temp]

== Inspiration and Acknowledgments ==
This section is '''informative'''.
Thanks to: my good friend [http://vadim.com/ Vadim] who introduced me to vCard ''many'' years ago, and if I'd only paid more attention then, perhaps I could have helped a lot of people avoid wasting a lot of time reinventing various standards wheels.

== Notes on derivation from vCard ==
This section is ''informative''.

<div id="Semantic_XHTML_Design_Principles">See: [[hcard-design-methodology]].</div>

=== More Semantic Equivalents ===
For some properties there are HTML elements which better match and convey their semantics. The following properties SHOULD be encoded with the following HTML:
* <code>URL</code> in vCard becomes <code><a class="url" href="...">...</a></code> inside the element with <code>class="vcard"</code> in hCard.
* Similarly, <code>EMAIL</code> in vCard becomes <code><nowiki><a class="email" href="mailto:...">...</a></nowiki></code>
* <code>PHOTO</code> in vCard becomes <code><img class="photo" src="..." alt="Photo of ..." /></code> or <code><object class="photo" data="..." type="...">Photo of ...</object></code>
* <code>UID</code> in vCard simply becomes another semantic applied to a specific URL (or EMAIL) for an hCard.

=== Singular and Plural derivations ===
The [[hcard#Singular_vs._Plural_Properties|lists of singular and plural properties]] have been derived by analyzing the semantics of the individual properties in vCard RFC2426 and determining logically that they MUST be singular per their semantics. See [[hcard-singular-properties]] for explanations.

==== Plural Properties Singularized ====
Since plural property names become their singular equivalents, even if the original plural property permitted only a single value with multiple components, those multiple components are represented each with their own singularly named property and the the property is effectively multivalued and subject to the above treatment of multivalued properties.

== Related Pages ==
{{hcard-related-pages}}

[[Category:Specifications]]
[[Category:hCard]]

== Translations ==
Read the hCard specification in additional <span id="languages">languages</span>:
* [[hcard-fr|français]]
* [[hcard-ru|Русский]]
* [[hcard-ja|日本語]]

User:BenWard/drafts/hcard

2009-12-26T22:05:25Z

BenWard: Copied hCard Spec 2009-12-26 as a base

<entry-title>hCard 1.0 — BenWard Edition</entry-title>

<dfn>hCard</dfn> is a simple, open, distributed format for representing people, companies, organizations, and places, using a 1:1 representation of vCard ([[rfc-2426|RFC2426]]) properties and values in [[semantic-xhtml|semantic HTML or XHTML]]. hCard is one of several open [[microformats|microformat]] standards suitable for embedding in HTML, XHTML, Atom, RSS, and arbitrary XML.

'''Want to get started with writing an [[hcard|hCard]]?''' Use the [http://microformats.org/code/hcard/creator hCard creator] to write up some contact information and publish it, or follow the [[hcard-authoring|hCard authoring tips]] to add hCard markup to your current contact page.

<div class="vcard">
; <span class="role">Editor</span>
: <span class="fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="url">http://tantek.com/</span>, and before at [http://technorati.com Technorati, Inc.], and at [http://microsoft.com/ Microsoft Corporation])
</div>
; Authors: [http://tantek.com/ Tantek Çelik] (affiliations above)
: <span class="vcard"><span class="fn">[[User:Brian|Brian Suda]]</span> (<span class="url">http://suda.co.uk/</span>)</span>

; Acknowledgments: See [[hcard#Inspiration_and_Acknowledgments|acknowledgments]].

[[hcard#Copyright|copyright]] and [[hcard#Patents|patents]] statements apply.

== Status ==
hCard 1.0 is a microformats.org specification. Public discussion on hCard takes place on [[hcard-feedback]], the #microformats [[irc]] channel on irc.freenode.net, and [http://microformats.org/discuss/mail/microformats-discuss/ microformats-discuss mailing list].

=== Available languages ===
The English version of this specification is the only normative version. For translations of this document see the [[#translations]] section.

=== Errata and Updates ===
Known errors and issues in this specification are corrected in [[hcard-issues-resolved|resolved]] and [[hcard-issues-closed|closed]] issues. Please check there before reporting [[hcard-issues|issues]].

The hCard 1.0.1 update is currently under development and incorporates known errata corrections as well as the [[value-class-pattern]].

== Introduction ==
The vCard standard ([[rfc-2426|RFC2426]]), has been broadly interoperably implemented (e.g. Apple's "Address Book" application built into MacOSX).

In addition, many bloggers identify themselves by name and discuss their friends and family. With just a tad bit of structure, bloggers can discuss people in their blog(s) in such a way that spiders and other aggregators can retrieve this information, automatically convert them to vCards, and use them in any vCard application or service.

This specification introduces the '''hCard''' format, which uses a 1:1 representation of the properties and values of the aforementioned vCard standard, in semantic HTML. Bloggers can both embed hCards directly in their web pages, and style them with CSS to make them appear as desired. In addition, hCard enables applications to retrieve information directly from web pages without having to reference a separate file.

Use the [http://microformats.org/code/hcard/creator hCard creator] and copy the HTML code it generates to your blog or website to publish your contact info.

{{rfc-2119-intro}}

== Format ==
=== In General ===
The vCard standard ([[rfc-2426|RFC2426]]) forms the basis of hCard.

The basic format of hCard is to use vCard object/property names in lower-case for class names, and to map the nesting of vCard objects directly into nested HTML elements.

=== Root Class Name ===
The root class name for an hCard is "vcard". An element with a class name of "vcard" is itself called an ''hCard''.

=== Properties and Sub-properties ===
The properties of an hCard are represented by elements inside the hCard. Elements with class names of the listed properties represent the values of those properties. Some properties have sub-properties, and those are represented by elements inside the elements for properties.

=== Property List ===
hCard properties (sub-properties in parentheses like this)

'''Required:'''
* '''fn'''
* <span id="property-list-n">'''n'''<sup style="font-size:smaller">[[#note1|1]]</sup> (family-name, given-name, additional-name, honorific-prefix, honorific-suffix)</span>
Optional:
* adr (post-office-box, extended-address, street-address, locality, region, postal-code, country-name, type, value)
* agent
* bday
* category
* class
* email (type, value)
* geo (latitude, longitude)
* key
* label
* logo
* mailer
* nickname
* note
* org (organization-name, organization-unit)
* photo
* rev
* role
* sort-string
* sound
* <span id="property-list-tel">tel<sup style="font-size:smaller">[[#note2|2]]</sup> (type, value)</span>
* title
* tz
* uid
* url

=== Property Notes ===
<span id="note1">[[#property-list-n|1. ^]]</span>: The 'n' property is {{optional}} if any [[hcard#Implied_.22n.22_Optimization|implied 'n' optimization rules]] are in effect.<br />
<span id="note2">[[#property-list-tel|2. ^]]</span>: tel - Authors {{may}} follow the [http://en.wikipedia.org/wiki/E.123 E.123] standard for writing values of telephone numbers. Letter values (e.g. +1-555-FORMATS) {{must}} be converted to numbers. Use an <code>abbr</code> to display letters and provide a numerical value simultaneously, e.g. <code><nowiki><abbr title="+15553676287">+1-555-FORMATS</abbr></nowiki></code>.

=== Singular vs. Plural Properties ===
Singular properties: 'fn', 'n', 'bday', 'tz', 'geo', 'sort-string', 'uid', 'class', 'rev'. For properties which are singular, the first descendant element with that class {{should}} take effect, any others being ignored.

All other properties {{may}} be plural. Each class instance of such properties creates a new instance of that property.

=== Human vs. Machine readable ===
The human visible text contents of an element for a property represents the value of that property, with a few exceptions:

If an <code><abbr></code> element is used for a property, then the '<code>title</code>' attribute (if present) of the <code><abbr></code> element is the value of the property, instead of the contents of the element, which instead provide a more human presentable version of the value.

If an <code><a></code> element is used for one or more properties, it {{must}} be treated as follows:
# For the 'photo' property and any other property that takes a URL as its value, the <code>href="..."</code> attribute provides the property value.
# For other properties, the element's content is the value of the property.

If an <code><img></code> element is used for one or more properties, it {{must}} be treated as follows:
# For the 'photo' property and any other property that takes a URL as its value, the <code>src="..."</code> attribute provides the property value.
# For other properties, the <code><img></code> element's '<code>alt</code>' attribute is the value of the property.

If an <code><object></code> element is used for one or more properties, it {{must}} be treated as follows:
# For the 'photo' property and any other property that takes a URL as its value, the <code>data="..."</code> attribute provides the property value.
# For other properties, the element's content is the value of the property.

=== Value excerpting ===
Sometimes only part of an element which is the equivalent for a property is used for the value of the property. This typically occurs when a property has a subtype, like 'tel'. For this purpose, the special class name "<code>value</code>" is used to excerpt out the subset of the element that is the value of the property. E.g. here is an hCard fragment for marking up a home phone number:<br />

vCard:
<pre><nowiki>
TEL;TYPE=HOME:+1.415.555.1212
</nowiki></pre>

hCard:
<pre><nowiki>
<span class="tel">
<span class="type">home</span>:
<span class="value">+1.415.555.1212</span>
</span>
</nowiki></pre>

This hCard fragment could be displayed as:

<div style="border: thin dashed black; width: 95%; padding: .5em 1em;">
<span class="tel">
<span class="type">home</span>:
<span class="value">+1.415.555.1212</span>
</span>
</div>



=== Property Exceptions ===
vCard has several properties which either do not make sense on, or are already implied within the context of a web page. This section explains what to (not) do with them.

# vCard's '''NAME''', '''PROFILE''', '''SOURCE''', '''PRODID''', '''VERSION''' properties are defined in Sections 2.1.2, 2.1.3, 2.1.4, 3.6.3, 3.6.9 of [[rfc-2426|RFC2426]]. Content publishers {{must-not}} use these properties in their hCards, and as such, hCard consumers/parsers {{must}} IGNORE these properties if they are found within an hCard. Instead. hCard to vCard converters {{should}} use the title of the page where the hCard is found (e.g. the <code><title></code> element in HTML documents) to construct the NAME property, {{may}} output a PROFILE value of "<code>VCARD</code>" per [[rfc-2426|RFC2426]], {{should}} use the URL of the page where the hCard is found to construct the SOURCE property (e.g. perhaps as a parameter to a URL/service that converts hCards to vCards), for an output vCard stream (e.g. a .vcf file). Only services/applications that output actual vCards should write the PRODID property, with the product identifier for said service/application. Similarly, only such services/applications should write the VERSION property, with the value "3.0" (without quotes) per [[rfc-2426|RFC2426]] Section 3.6.9.

=== Organization Contact Info ===
If the "FN" and "ORG" (organization) properties have the exact same value (typically because they are set on the same element, e.g. class="fn org"), then the hCard represents contact information for a company, organization or place and {{should}} be treated as such. In this case the author also {{must-not}} set the "N" property, or set it (and any sub-properties) explicitly to the empty string "". Thus parsers {{should}} handle the missing "N" property, in this case by implying empty values for all the "N" sub-properties.

=== Implied "n" Optimization ===
Although vCard requires that the "N" property be present, the authors of the vCard specification ([[rfc-2426|RFC2426]]) themselves do not include "N" properties in their vCards near the end of the spec (p.38). This apparent contradiction can be resolved by simply allowing the "FN" property to imply "N" property values in typical cases provided in the spec. We do so explicitly in hCard.

If "FN" and "ORG" are not the same (see previous section), and the value of the "FN" property is exactly two words (separated by whitespace), and there is no explicit "N" property, then the "N" property is inferred from the "FN" property. For "FN"s with either one word see below, and for three or more, the author {{must}} explicitly markup the "N", except for the organization contact info case, [http://microformats.org/wiki/hcard#Organization_Contact_Info see above] for that.

# The content of "FN" is broken into two "words" separated by whitespace.
# The ''first'' word of the "FN" is interpreted as the "given-name" for the "N" property.
# The ''second/last'' word of the "FN" is interpreted as the "family-name" for the "N" property.
# Exception: If the first word ends in a "," comma OR if the second word is a single character (optionally followed by a period "."), then the first word (minus the comma at the end if any) is interpreted as the "family-name" and the second word is interpreted as the "given-name".

This allows simplification in the typical case of people stating:
* given-name (space) family-name
* family-name (comma) given-name
* family-name (comma) given-name-first-initial
* family-name (space) given-name-first-initial (optional period)

=== Implied "nickname" Optimization ===
Due to the prevalence of the use of nicknames/handles/usernames in actual content published on the Web (e.g. authors of [[hReview|reviews]]), hCard also has an implied "nickname" optimization to handle this.

Similar to the implied "n" optimization, if "FN" and "ORG" are not the same, and the value of the "FN" property is exactly one word, and there is no explicit "N" property, then:

# The content of the "FN" {{must}} be treated as a "nickname" property value.
# Parsers {{should}} handle the missing "N" property by implying empty values for all the "N" sub-properties.

Though parsers {{must}} follow the implied nickname optimization, publishers {{should}} explicitly indicate the "nickname" even in this case, e.g.:

<pre><nowiki>
<span class="vcard">
<span class="fn nickname">daveman692</span>
</span>
</nowiki></pre>

The hCard {{may}} have additional explicit "nickname" property values in addition to the implied nickname.

=== Implied "organization-name" Optimization ===
The "ORG" property has two subproperties, organization-name and organization-unit. Very often authors only publish the organization-name. Thus if an "ORG" property has no "organization-name" inside it, then its entire contents {{must}} be treated as the "organization-name".

=== Tags as Categories ===
Categories in hCard {{may}} be represented by tags with [[rel-tag]]. When a category property is a rel-tag, the tag (as defined by rel-tag) is used for that category.

=== type subproperty values ===
The 'type' subproperty in particular takes different values depending on which property it is a subproperty of. These 'type' subproperty values are case-INSENSITIVE, meaning "Home" is the same as "home", as well as multivalued, e.g. a tel can be home and preferred:

vCard:
<pre><nowiki>
TEL;TYPE=HOME,PREF:+1.415.555.1212
</nowiki></pre>

hCard:
<pre><nowiki>
<span class="tel"><span class="type">Home</span> (<span class="type">pref</span>erred):
<span class="value">+1.415.555.1212</span>
</span>
</nowiki></pre>

This could be displayed as:

<div style="border: thin dashed black; width: 95%; padding: .5em 1em; ">
<span class="tel"><span class="type">Home</span> (<span class="type">pref</span>erred):
<span class="value">+1.415.555.1212</span>
</span>
</div>

==== type with unspecified value ====
When the type of a property is specified, and there is no explicit value specified, then everything in the property except for the type is considered the value of the property. E.g.

<pre><nowiki>
<span class="tel"><span class="type">Home</span> +1.415.555.1212</span>
</nowiki></pre>

is equivalent to:

<pre><nowiki>
<span class="tel"><span class="type">Home</span><span class="value"> +1.415.555.1212</span></span>
</nowiki></pre>

And thus the type is "home" and the value is "+1.415.555.1212".

==== adr tel email types ====
The following lists are ''informative''. See [[rfc-2426|RFC2426]] sections 3.2.1 ADR, 3.3.1 TEL, and 3.3.2 EMAIL respectively for normative type values. They are repeated here for convenience. Default type subproperty value(s) is(are) first in each list and indicated in ALL CAPS. types may be multivalued.

* adr type: INTL, POSTAL, PARCEL, WORK, dom, home, pref
* tel type: VOICE, home, msg, work, pref, fax, cell, video, pager, bbs, modem, [http://flickr.com/photos/tags/carcellphone/ car], isdn, pcs
* email type: INTERNET, x400, pref

=== Profile ===
The hCard <span id="XMDP_Profile">XMDP profile</span> is at http://microformats.org/profile/hcard

Content that uses hCard {{should}} reference this profile, e.g.
<source lang=html4strict>
<head profile="http://microformats.org/profile/hcard">
</source>
or
<source lang=html4strict>
<link rel="profile" href="http://microformats.org/profile/hcard">
</source>
or
<source lang=html4strict>
This content uses <a rel="profile" href="http://microformats.org/profile/hcard">hCard</a>.
</source>
Content may combine the above methods as well.

=== Parsing Details ===

See [[hcard-parsing|hCard parsing]].

== Examples ==

This section is informative.

=== Sample vCard ===

Here is a sample vCard:

<pre><nowiki>
BEGIN:VCARD
VERSION:3.0
N:Çelik;Tantek
FN:Tantek Çelik
URL:http://tantek.com/
END:VCARD
</nowiki></pre>

and an equivalent in hCard with various elements optimized appropriately. See [[hcard-example1-steps| hCard Example 1]] for the derivation.

<pre><nowiki>
<div class="vcard">
<a class="url fn" href="http://tantek.com/">Tantek Çelik</a>
</div>
</nowiki></pre>

This hCard might be displayed as:
<div style="border: thin dashed black; width: 95%; padding: .5em 1em;">
[http://tantek.com/ Tantek Çelik]
</div>

Note: The version information is unnecessary in hCard markup directly since the version will be defined by the profile of hCard that is used/referred to in the 'profile' attribute of the <head> element.

===Live example===

Here is [http://www.commerce.net/ Commercenet]'s contact details, as a live hCard which will be detected, on this page, by microformat parsing tools:

<div class="vcard">
<div class="fn org">'''CommerceNet'''</div>
<div class="url">'''<nowiki>http://www.commerce.net/</nowiki>'''</div>
<div class="adr">'''<span class="type">Work</span>:'''
<div class="street-address">'''169 University Avenue'''</div>
<span class="locality">'''Palo Alto'''</span>, <span class="region">'''CA'''</span>  <span class="postal-code">'''94301'''</span>
<div class="country-name">'''USA'''</div>
</div>
<div class="tel">'''<span class="type">Work</span> +1-650-289-4040'''</div>
<div class="tel">'''<span class="type">Fax</span> +1-650-289-4041'''</div>
<div>'''Email <span class="email"><nowiki>info@commerce.net</nowiki></span>'''</div>
</div>

The mark-up, emboldening omitted for clarity, with the following semantic improvements:
* <code>abbr</code> to expand abbreviations
* hyperlinking the org name with the url

<pre><nowiki>
<div class="vcard">
<a class="fn org url" href="http://www.commerce.net/">CommerceNet</a>
<div class="adr">
<span class="type">Work</span>:
<div class="street-address">169 University Avenue</div>
<span class="locality">Palo Alto</span>,
<abbr class="region" title="California">CA</abbr>  
<span class="postal-code">94301</span>
<div class="country-name">USA</div>
</div>
<div class="tel">
<span class="type">Work</span> +1-650-289-4040
</div>
<div class="tel">
<span class="type">Fax</span> +1-650-289-4041
</div>
<div>Email:
<span class="email">info@commerce.net</span>
</div>
</div>
</nowiki></pre>

=== More Examples ===
See [[hcard-examples|hCard examples]] for more examples, including all examples from vCard [[rfc-2426|RFC2426]] converted into hCard.

== Examples in the wild ==
This section is '''informative'''. The number of hCard examples in the wild has expanded far beyond the capacity of being kept inline in this specification. They have been moved to a [[hcard-examples-in-wild|separate page]].

See [[hcard-examples-in-wild|hCard Examples in the wild]].

== Implementations ==
This section is '''informative'''. The number of hCard implementations has also expanded beyond the capacity of keeping them inline. They have been moved to a [[hcard-implementations|separate page]].

See [[hcard-implementations|hCard Implementations]].

== Articles ==
This section is <strong>informative</strong>. For <span id="Further_Reading">further reading</span> on hCard see [[hcard-articles]].

==Buttons==
You can use these buttons on pages with hCards. See [[buttons#hCard]] for any recent additions.

* http://www.crowley.nl/images/hcard.png (mirror: http://www.davidjanes.com/images/mf_hcard.png)
* http://rbach.priv.at/2006/buttons/hcard.png
* http://www.boogdesign.com/images/buttons/microformat_hcard.png
* CSS-powered button, as evidenced at [http://re-run.com/about/microformat-badges microformat badges @ re-run]

== Copyright ==
Per the public domain release on the authors' user pages ([[User:Tantek|Tantek Çelik]], [[User:Brian|Brian Suda]]) this specification is released into the public domain.

{{MicroFormatPublicDomainContributionStatement}}

== Patents ==
{{MicroFormatPatentStatement}}

== References ==
=== Normative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://www.ietf.org/rfc/rfc2426.txt vCard RFC2426]
* [http://www.itu.int/rec/T-REC-E.123-200102-I/en ITU recommendation E.123] format of telephone numbers (chargeable document)
* [[rfc-2119|RFC 2119]]

=== Informative References ===
This section is '''informative'''.
* [[hcard-history|hCard history]]
** [http://wiki.oreillynet.com/foocamp04/index.cgi?SimpleSemanticFormats FOO Camp 2004 Simple Semantic Formats presentation, 2004-09-10]
** [http://tantek.com/log/2004/09.html#hcard hCard term introduced and defined on the Web, 2004-09-30]
** Contributed from http://developers.technorati.com/wiki/hCard 2005-06-20
* [http://www.dante.net/np/ds/osi/9594-6-X.520.A4.ps X.520 in Postscript] ([http://72.14.253.104/search?q=cache:FjqzsFu4h20J:www.dante.net/np/ds/osi/9594-6-X.520.A4.ps HTMLization courtesy of Google Cache]) - vCard refers to ROLE as being "based on the X.520 Business Category explanatory attribute".
* [http://www.w3.org/2002/12/cal/rfc2426 HTML reformatted version of RFC2426]
* [http://w3.org/TR/REC-CSS1 CSS1]
* [http://www.w3.org/TR/xhtml11 XHTML 1.1]
* [http://en.wikipedia.org/wiki/E.123 Wikipedia summary of ITU-T Recommendation E.123] - for "TEL" values.
* [http://www.imc.org/pdi/ Internet Mail Consortium Personal Data Interchange vCard and vCalendar]
* [[iso-8601|ISO8601]]

==== Specifications That Use hCard ====
* [[adr]]
* [[geo]]
* [[hcalendar|hCalendar]]
* [[hreview|hReview]]

==== Similar Work ====
This section is '''informative'''.
* [http://www.intertwingly.net/wiki/pie/PaceBetterPersonElement Atom PaceBetterPersonElement]
* [http://www.jabber.org/jeps/jep-0054.html JEP-0054: vcard-temp]

== Inspiration and Acknowledgments ==
This section is '''informative'''.
Thanks to: my good friend [http://vadim.com/ Vadim] who introduced me to vCard ''many'' years ago, and if I'd only paid more attention then, perhaps I could have helped a lot of people avoid wasting a lot of time reinventing various standards wheels.

== Notes on derivation from vCard ==
This section is ''informative''.

<div id="Semantic_XHTML_Design_Principles">See: [[hcard-design-methodology]].</div>

=== More Semantic Equivalents ===
For some properties there are HTML elements which better match and convey their semantics. The following properties SHOULD be encoded with the following HTML:
* <code>URL</code> in vCard becomes <code><a class="url" href="...">...</a></code> inside the element with <code>class="vcard"</code> in hCard.
* Similarly, <code>EMAIL</code> in vCard becomes <code><nowiki><a class="email" href="mailto:...">...</a></nowiki></code>
* <code>PHOTO</code> in vCard becomes <code><img class="photo" src="..." alt="Photo of ..." /></code> or <code><object class="photo" data="..." type="...">Photo of ...</object></code>
* <code>UID</code> in vCard simply becomes another semantic applied to a specific URL (or EMAIL) for an hCard.

=== Singular and Plural derivations ===
The [[hcard#Singular_vs._Plural_Properties|lists of singular and plural properties]] have been derived by analyzing the semantics of the individual properties in vCard RFC2426 and determining logically that they MUST be singular per their semantics. See [[hcard-singular-properties]] for explanations.

==== Plural Properties Singularized ====
Since plural property names become their singular equivalents, even if the original plural property permitted only a single value with multiple components, those multiple components are represented each with their own singularly named property and the the property is effectively multivalued and subject to the above treatment of multivalued properties.

== Related Pages ==
{{hcard-related-pages}}

[[Category:Specifications]]
[[Category:hCard]]

== Translations ==
Read the hCard specification in additional <span id="languages">languages</span>:
* [[hcard-fr|français]]
* [[hcard-ru|Русский]]
* [[hcard-ja|日本語]]

Main Page

2009-12-09T06:46:19Z

BenWard: Reverted edits by Cormierl20 (Talk) to last version by Tantek

<entry-title>Welcome to the microformats wiki!</entry-title>
__TOC__
Please start with the [[introduction]] page and read [[how-to-play]] before making any edits.

==Introduction==
This wiki is the central resource of the microformats community. You'll find current versions of published microformat specifications, specification drafts and publishing patterns. The wiki also hosts development resources, such as brainstorming pages for new formats and issue tracking pages for all current and in-development microformats.

== Get Started==
To get started with microformats:

* First, be familiar writing your pages and applications with semantically rich, descriptive, ‘[[posh|<abbr title="Plain Old Semantic HTML">POSH</abbr>]]’ <abbr title="HyperText Mark-up Language">HTML</abbr>.
* Learn about microformats from the [http://microformats.org/about/ about page], [http://microformats.org/ blog], [[press]], [[presentations]], [[books]], [[podcasts]], & [[screencasts]] pages.
* Take a look at established specifications such as [[hcard|hCard]] and [[hcalendar|hCalendar]], and follow the [[hcard-examples|examples]] to start publishing microformats.
* Have questions? Read the [[faq|frequently asked questions]] and see the [[glossary]] for terms and definitions. You can also post to the {{MicroformatsMailingList}}.
* Want to learn more in person? Check out microformats [[events]].

==Definition==
Microformats are small patterns of HTML to represent commonly published things like [[hcard|people]], [[hcalendar|events]], [[hatom|blog posts]], [[hreview|reviews]] and [[rel-tag|tags]] in web pages.

Microformats enable the publishing of higher fidelity information on the Web; the fastest and simplest way to provide feeds and APIs for the information in your website.

* Read more explanations of [[what-are-microformats|what microformats are]], and [[what-can-you-do-with-microformats|what you can do with them]].

== How to contribute ==
Do you want to help take microformats to the next level? You can:

* [[get-started|Get started]] by adding microformats to your website, services, and products.
* [[advocacy|Advocate]] the use of microformats on other web sites, especially those you use.
* Write a [[testimonial]].
* Do something on the [[to-do|to do list]].
* Join the [[irc|IRC Channel]] and [[mail|mailing lists]] to learn and help answer questions (read the [[mailing-lists#General_guidelines|general guidelines]] before posting).
* [[Main_Page#microformats_wiki_translations|Translate this microformats wiki into other languages]] to make microformats more accessible to readers of languages around the world.
* Before proposing any new microformats, make sure your website is [[POSH]], [[get-started|uses existing microformats]], and then read the [[process]].

This wiki has a number of enhancements to assist development and contributions to microformats. Before you start editing, see the [[wiki-2|wiki introduction page]] for instructions.

== Specifications ==
The list of current, stable [[microformats|Microformats]] open standard specifications.

* [[hcalendar|hCalendar]] - [http://microformats.org/code/hcalendar/creator hCalendar creator]
* [[hcard|hCard]] - [http://microformats.org/code/hcard/creator hCard creator]
* [[rel-license]]
* [[rel-nofollow]]
* [[rel-tag]]
* [[vote-links|VoteLinks]]
* [[XFN]] - [http://gmpg.org/xfn/creator XFN creator]
* [[XMDP]]
* [[xoxo|XOXO]]

''If you're tempted to try your hand at writing a microformat please read '''[[process|the process]]''' page first!''

== Drafts ==
Drafts are newer microformats, for which the specifications haven't been completed yet. Drafts are somewhat mature in the development [[process]] (see [[exploratory-discussions]] for additional efforts that are not as far along in the process). The stability of these documents cannot be guaranteed, and implementers should be prepared to keep abreast of future developments and changes. Please watch the wiki pages for updates.

* [[adr|adr]] - for marking up address information
* [[geo|geo]] - for marking up [http://en.wikipedia.org/wiki/WGS84 WGS84] geographic coordinates (latitude; longitude)
* [[hatom|hAtom]] - syndicating episodic content (e.g. weblog postings)
* [[haudio|hAudio]]
* [[hlisting|hListing]] - open, distributed listings
* [[hmedia|hMedia]] - A single media publishing format that relates to Images, Video and Audio.
* [[hnews|hNews]]
* [[hproduct|hProduct]]
* [[hrecipe|hRecipe]] - for cooking+baking recipes
* [[hresume|hResume]] - for publishing resumes and CVs
* [[hreview|hReview]] - [http://microformats.org/code/hreview/creator hReview creator]
* [[rel-directory]] - to indicate that the destination of a hyperlink is a directory listing containing an entry for the current page
* [[rel-enclosure]] - for indicating attachments (e.g. files) to download and cache
* [[rel-home]] - indicate a hyperlink to the homepage of the site
* [[rel-payment]] - indicate a payment mechanism
* [[robots-exclusion|robots exclusion]]
* [[xfolk|xFolk]]

== Design Patterns ==
{{design_patterns}} 

== Exploratory Discussions ==
See: [[exploratory-discussions]] for details of research and analysis of real-world [[examples]], existing formats, and brainstorming of possible new microformats, per the microformats [[process]].

== Examples ==
* [[examples-in-the-wild]]
* [[implementations]]
* [[zen-garden]]

== Resources ==
See [[resources]].

== User centric development ==
*[[user-interface]]
*[[data-portability]]
*[[social-network-portability]]

== Shared work areas ==
* [[to-do]]
* [[templates]]
* [http://microformats.org/wiki/delete pages for deletion] 
* [[Special:Specialpages|"Special" wiki pages]]
* [[year-in-review]]

== Tools, test cases, additional research ==
The first place to look for examples, code, and test cases is in the pages for each individual microformat. There are only a few cross-cutting [[tools|tools and services]] that need to process more than one microformat. That section is intended for editors, [[parsers]], [[validators]], test cases, and other information relevant across multiple microformats.

== Microformats wiki translations ==
<span id="microformats_wiki_translations_in_other_languages">You may read and edit microformats articles in many other languages:</span>

* languages with over 100 articles
** [[Main_Page-fr|<span lang="fr">Français</span> (French)]] <span lang="fr">{{UpdateMarker-fr}}</span>
* languages with over 10 articles
** [[Main_Page-pt-br|<span lang="pt-br">Português</span> (Brazilian Portuguese)]]
** [[Main_Page-ja|<span lang="ja">日本語</span> (Japanese)]]
** [[Main_Page-ru|<span lang="ru">Русский</span> (Russian)]]
* languages with over 2 articles
** [[Main_Page-cs|<span lang="cs">Česky</span> (Czech)]] {{NewMarker}}
** [[Main_Page-de|<span lang="de">Deutsch</span> (German)]]
** [[Main_Page-es|<span lang="es">Español</span> (Spanish)]]
** [[Main_Page-gl|<span lang="gl">Galego</span> (Galician)]] {{NewMarker}}
** [[Main_Page-pl|<span lang="pl">Polski</span> (Polish)]]
** [[Main_Page-ro|<span lang="ro">Română</span> (Romanian)]] {{NewMarker}}
** [[Main_Page-zh|<span lang="zh">汉语</span> (Chinese)]]
** [[Main_Page-id|<span lang="id">Indonesia</span> (Bahasa Indonesia)]] {{NewMarker}}
* languages just started
** [[Main_Page-ar|<span lang="ar">العربية</span> (Arabic)]]
** [[Main_Page-th|<span lang="th">ภาษาไทย</span> (Thai)]]
** [[Main_Page-it|<span lang="it">Italiano</span> (Italian)]] {{NewMarker}}
** [[Main_Page-ko|<span lang="ko">한국어</span> (Korean)]] {{NewMarker}}
* elsewhere
**[http://en.wikipedia.org/wiki/Microformat Wikipedia's article on microformats] has been translated into a number of languages.

See also [[other-languages]], and [[how-to-start-new-translation|how-to-start-a-new-translation]].

value-dt-test-YYYY-MM-DD--HH-MM

2009-11-04T01:59:31Z

BenWard: /* Asserts */ MediaWiki doesn't allow thead and tbody. Good grief.

<div class="test-fixture">
One of several [[value-class-date-time-tests|value class pattern date and time value test cases]]. Marked up with the [[test-fixture]] [[poshformat]].

;author
:<span class="author vcard"><span class="fn">[[User:Tantek|Tantek Çelik]]</span></span>

== testing ==
<span class="description">The <span class="summary">value-dt-test-YYYY-MM-DD--HH-MM</span> test demonstrate the concatenation of two html elements to create one datetime value:</span>
* YYYY-MM-DD
* HH:MM
in an <span class="format">[[hCalendar]]</span> event.

== markup pattern ==
Here is the markup pattern fragment (escaped, and with abstract not real values) that is being tested:

<source lang=html4strict>
<span class="dtstart">
<span class="value">YYYY-MM-DD</span>
at
<span class="value">HH:MM</span>
</span>
</source>

Similarly with <code>dtend</code>.

== test ==
[[hCalendar]] test in actual markup on the page (view or edit source to see actual hCalendar markup)
<div class="test" id="uf">
<div class="vevent">
;When
:<span class="dtstart"><span class="value">2009-06-26</span> at <span class="value">19:00</span></span> to <span class="dtend"><span class="value">2009-06-26</span> at <span class="value">22:00</span></span>
;Where
:<span class="location vcard"><span class="fn org">[http://www.yelp.com/biz/b-restaurant-and-bar-san-francisco B Restaurant and Bar]</span>, <span class="adr"><span class="street-address">720 Howard Street</span>, <span class="extended-address">Yerba Buena Upper Terrace</span>, <span class="locality">San Francisco</span>, <span class="region">CA</span> <span class="postal-code">94103</span> <span class="country-name">USA</span></span></span>
;What
:<span class="summary">microformats.org 4th birthday party!</span>
;Web
:<span class="url">http://microformats.org/wiki/events/2009-06-26-microformats-4th-bday</span>
:<span class="url">http://upcoming.yahoo.com/event/3010807</span>
;Donation
:Donation requested at the door: sliding scale $5-$20.
</div> 
</div> 

== expected iCalendar output ==
<div class="output">
Here is the expected <span class="type">iCalendar</span> output, omitting optional "X-" properties, and implementation specific "PRODID" property:
<div class="value">
<source lang=text>
BEGIN:VCALENDAR
VERSION:2.0
METHOD:PUBLISH
CALSCALE:GREGORIAN
BEGIN:VEVENT
LOCATION;LANGUAGE=en;CHARSET=utf-8:B Restaurant and Bar\, 720 Howard Street\, Yerba Buena Upper Terrace\, San Francisco\, CA 94103 USA
SUMMARY;LANGUAGE=en;CHARSET=utf-8:microformats.org 4th birthday party!
URL:http://microformats.org/wiki/events/2009-06-26-microformats-4th-bday
DTSTART;VALUE=DATE-TIME:20090626T190000
DTEND;VALUE=DATE-TIME:20090626T220000
END:VEVENT
END:VCALENDAR
</source>
</div> 
</div> 

The key lines that an hCalendar to iCalendar converter must match in order to pass this test:

<source lang=text>
DTSTART;VALUE=DATE-TIME:20090626T190000
DTEND;VALUE=DATE-TIME:20090626T220000
</source>

Acceptable variant:

<source lang=text>
DTSTART:20090626T190000
DTEND:20090626T220000
</source>

== Asserts ==

<table cellpadding="0" cellspacing="0" summary="Testing framework assertions used to test the parsed data against the expected data.">
<caption>A set of programming tests for xUnit testing frameworks</caption>
<tr>
<th>Test</th>
<th>Result</th>
<th>Comment</th>
</tr>
<tr class="assert">
<td class="test">vevent[0].dtstart</td>
<td class="result">IsEqualToISODate("2009-06-26T19:00")</td>
<td class="comment">With the value class pattern the results should contain a time</td>
</tr>
<tr class="assert">
<td class="test">vevent[0].dtend</td>
<td class="result">IsEqualToISODate("2009-06-26T22:00")</td>
<td class="comment">With the value class pattern the results should contain a time</td>
</tr>
</table>

== results ==
<div class="history">
* 2009-06-26: Brian Suda's [[X2V]] has been updated (as of X2V 0.9.3) to pass this test! See [http://suda.co.uk/projects/X2V/#H2I Brian Suda's X2V hCalendar-2-iCalendar converter on his site] to re-run and verify this test case for yourself. Or use this converter link to produce results from this test case page directly:
** http://suda.co.uk/projects/microformats/hcalendar/get-cal.php?uri=http://microformats.org/wiki/value-dt-test-YYYY-MM-DD--HH-MM%23uf
** verified by [[User:Tantek]] 2009-07-06.

* 2009-11-03: UfXtract has been updated to pass this test. To re-run and verify this test case try:
** http://ufxtract.com/api/?url=http://microformats.org/wiki/value-dt-test-YYYY-MM-DD--HH-MM&format=hcalendar&output=text

</div>
</div> 

== derivation ==
This test was derived from [[events/2009-06-26-microformats-4th-bday]] which used the [[hCard]] defined [[value-excerption-pattern]] to provide more readable and accessible date and time information.

== see also ==
* [[value-class-date-time-tests]]
* [[value-class-pattern]]
* [[hCalendar]]

value-dt-test-YYYY-MM-DD--HH-MM

2009-11-04T01:58:29Z

BenWard: /* Asserts */ Updated table semantics for assertions.

<div class="test-fixture">
One of several [[value-class-date-time-tests|value class pattern date and time value test cases]]. Marked up with the [[test-fixture]] [[poshformat]].

;author
:<span class="author vcard"><span class="fn">[[User:Tantek|Tantek Çelik]]</span></span>

== testing ==
<span class="description">The <span class="summary">value-dt-test-YYYY-MM-DD--HH-MM</span> test demonstrate the concatenation of two html elements to create one datetime value:</span>
* YYYY-MM-DD
* HH:MM
in an <span class="format">[[hCalendar]]</span> event.

== markup pattern ==
Here is the markup pattern fragment (escaped, and with abstract not real values) that is being tested:

<source lang=html4strict>
<span class="dtstart">
<span class="value">YYYY-MM-DD</span>
at
<span class="value">HH:MM</span>
</span>
</source>

Similarly with <code>dtend</code>.

== test ==
[[hCalendar]] test in actual markup on the page (view or edit source to see actual hCalendar markup)
<div class="test" id="uf">
<div class="vevent">
;When
:<span class="dtstart"><span class="value">2009-06-26</span> at <span class="value">19:00</span></span> to <span class="dtend"><span class="value">2009-06-26</span> at <span class="value">22:00</span></span>
;Where
:<span class="location vcard"><span class="fn org">[http://www.yelp.com/biz/b-restaurant-and-bar-san-francisco B Restaurant and Bar]</span>, <span class="adr"><span class="street-address">720 Howard Street</span>, <span class="extended-address">Yerba Buena Upper Terrace</span>, <span class="locality">San Francisco</span>, <span class="region">CA</span> <span class="postal-code">94103</span> <span class="country-name">USA</span></span></span>
;What
:<span class="summary">microformats.org 4th birthday party!</span>
;Web
:<span class="url">http://microformats.org/wiki/events/2009-06-26-microformats-4th-bday</span>
:<span class="url">http://upcoming.yahoo.com/event/3010807</span>
;Donation
:Donation requested at the door: sliding scale $5-$20.
</div> 
</div> 

== expected iCalendar output ==
<div class="output">
Here is the expected <span class="type">iCalendar</span> output, omitting optional "X-" properties, and implementation specific "PRODID" property:
<div class="value">
<source lang=text>
BEGIN:VCALENDAR
VERSION:2.0
METHOD:PUBLISH
CALSCALE:GREGORIAN
BEGIN:VEVENT
LOCATION;LANGUAGE=en;CHARSET=utf-8:B Restaurant and Bar\, 720 Howard Street\, Yerba Buena Upper Terrace\, San Francisco\, CA 94103 USA
SUMMARY;LANGUAGE=en;CHARSET=utf-8:microformats.org 4th birthday party!
URL:http://microformats.org/wiki/events/2009-06-26-microformats-4th-bday
DTSTART;VALUE=DATE-TIME:20090626T190000
DTEND;VALUE=DATE-TIME:20090626T220000
END:VEVENT
END:VCALENDAR
</source>
</div> 
</div> 

The key lines that an hCalendar to iCalendar converter must match in order to pass this test:

<source lang=text>
DTSTART;VALUE=DATE-TIME:20090626T190000
DTEND;VALUE=DATE-TIME:20090626T220000
</source>

Acceptable variant:

<source lang=text>
DTSTART:20090626T190000
DTEND:20090626T220000
</source>

== Asserts ==

<table cellpadding="0" cellspacing="0" summary="Testing framework assertions used to test the parsed data against the expected data.">
<caption>A set of programming tests for xUnit testing frameworks</caption>
<thead>
<tr>
<th>Test</th>
<th>Result</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr class="assert">
<td class="test">vevent[0].dtstart</td>
<td class="result">IsEqualToISODate("2009-06-26T19:00")</td>
<td class="comment">With the value class pattern the results should contain a time</td>
</tr>
<tr class="assert">
<td class="test">vevent[0].dtend</td>
<td class="result">IsEqualToISODate("2009-06-26T22:00")</td>
<td class="comment">With the value class pattern the results should contain a time</td>
</tr>
</tbody>
</table>

== results ==
<div class="history">
* 2009-06-26: Brian Suda's [[X2V]] has been updated (as of X2V 0.9.3) to pass this test! See [http://suda.co.uk/projects/X2V/#H2I Brian Suda's X2V hCalendar-2-iCalendar converter on his site] to re-run and verify this test case for yourself. Or use this converter link to produce results from this test case page directly:
** http://suda.co.uk/projects/microformats/hcalendar/get-cal.php?uri=http://microformats.org/wiki/value-dt-test-YYYY-MM-DD--HH-MM%23uf
** verified by [[User:Tantek]] 2009-07-06.

* 2009-11-03: UfXtract has been updated to pass this test. To re-run and verify this test case try:
** http://ufxtract.com/api/?url=http://microformats.org/wiki/value-dt-test-YYYY-MM-DD--HH-MM&format=hcalendar&output=text

</div>
</div> 

== derivation ==
This test was derived from [[events/2009-06-26-microformats-4th-bday]] which used the [[hCard]] defined [[value-excerption-pattern]] to provide more readable and accessible date and time information.

== see also ==
* [[value-class-date-time-tests]]
* [[value-class-pattern]]
* [[hCalendar]]

twitter-syntax

2009-10-30T18:51:09Z

BenWard: /* hreview */ Documented group account author attribution syntax (^BW)

<entry-title>Twitter Syntax</entry-title>
;short URL
:http://tr.im/twyntax

There is now an [http://help.twitter.com/index.php?pg=kb.page&id=75 Official Twitter Commands] page. Originally retrieved from the [http://twitter.com/help/lingo Twitter Lingo page], [http://twitter.com/help/follow Friends and Followers].

Send these commands to the appropriate number (below) and interact with Twitter on your mobile phone, via Gtalk (IM twitter at twitter.com) or the web.

;Following [http://twitter.com/blog/2007/07/friends-followers-and-notifications.html changes at Twitter] this page may need to be updated.

==Numbers==

<div class="vcard"><span class ="fn org">Twitter Canada</span>: <span class="tel"><span class="type" style="display:none;">cell</span> 21212</span></div>
<div class="vcard"><span class ="fn org">Twitter UK</span>: <span class="tel"><span class="type" style="display:none;">cell</span> +44 7624 801423</span></div>
<div class="vcard"><span class ="fn org">Twitter USA</span>: <span class="tel"><span class="type" style="display:none;">cell</span> 40404</span></div>
<div class="vcard"><span class ="fn org">Twitter International</span>: <span class="tel"><span class="type" style="display:none;">cell</span> +44 7624 801423</span></div>

== Commands ==

=== Messages ===
* '''@username + message''': directs a twitter at another person, and causes your twitter to save in their "replies" tab. Aka "at replies" or "@replies". Note that since @-reply handling change in (May?) 2009 (citation to Twitter blog post needed), messages starting with <kbd>@username</kbd> passed along only to your followers who also follow @username.
** '''.@username + message''': similar but the "." prefix is used to force/trick Twitter to have the message show up in the person's "replies" tab as well as be sent to all of your followers. Work around for the @-reply change mentioned above.
* '''D username + message''': sends a person a private message that goes to their device, and saves in their web archive.

=== Friends and Followers ===

* '''invite phone number''': 415-555-1212 john sends a text invite to john
* '''accept''': this command will accept a friend invitation. Example: Accept Jade. NOTE: when you accept, you must type in the name exactly as it was sent to you in order for Twitter to recognize it properly.
* '''deny''': this command will deny a friend invitation.
* '''delete''': for now, deleting friends must be done from the web.
* '''fav username''': marks a person's last twitter as a favorite

* '''get ''username''''': gets this person's last update
* '''on''' or '''start''' or '''wake''': enables twitter phone updates
** '''on username''': turns on notifications for a specific person on your device. For example, ON alissa.
* '''off''' or '''stop''' or '''sleep''': disables twitter phone updates
** '''off username''':turns off notifications for a specific person on your device. For example, OFF blaine.
* '''follow all''': turns on phone updates (entire friends list)
** '''follow username''': you will get phone updates from this person (requires initial approval)
*** shortcut: '''F'''
* '''leave all''': turns off phone updates (entire friends list)
** '''leave username''': disables phone updates from this person
*** shortcut: '''L'''
* '''nudge username''': encourages this person to update
* '''whois username''': text WHOIS BIZ to 40404 you will get the info Biz has filled out in his settings

=== Finding Out Stuff ===

* '''followers''': find out who is following your updates ''(no longer supported)''
* '''stats''': find out how many people are following you, and how many friends you have
* '''help''': sends back a list of twitter lingo commands

To update your own Twitter timeline, just text whatever is on your mind to the Twitter number: 40404, or use +447781488126 if you are outside the US.

=== Tracking ===

* '''track word''': get notifications via SMS or IM when a word is mentioned. type again to turn off.
* '''untrack word''': stops tracking a word
* '''untrack all''': stops tracking all words
* '''track off''': stops tracking all words
* '''tracks''': returns a list of words you're tracking

==hash tags==
[http://hashtags.org/ Hashtags] (aka "#tags") allow tagging of Twitter posts. For example, post "I love #microformats a lot" to Twitter and the post is tagged "microformats".

== hreview ==
* starting a message with "@hreview" will have it be aggregated by http://microrevie.ws and republished with [[hReview]] markup there.

==group accounts==

Groups of multiple people may share a single Twitter account to represent their organization.

* Attribution: Ending a message with <code>^XX</code>, indicates the author of a message on a group account. The <code>XX</code> initials correspond to one of the staff representing the group. (This convention popularized by [http://cotweet.com CoTweet], adopted by [[microformateers]]. e.g. [https://twitter.com/Microformateers/status/5294239824], [https://twitter.com/cotweet/])

==See also==
*[[picoformats]]
*[[twitter-nanoformats|twitter nanoformats]]
*[http://pigsonthewing.wordpress.com/2008/01/05/suggested-method-of-publishing-microformats-in-twitter-posts/ A suggested method of publishing microformats in Twitter posts]

x2v

2009-10-30T18:33:33Z

BenWard: Started listing the multiple hosted instances of X2V, rather than just linking to Technorati alone

<entry-title>X2V</entry-title>
[http://suda.co.uk/projects/X2V/ X2V] is an open source [[microformats]] XSLT [[implementation]] by [[User:Brian|Brian Suda]] that [[parsers|parses]] [[hCard]] or [[hCalendar]] events in (X)HTML and transforms them into the corresponding vCard (.vcf) or iCalendar (.ics) file respectively.

The latest beta and development versions of X2V can be tested at:
* http://suda.co.uk/projects/X2V/
** version 0.9.7 is the latest version, and it supports:
** [[hCard]] to [[vCard]]
** [[hCalendar]] to [[iCalendar]]
** [[value-class-pattern]] (nearly complete support of dates time separation, see [[value-class-date-time-tests]])

== feedback ==
Feature requests and other general feedback.
When this section grows to big we can move it to [[x2v-feedback]].

== issues ==
Bugs or other apparent problems. See [[x2v-issues]].

==hosted instances==

If you want to just use X2V hosted on the web, the following sites are running it:

* [[implementors#Technorati|Technorati]] hosts a deployment of X2V for converting hCard contacts or hCalendar events at:
** http://feeds.technorati.com/contacts/
** http://feeds.technorati.com/events/
* [http://h2vx.com h2vx] is a transformer service powered by X2V
** http://h2vx.com/vcf/
** http://h2vx.com/ics/
* Brian Suda's development page has a running copy, too:
** http://suda.co.uk/projects/X2V/

== install ==
If you wish to run your own X2V converter, either for your own content, or as a general web service, you need to first get:
* X2V XSLT files (needs link to latest download)
* X2V PHP code (needs link to latest download)

Then follow these instructions to set it up:
# ... (to be documented)
# ...

== moved ==
One inline <span id="Test">test</span> moved to: [[value-dt-test-YYYY-MM-DD--HH-MM]], and expanded into a general test case for the [[value-class-pattern]], one of several [[value-class-date-time-tests]].

== see also ==
* [[hCard]]
* [[hcard-implementations]]
* [[vcard-implementations]]
* [[hCalendar]]
* [[hcalendar-implementations]]
* [[icalendar-implementations]]
* [[implementations]]

microformateers

2009-09-26T21:33:02Z

BenWard: /* Response Process */ Fixed collapsed URL

microformateers

2009-09-26T21:32:38Z

BenWard: /* Response Process */ Fixed collapsed URL

microformateers

2009-09-26T21:31:57Z

BenWard: Finished microformateers page

microformateers

2009-09-26T21:25:31Z

BenWard: /* Who are the microformateers? */ Changed mark-up to use AGENT

microformateers

2009-09-26T21:20:58Z

BenWard: Created page for @microformateers service.

User:BenWard/drafts/embed-brainstorming

2009-09-15T19:07:43Z

BenWard: User:BenWard/drafts/embed-brainstorming moved to embed-brainstorming: Move out of user space.

#REDIRECT [[embed-brainstorming]]

embed-brainstorming

2009-09-15T19:07:43Z

BenWard: User:BenWard/drafts/embed-brainstorming moved to embed-brainstorming: Move out of user space.

; Editor: [[User:BenWard|Ben Ward]]

==Synopsis==

Embedding content across different publishers — such as showing YouTube videos in blog posts, Flickr photographs in Pownce, preview images next to bookmarked links.

Sites such as YouTube, Flickr, Vimeo and others publish ‘embed code’ to aid users in copy+pasting content into their own repostings. This is especially useful for embedding of complex content such as Shockwave Flash movies, where the HTML code is not intuitive. Sites like Flickr use copy+paste code examples to encourage and enforce link-back policies and publication of author, publisher and copyright information.

==Goal==

Produce a microformat to describe the embedding patterns for content and the author/publisher information connected to the content, such that a user or tool could extract the ‘embed’ from any supporting site in a common manner. That could be in the authoring stage of tools such as blogging platforms, or at the publication stage, such as Pownce showing embedded content for URLs that are posted to the service.

==Use Cases==

* Users republish any embeddable piece of content by providing just a URL
* Content from a URL extracted and displayed alongside links in microblogging systems such as Pownce and Tumblr, without those services having to write unique extraction code for every website.
* Content to be displayed alongside search results (e.g. via Yahoo SearchMonkey, or behind-the-scenes systems used for image previews)
* Where you type a URL into a message (e.g. on Facebook), a service looks up the URL and grabs the page title and a content snippet to display with the the message. A kind of ‘rich link’. This microformat would enable more relevant content to be parsed out of pages.
* Allow content to be marked up in such a way that the embed code can be taken from mark-up itself if appropriate, not just explicit chunks of code.
* Allow publishers to mark-up a piece of code used for embedding that differs from the code used by the publisher site.
** e.g. Flickr photos on Flickr do not link to the Flickr page itself, but Flickr TOS dictate that photos ''must'' link back to Flickr. As such, the code they give users to embed a photo is different from the code they use to publish the photo.
** However, when I repost that photo — linking to Flickr — the actual mark-up I used could be used by someone else to republish that photo in line with the TOS. Both publishing scenarios are valid.

==Existing Sytems==

The creators of Pownce have created an XML standard called oEmbed. This is a standalone XML representation of embeddable content, similar to a feed entry, but including additional fields for the host site (the publisher), and the exact code needed to include the content object in pages.

oEmbed uses an XRDS endpoint, linked to from the content page, to provide the oEmbed representation of a resource.

==Examples==

===Publishers===

Publisher examples record both the content of the provided embed code, and also the whether that same information is present in the mark-up of the page.

====YouTube====

=====In Page=====

* Video (object)
* Title
* Description
* HTML embed code (<input>)
* Permalink
* Author
** Name
** URL
* Site (Publisher)
* Rating
* Viewcount

— http://uk.youtube.com/watch?v=zP4zaMvV__4

=====Embed Code=====

<source lang=html4strict>
<object width="425" height="344">
<param name="movie" value="http://www.youtube.com/v/zP4zaMvV__4&hl=en&fs=1"></param>
<param name="allowFullScreen" value="true"></param>
<param name="allowscriptaccess" value="always"></param>
<embed src="http://www.youtube.com/v/zP4zaMvV__4&hl=en&fs=1"
type="application/x-shockwave-flash"
allowscriptaccess="always"
allowfullscreen="true"
width="425"
height="344"></embed>
</object>
</source>

* Video URL
* Media Dimensions

YouTube does not include any information about the video, author, licensing or source site in HTML. That content is all presented within the Flash object itselt.

====Flickr====

Flickr has two relevant pages; the photo page itself (which contains no explicit embed code) and the ‘All Photos’ page, which contains links to multiple sizes and example embed code.

=====Photo Page Schema=====

* Title
* Description
* Image (img)
* Author
* Publisher (site name)
* License
* Link to other sizes
* Page is the permalink

— http://www.flickr.com/photos/benward/3189768143/

=====‘All Sizes’ (embed page) schema=====

* Image (at size)
* License
* Author
* HTML embed code
* Direct link to image
* Additional reuse rules (‘photo must be linked to the photo page’)
* Links to other sizes
* Link back to main image (permalink)

— http://www.flickr.com/photos/benward/3189768143/sizes/l/

=====Embed Code=====

<source lang=html4strict>
<a href="http://www.flickr.com/photos/benward/3189768143/" title="Fresh Baked by Ben Ward, on Flickr">
<img src="http://farm4.static.flickr.com/3398/3189768143_2ca7da4544_b.jpg" width="1024" height="683" alt="Fresh Baked" />
</a>
</source>

* Photo URL
* Photo Title
* Photo Dimensions
* Author name
* Publisher Name
* Photo permalink

===Vimeo===

====In Page===
* Title
* Video (content)
* Description
* Author
* Publisher (vimeo)
* Published Date
* Link to raw video
* Embed code — revealed by clicking a link within a flash movie. Not present with JavaScript disabled.

====Embed Code====

<source lang=html4strict>
<object width="400" height="225">
<param name="allowfullscreen" value="true" />
<param name="allowscriptaccess" value="always" />
<param name="movie" value="http://vimeo.com/moogaloop.swf?clip_id=2755105&server=vimeo.com&show_title=1&show_byline=0&show_portrait=0&color=FF0E0F&fullscreen=1" />
<embed src="http://vimeo.com/moogaloop.swf?clip_id=2755105&server=vimeo.com&show_title=1&show_byline=0&show_portrait=0&color=FF0E0F&fullscreen=1"
type="application/x-shockwave-flash"
allowfullscreen="true"
allowscriptaccess="always"
width="400"
height="225">
</embed>
</object>
<br />
<a href="http://vimeo.com/">The Remnants</a>
from <a href="http://vimeo.com/johnaugust">John August</a>
on <a href="http://vimeo.com">Vimeo</a>.
</source>

* Video object
* Video dimensions
* Video title
* Permalink
* Publisher
** Name (Vimeo)
** URL
* Creator
** Name
** URL

===Skitch===
* Publishes 5 different embed codes. Interrrresting.

===Photobucket===

===Consumers===

Consumption of embedable content is spread throughout a number of different use cases:

====Microblogging====

=====Pownce=====

[http://pownce.com Pownce] is the original pioneer of the <code>oembed</code> standard. It takes a URL input for an external resource, and where supported embedable content is found, the embed is included with the link post.

Pownce notes are already marked up with hAtom, and include embedded content within a class of <code>attachment</code>.

In addition to the fields of hAtom, the embedded content includes:

* Linking back to the publishing source
* Attribution to the embedded content creator
* Count of the times the content has been downloaded from this publisher

<source lang=html4strict>
<li id="note4390327" class="public-note hentry">
<div class="note-contents">
<a href="/ariel/">
<img src="/profile_photos/a/r/i/ariel/304_medium.jpg" width="48" height="48" title="Ariel Waldman" class="user" />
<em class="pro-2">Pro!</em>
</a>

<p class="entry-content">
<em class="note-type entry-title">
<a href="/ariel/notes/4390327/" rel="bookmark">Public</a>
</em>
My favorite Pownce post from !<a href="/leahculver/">leahculver</a>.
</p>

<div class="attachment">
<div>
<a href="http://flickr.com/photos/arielwaldman/3078507970/in/photostream/">
<img src="http://farm4.static.flickr.com/3210/3078507970_5811e41585_m.jpg" alt="Pownce" /><br />
</a>
</div>

<div class="by-caption">
<span>photo by</span>
<a href="http://www.flickr.com/photos/arielwaldman/" >arielwaldman</a>
</div>

<a href="http://flickr.com/photos/arielwaldman/3078507970/in/photostream/" class="note-url">
flickr.com/photos/arielwaldman/30...
</a>
<div class="note-count">
<span id="click-count-4390327">(14 views)</span>
</div>
</div>

<div class="note-location fireeagle">
<span class="locator"><a href="/settings/fireeagle/">Fire Eagle</a>:
<span class="locality">San Francisco, CA</span>
<span class="country-name">US</span>
</div>

<h4>
<abbr class="published" title="1 day ago">1 day ago</abbr>
<span class="vcard author">
<a href="/ariel/" class="sender url">
<span class="fn">
Ariel Waldman
</span>
</a>
</span>

<a href="/ariel/notes/4390327/" class="reply">2 Replies </a>
<a href="/ariel/notes/4390327/forward/" class="forward">Forward</a>
</h4>
</div>
</li>
</source>
''— Source of a full note, embedding a Flickr photograph, from http://pownce.com/benward''

<source lang=html4strict>
<div class="attachment">
<div>
<span>
<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000"
codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=8,0,0,0"
width="300" height="247" id="jxT0ELP7az0" align="middle">
<param name="movie" value="http://www.youtube.com/v/jxT0ELP7az0" />
<embed src="http://www.youtube.com/v/jxT0ELP7az0" quality="high"
width="300" height="247" name="jxT0ELP7az0"
align="middle" allowScriptAccess="sameDomain"
type="application/x-shockwave-flash" pluginspage="http://www.adobe.com/go/getflashplayer" />
</object>
</span>
</div>

<a href="http://www.youtube.com/watch?v=jxT0ELP7az0" class="note-url">
www.youtube.com/watch?v=jxT0ELP7a...
</a>
<div class="note-count">
<span id="click-count-3949474">(4 views)</span>
</div>
</div>
</source>
''— Source snippet of a video note, showing the YouTube video attachment, from [http://pownce.com/BenWard/notes/4137829/]''

=====Tumblr=====

[http://tumblr.com Tumblr] is the defacto tumblelog application, encouraging users to post small snippet posts of text, as well as reposting images, audio, video, text quotes and URLs. The output of Tumblr varies depending on the theme the user uses, and can be customised. As such, the following documents the inputs used to publish content.

* '''Text'''
** Title
** Text Content
* '''Photo'''
** Either the URL of a already hosted photograph, or an image binary upload
** Text Caption
** Click-through URL (e.g. linking a Flickr photo back to the source page)
* '''Quote'''
** Quote Text
** Source (text, also usable as a desciption)
* '''Link/URL'''
** Name (title)
** URL
** Description
* '''Chat (conversations)'''
** Title
** Dialogue (free text field, expects <code>My Name: This is my message</code> format text)
* '''Audio'''
** Audio binary, or URL to externally hosted audio
** Text description
* '''Video'''
** URL for YouTube or Vimeo service videos, or paste custom embed code from any site.
** Text caption

All post types include adding tags, setting the publication date, visibility (public/private), and the permalink slug.

Tumblr provides a quite strictly structured input mechanism, but the ''video'' type is most relevant, as this accepts the code provided by any site. This microformat could allow it to accept any URL, beyond just YouTube and Vimeo for which it has implemented proprietary support.

=====More to Document=====

* Delicious
* Yahoo Search
* Google Search
* Facebook's ‘Compose New Message’ interface

embed-brainstorming

2009-09-15T19:06:43Z

BenWard: Add editor credit

html5

2009-09-04T21:25:08Z

BenWard: /* New features in HTML5 */ More HTML5 equivalents

<h1>Microformats in HTML 5</h1>

''This page is to document '''future''' use of microformats in [http://www.w3.org/html/wg/html5 HTML 5]. None of the items documented are supported now, and may change upon proper development within the microformats community, or changes in the HTML 5 specification. This page is to track HTML5 enabled enhancements to microformats, and issues that HTML5 raises. It may be used to track issues which we need to push back into the HTML 5 development process.''

If there are things that Microformats would like to mark up that aren't handled by HTML5 explicitly, please let the WHATWG know, so we can improve HTML5. This is how <code>time</code> came to be, for instance.

==New features in HTML5==

* '''<code>time</code> element for representing date times'''. In HTML5, the machine form of datetimes can be represented natively. It should be possible to replace the date-time design pattern with native HTML.
** <code>time</code> takes an optional <code>pubdate</code> attribute, to indicate the publication date of an <code>article</code>. Synonymous with [[hAtom]] <code>published</code>, may imply [[hAtom]] <code>updated</code>, may imply [[hReview]] <code>dtreviewed</code>, may imply [[hListing]] <code>dtlisted</code>
* '''<code>article</code>''' element for major, independent compositions of content within a page. Perhaps synonymous with [[hAtom]] <code>hentry</code>. Could be parsed as <code>hentry</code> within explicit <code>hfeed</code> blocks?
* '''<code>data-</code> naming convention for tag attributes'''. the draft specification states that any attribute that starts with "data-" will be treated as a storage area for private data.
** Note that the data-* stuff is explicitly 'not' for Microformats, at least not Microformats that ever want to be handled natively by the browser. Those attributes are defined in such a way that browsers will never do anything special with them, ever. They are intended for script authors to have a space in which they can play without ever clashing with anything the browser does.
* '''[[microdata]]'''. HTML5 provides a set of attributes and associated DOM APIs for extracting data from web pages.
** <code>itemprop</code> attribute is a more specific version of <code>class</code>, for field names
** <code>subject</code> attribute allows semantically linking within the page. Conceptually similar to the [[include-pattern]].
** <code>content</code> attribute on the <code>meta</code> element can be used to invisibly include data. Conceptually similar to the [[value-class-pattern]].
** <code>item</code> attribute identifies blocks to be marked as structure data. Conceptually similar to the [[mfo]] brainstorming?

== Current microformat compatibility ==
There seems to be no issue with current implementation of the following microformats in HTML 5:
* [[hcard]]
* [[xfn]]

== Requests ==
* "how to use with HTML5" sections that include (a) microformats examples that use [[HTML5]], and (b) microformats parsing details that specify what to do (if anything special is required) with HTML5 elements (e.g. how to parse the <code>time</code> element for dates and times for microformats). See (and add to if necessary) :
** [[hcard-brainstorming#how_to_use_with_HTML5|hCard brainstorming - how to use with HTML5]]
** [[hcalendar-brainstorming#how_to_use_with_HTML5|hCalendar brainstorming - how to use with HTML5]] e.g. hCalendar with the <code>time</code> element
** [[citation-brainstorming#how_to_use_with_HTML5|citation brainstorming - how to use with HTML5]]
** if nothing special is required for HTML5, then after performing the analysis, that should be noted as well, for the purpose of clarity.

==Issues==

<div class='discussion issues'>
* '''The <code>rev</code> attribute has been removed'''. In HTML5, <code>rel</code> and <code>rev</code> are no-longer paired, and the <code>rel</code> attribute nolonger describes the direction of a relationship. Microformats which use <code>rev</code> will need to use <code>rel</code> instead.
** Or something like data-rev="vote-for"
*** As above, <code>data-</code> attributes are for application-context functionality, ''not'' shared vocabularies. Further, the HTML5 specification makes <code>rel</code> the correct attribute to use, regardless of direction, through the changed specification. --[[User:BenWard|BenWard]] 17:53, 12 May 2009 (UTC)
* '''The <code>profile</code> attribute has been removed'''. In HTML, the <code>profile</code> attribute from the <code>head</code> has been removed, with no direct replacement. This causes issues for GRDDL support. It's been suggested that profile URLs be represented in <code>link</code> elements instead, or even as a custom HTTP header. See [[grddl]] and [[profile-uris]]
* '''Microdata <code>itemprop</code> duplicates <code>class</code> data'''. the new attribute itemprop is designed to hold some meaningful data about an element, but class already exists to hold this data. Unsure of reasons why itemprop required?
** This is because microdata is designed to be generically parsable, even when the parser does not understand the vocabulary. As such, property names have to be on an explicit attribute, not shared with other, non-data classnames. --[[User:BenWard|BenWard]] 21:12, 4 September 2009 (UTC)
</div>

== see also ==
* [[HTML3]]

html5

2009-09-04T21:12:26Z

BenWard: /* Issues */ Explain why itemprop not class

<h1>Microformats in HTML 5</h1>

''This page is to document '''future''' use of microformats in [http://www.w3.org/html/wg/html5 HTML 5]. None of the items documented are supported now, and may change upon proper development within the microformats community, or changes in the HTML 5 specification. This page is to track HTML5 enabled enhancements to microformats, and issues that HTML5 raises. It may be used to track issues which we need to push back into the HTML 5 development process.''

If there are things that Microformats would like to mark up that aren't handled by HTML5 explicitly, please let the WHATWG know, so we can improve HTML5. This is how <code>time</code> came to be, for instance.

==New features in HTML5==

* '''<code>time</code> element for representing date times'''. In HTML5, the machine form of datetimes can be represented natively. It should be possible to replace the date-time design pattern with native HTML.
* '''<code>data-</code> naming convention for tag attributes'''. the draft specification states that any attribute that starts with "data-" will be treated as a storage area for private data.
** Note that the data-* stuff is explicitly 'not' for Microformats, at least not Microformats that ever want to be handled natively by the browser. Those attributes are defined in such a way that browsers will never do anything special with them, ever. They are intended for script authors to have a space in which they can play without ever clashing with anything the browser does.
* '''[[microdata]]'''. HTML5 provides a set of attributes and associated DOM APIs for extracting data from web pages.
** <code>itemprop</code> attribute is a more specific version of <code>class</code>, for field names
** <code>subject</code> attribute allows semantically linking within the page. Conceptually similar to the [[include-pattern]].
** <code>content</code> attribute on the <code>meta</code> element can be used to invisibly include data. Conceptually similar to the [[value-class-pattern]].
** <code>item</code> attribute identifies blocks to be marked as structure data. Conceptually similar to the [[mfo]] brainstorming?

== Current microformat compatibility ==
There seems to be no issue with current implementation of the following microformats in HTML 5:
* [[hcard]]
* [[xfn]]

== Requests ==
* "how to use with HTML5" sections that include (a) microformats examples that use [[HTML5]], and (b) microformats parsing details that specify what to do (if anything special is required) with HTML5 elements (e.g. how to parse the <code>time</code> element for dates and times for microformats). See (and add to if necessary) :
** [[hcard-brainstorming#how_to_use_with_HTML5|hCard brainstorming - how to use with HTML5]]
** [[hcalendar-brainstorming#how_to_use_with_HTML5|hCalendar brainstorming - how to use with HTML5]] e.g. hCalendar with the <code>time</code> element
** [[citation-brainstorming#how_to_use_with_HTML5|citation brainstorming - how to use with HTML5]]
** if nothing special is required for HTML5, then after performing the analysis, that should be noted as well, for the purpose of clarity.

==Issues==

<div class='discussion issues'>
* '''The <code>rev</code> attribute has been removed'''. In HTML5, <code>rel</code> and <code>rev</code> are no-longer paired, and the <code>rel</code> attribute nolonger describes the direction of a relationship. Microformats which use <code>rev</code> will need to use <code>rel</code> instead.
** Or something like data-rev="vote-for"
*** As above, <code>data-</code> attributes are for application-context functionality, ''not'' shared vocabularies. Further, the HTML5 specification makes <code>rel</code> the correct attribute to use, regardless of direction, through the changed specification. --[[User:BenWard|BenWard]] 17:53, 12 May 2009 (UTC)
* '''The <code>profile</code> attribute has been removed'''. In HTML, the <code>profile</code> attribute from the <code>head</code> has been removed, with no direct replacement. This causes issues for GRDDL support. It's been suggested that profile URLs be represented in <code>link</code> elements instead, or even as a custom HTTP header. See [[grddl]] and [[profile-uris]]
* '''Microdata <code>itemprop</code> duplicates <code>class</code> data'''. the new attribute itemprop is designed to hold some meaningful data about an element, but class already exists to hold this data. Unsure of reasons why itemprop required?
** This is because microdata is designed to be generically parsable, even when the parser does not understand the vocabulary. As such, property names have to be on an explicit attribute, not shared with other, non-data classnames. --[[User:BenWard|BenWard]] 21:12, 4 September 2009 (UTC)
</div>

== see also ==
* [[HTML3]]

category-brainstorming

2009-09-01T01:16:27Z

BenWard: New brainstorming around the area of object categorization. Proposal for identifying/parsing language categories

<code>category</code> is a field used in many microformats, originally taken from [[hCard]].

<blockquote>Type name: CATEGORIES
Type purpose: To specify application category information about the vCard.</blockquote>
— <cite>[http://www.ietf.org/rfc/rfc2426.txt RFC2426]</cite>

It is closely related to [[rel-tag]], but has no dependency on URL schemes, it simply marks up the inner-text as a category keyword.

Brainstorming on this page may be applicable to parsing of <code>category</code> and/or [[rel-tag]].

__TOC__

==Supported Languages==

An object — a person, or item (in a [[hProduct]] or [[hListing]] context) — may be consumable in multiple languages. A person may communicate in multiple languages, a set of self-assembly shelves may come with an instruction manual in multiple languages, a web application (also a product) can be localized to support use in multiple languages.

In a loose form, supported language is a form of categorization, but it is useful to filter by language separately from other tags/categories (‘Only show me people that speak languages I speak’, ‘Only show applications available in my language’).

Language on the web are indicated in multiple forms on the web:

* Names (e.g. ‘Français’, ‘Deutsch’, ‘English (British)’
* Abbreviated local names ‘En’, ‘Fr’, ‘De’
* Abbreviated country names: ‘GB’, ‘UK’, ‘ES’
* ''Local'' names (e.g. ‘French’, ‘German’, ‘British English’, ‘Dutch’)
* ISO 639 language codes (e.g. 'en-gb', 'en', 'fr', 'de')

HTML already has a <code>lang</code> attribute for marking up actual content. This uses ISO 639 codes.

Categorizing languages has the following requirements:

* Differentiate from other types of category
* Allow the language to be presented in local name form
* Allow the language itself to be ascertained reliably and interoperably

===Proposal 1: <code>class='category language'</code>===

* Use an additional class-name <code>language</code> to indicate that a category is marking up a supported language for the object.
* <code>class=language</code> also instructs parsers to read the ISO code from the <code>lang</code> attribute of the element, in place of the inner text, where present.

e.g.

<source lang=html4strict>
<ul>
<li class="category language" lang="en-gb">English (British)</li>
<li class="category language" lang="en">English (American)</li>
<li class="category language" lang="fr">Français</li>
<li class="category language" lang="de">Deutsch</li>
</ul>
</source>

In HTML, the strings ''should'' be marked up with a lang attribute to ensure that the local named languages are pronounced correctly by screen readers (for example).

With rel-tag:

<source lang=html4strict>
<ul>
<li><a class='language' rel='tag' href='/apps/lang/en' lang='en'>English</a></li>
<li><a class='language' rel='tag' href='/apps/lang/en-gb' lang='en-gb'>English (British)</a></li>
<li><a class='language' rel='tag' href='/apps/lang/fr' lang='fr'>Français</a></li>
<li><a class='language' rel='tag' href='/apps/lang/de' lang='de'>Deutsch</a></li>
</ul>
</source>

In this case, the URL scheme is shown to also use ISO codes. This may not be the case in production environments (they may choose to use <code>/apps/lang/english</code>, for example), so parsers look explicitly for language information should be instructed to again look for for the <code>lang</code> attribute where rel-tag is used in combination with class-language.
--[[User:BenWard|BenWard]] 01:16, 1 September 2009 (UTC)

rel-tag-spaces

2009-09-01T00:44:20Z

BenWard: Document Last.FM tagspace

This is a list of "name spaces" suitable for use in tagging, and by the [[rel-tag]] microformat. Please feel free to add to it, in alphabetical order.

==A9==
*One word - http://a9.com/microformats
*Multi-word - http://a9.com/source+code (plus sign)

==Amazon.com==
*One word - http://www.amazon.com/tag/horror
*Multi-word - http://www.amazon.com/tag/science%20fiction (%20, browsers will auto-encode a space into this)

:(note - not valid for amazon.co.uk)

==del.icio.us==
*One word - http://del.icio.us/tag/dog
*Multi-word - http://del.icio.us/tag/german_shepherd (underscore)

==Discogs==
(for musical artists)
*One word - http://www.discogs.com/artist/Genesis
*Multi-word - http://www.discogs.com/artist/Jimi+Hendrix (plus sign)

==eBay==
*One word - http://search.ebay.com/door
*Multi-word - http://search.ebay.com/door-mat (hyphen)
*International - http://search.ebay.co.uk/door (etc.)

==Flickr==
*One word - http://www.flickr.com/photos/tags/key
*Multi-word. Flickr allows all of the following, and treats them as "keyhole":
**http://www.flickr.com/photos/tags/key_hole (underscore)
**http://www.flickr.com/photos/tags/key-hole (hyphen)
**http://www.flickr.com/photos/tags/key+hole (plus)
**http://www.flickr.com/photos/tags/key=hole (equals)
**http://www.flickr.com/photos/tags/key*hole (asterisk)
**http://www.flickr.com/photos/tags/key.hole (stop)

[http://weblog.terrellrussell.com/2007/06/clean-and-store-your-raw-tags-like-flickr/ More on this "tag-cleaning" behavior] and [http://www.flickr.com/services/api/misc.tags.html Flickr's note on tag-cleaning].

== HashTags ==

Tags for Twitter posts, but also suitable as a general target for tagged links:

* One word - http://hashtags.org/tag/microformats/
* Multi-word - tbc

== ISBN ==

For [[isbn|ISBN]] codes, e.g. 0-9507881-2-0:

*Talis (note: no hyphens)
** ISBN-10 - http://cenote.talis.com/isbn/0950788120
** ISBN-13 - http://cenote.talis.com/isbn/9780950788128
*Wikipedia
** ISBN-10 - http://en.wikipedia.org/wiki/Special:Booksources/0950788120 or http://en.wikipedia.org/wiki/Special:Booksources/0-9507881-2-0
** ISBN-13 - http://en.wikipedia.org/wiki/Special:Booksources/9780950788128 or http://en.wikipedia.org/wiki/Special:Booksources/978-09507881-2-8
*WorldCat
** ISBN-10 - http://worldcat.org/isbn/0950788120 or http://worldcat.org/isbn/0-9507881-2-0
** ISBN-13 - http://worldcat.org/isbn/9780950788128 or http://worldcat.org/isbn/978-0950788128

== ISSN ==

For [[isbn|ISSN]] codes, e.g. 0007-0335
*WorldCat - http://worldcat.org/issn/0007-0335 (hyphen mandatory)

==Journa-list==
*One word - http://www.journa-list.com/tags/letters
*Multi-word - http://www.journa-list.com/tags/royal+mail (plus sign)

==Last.FM==
* One word - http://last.fm/music/Radiohead
* One word - http://last.fm/music/Radiohead/Amnesiac
* Multi word - http://last.fm/music/Florence+and+the+Machine (plus sign separator)

==Technorati==
*One word - http://technorati.com/tag/cheese
*Multi-word - http://technorati.com/tag/apple+pie (plus sign)

==Wikipedia==
*One word - http://en.wikipedia.org/wiki/sugar
*Multi-word - http://en.wikipedia.org/wiki/brown_sugar (underscore)

===Issues (Wikipedia)===
*Case sensitivity (http://en.wikipedia.org/wiki/Perry_Barr works; http://en.wikipedia.org/wiki/perry_barr does not)
*Caution should be exercised when using Wikipedia as a name-space. For example, an article about Birmingham, Alabama, tagged with a link to http://en.wikipedia.org/wiki/Birmingham would link to an article about Birmingham, England.

==Wikitravel==
For place names.
*One word - http://wikitravel.org/en/London
*Multi-word - http://wikitravel.org/en/East_Grinstead (underscore)

===Issues (Wikitravel)===
*A tag using, e.g. http://wikitravel.org/en/Newcastle will link to a disambiguation page.

==Yedda==
For Questions & Answers:
*One word - http://yedda.com/questions/tags/technology
*Multi-word - http://yedda.com/questions/tags/home+improvement (plus sign)

For people (by interest):
*One word - http://yedda.com/questions/tags/technology
*Multi-word - http://yedda.com/people/tags/web+2.0 (plus sign)

==Related pages==
{{rel-tag-related-pages}}

rel-licence

2009-08-31T21:30:10Z

BenWard: en-gb redirect for License/Licence

#REDIRECT [[rel-license]]