old-json-serializations

Standardised microformats representation in JSON - ufJSON

Introduction

Although the microformat design process did not originally have the concept of an output format, there are times when this would be useful. As parsers mature, we need an easy way to support the interchange and integration of data. Not just for parsers, but also for the applications that use them. A standard output format should encourage a greater culture of reuse and sharing between developers and help collaborative projects such as the building of shared test suites and other tools. JSON is well placed to be the foundations of that common data format. It works equally as well within client-side applications and server-side development languages.

This specification should be considered a draft. Contents are subject to change. It is provided here for reference and as a basis for discussion on the mailing list. This work in some ways extends the efforts around jCard, which had some of the same aims but was only focussed on hCard.

Authoring rules

Follow the logical structure of the microformat

• The structure of the JSON should follow the logical structure of the microformat in regard to nesting elements.

// Correct
"fn" : "John Doe",
"n" : {,
    "given-name" : ["John"],
    "family-name" : ["Doe"]
}

// Wrong - In hCard given-name is always a child of n 
"fn" : "John Doe",
"given-name" : ["John"],
"family-name" : ["Doe"]

Use the same property names as microformat equivalents

• All property names must be consistent with their equivalent microformat name. They should not be camel cased.
• All property names must be enclosed with double quotes to allow hyphenated properties.

// Correct
"fn" : "John Doe",
"n" : {,
    "given-name" : ["John"],
    "family-name" : ["Doe"]
}

// Wrong - givenName has been camel cased, it should be given-name
"fn" : "John Doe",
"n" : {,
    "givenName" : ["John"],
    "familyName" : ["Doe"]

Always use arrays for properties which can have multiple values

• Where the microformat specification allows a property to have multiple values always use an array even if only one value exists.

 
// Correct
"nickname" : ["lostboy", "man with no name"],
 url" : [ "http:\/\/www.joeblogs.com\/" ]
  
// Wrong - both nickname and url can have multiple values.
"nickname" : "lostboy",
"url" : "http:\/\/www.joeblogs.com\/"

Properties that are not set must be omitted

 // Wrong
 "email" : [],
 "bday" : ""

Escape JSON where needed

• Escape JSON values where needed.
• This is a http://json.org syntax rule

 
// Correct
 "url" : [ "http:\/\/www.joeblogs.com\/" ]
 
 // Wrong
 "url" : [ "http://www.joeblogs.com/" ]

Authoring rules that need discussion

There are a number of areas where there is no logical structure and naming convention to follow. This has caused the largest difference in data representation.

Representing XFN

XFN causes some major issues in terms of the differences in data representation. The Operator data structure would seem to be the most compact and less ambiguous.

Option for representation XFN

{ "xfn": [{
	"friend": "true",
	"met": "true",
	"link": "http:\/\/hackdaylondon07.backnetwork.com\/people\/person.aspx?personid=684",
	"text": "Andy Budd"
}]  

Representing rel-tag

There is a closer match between data structure to represent rel-tag. Because the value of a tag comes from the last fragment of the URL. It would be useful to include both a tag and text property in case they differ.

Option for representation rel-tag

{ "rel-tag": [{
	"tag": "hackday",
	"text": "hackday",
	"link": "http:\/\/technorati.com\/tags\/hackday"
}]  

References

• www.json.org: the original specification, documentation, and list of implementations for many different programming languages.
• RFC 4627, current formal JSON specification.
• JSON on Wikipedia