jcard

jCard 0.1

A jCard is a standardized representation of an hCard encoded in JSON.

Introduction

A jCard is a standardized representation of an hCard encoded in JSON. The primary aim of a jCard is to provide a standardized JSON output in Microformat parsers to allow for easier interchange and integration with other applications.

The term jCard was first coined by Jon Sykes und Jim Barraud of the MicroJSON project. The MicroJSON wiki was also the first to come up with a standard for this format. This standard however is incomplete and inconsistent in regards to property names and structure. The specification presented here is a completely new attempt at defining a standard representation and only borrows the name from the original jCard specification at MicroJSON.org.

The specification is considered a draft. Contents are subject to change. It is provided here for reference and a basis for discussion on the mailing list.

Format

Authoring rules

• The structure of a jCard follows the logical structure of an hCard in regard to nesting elements.

  <p class="note">You can e-mail me at <a class="email"
  href="mailto:me@example.com">me@example.com</a>.</p>

 // Correct
 {
   "note" : ["You can e-mail me at me@example.com."],
   "email" : [{ value: "me@example.com" }]
 }
 
 // Wrong
 {
   "note" : [{
     "value" : "You can e-mail me at me@example.com.",
     "email" : [{ value: "me@example.com" }]
   }]
 }

• All property names must be consistent with their equivalents in hCard.
• All property names must be enclosed with quotes to allow hyphenated properties.
• Singular instance properties use only their corresponding datatype for value:

 // Correct
 fn = 'John Doe'
 uid = 'http://jdoe.example.com'
 
 // Wrong
 fn = {value: 'John Doe'}
 uid = ['http://jdoe.example.com']

• All properties that may have multiple instances use an Array of their corresponding datatype.

 // Correct
 nickname = ['Rio Demonhog', 'Gus Aspara']

• Properties that are not set must be omitted.

 // Correct
 email = [
   {type: ['pref'], value: 'foo at example.com'},
   {value: 'bar at example.com'}
 ]

• A type property must not be the only property of an Object.

 // Wrong
 email = [{type: 'pref'}]

The following is still undecided and needs further discussion

• Option a) Enclosing Arrays or Objects must NOT be reduced.

 // Wrong
 email = 'bar at example.com'
 
 // Correct
 email = [{value: 'bar at example.com'}]

• Option b) Enclosing Arrays or Objects MUST be reduced

 // Wrong
 email = [{value: 'bar at example.com'}]
 nickname = ['Gogo Fiasco']

 // Correct
 email = 'bar at example.com'
 email = [
   {type: ['pref'], value: 'foo at example.com'},
   'foobar at example.com'
 ]
 nickname = 'Gogo Fiasco'

• Option c) Enclosing Arrays or Objects MAY be reduced

 // Correct
 email = [{value: 'bar at example.com'}]
 email = 'bar at example.com'
 email = [
   {type: ['pref'], value: 'foo at example.com'},
   'foobar at example.com'
 ]
 nickname = ['Gogo Fiasco']
 nickname = 'Gogo Fiasco'

Field and Element Details

[ This section is a placeholder and should be replaced with field descriptions ]

Implementations

The author of Optimus have announced their support of jCards.

A proof-of-concept jCard web service is available (powered by Cognition) at http://srv.buzzword.org.uk/jcard/. To use it, simply append the URL of an hCard page (minus the "http://"). e.g.

http://srv.buzzword.org.uk/jcard/www.example.com/contact.html

Criticism

Critics argued, that there is no need for a jCard standard. In order to preserve the semantics of microformats, the entire marked up HTML or the URI should be passed between applications. Applications should then decide by themselves on how to represent a Microformat internally.

• Say I'm writing an online address book app. I don't want to have to include hCard parsing code in the app itself. hCard parsing is a lot of work and intentionally so. I don't want to re-invent the wheel. I want to simply plug in an existing parser, and take the output from that. The output from this parser should conform to an interoperable standard so that I don't need to worry about having to change my code every time I upgrade the parser, and so that I can choose to switch to a different parser altogether if need be - interoperability, avoiding vendor lock-in. vCard is not a good candidate for such an output format, as it would require a lot of parsing effort in itself. jCard can be parsed with widely available libraries for JSON.

References

• MicroJSON.org - The original jCard specification at the MicroJSON Project
• jCard UML diagram - Note: this version still uses the camelCase properties.