old-json-serializations

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 focused 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.
  • This is a JSON syntax rule anyway - do we need to restate it?

// 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
  • In JSON only the backslash, double quote and ASCII control characters need to be escaped. Forward slashes may be escaped as in the URL example below, but do not have to be.

 // Correct
 "note" : [ "My current job title is \"Interactive Designer\"" ]

 // Wrong
 "note" : [ "My current job title is "Interactive Designer"" ]
 
// Optional
 "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"
}]  

Envelope Structure

When navigating data from different applications it is useful to make the path of navigation consistent. The envelope structure provides a consistent start point for navigating the microformat data as well as providing an area for metadata. As a number of parsers and applications can process multiple formats at once the envelope starts with an array called microformats. It then contains individual arrays of each format request/supported.

There are two types of optional top level metadata. The first is parser-information, it contains information about the parser used and the document parsed. The second is an errors array, which when needed is populated with error messages. Each individual microformat data set can also have an optionally attached array of error messages where it is appropriate.

A new proposal that also addresses this area is SOAPjr - a hybrid of SOAP and JR (JSON-RPC). This adapts the SOAP/MIME Envelope/Head/Body separation into JSON.

microformats
  vcard
    ...
      errors
  xfn
    ...
      errors
parser-information
  name
  version
  page-http-status
  page-title
  page-url
  time
errors

Envelope Properties

microformats

An array of request/supported formats. Each array item should contain a property. The name of the property should be the name of the microformat. If the microformat has a root class name that should be used i.e. "vcard" else use the name from community wiki i.e. "xfn".

parser-information

Is an array of optional properties about the parser used and the document parsed

name

The parser of the application used to create the JSON

version

A string that represents the application version number i.e. "version 2" or "2.0"

page-http-status

The HTTP status number from the request page that was parsed. i.e. "200" or "404"

page-title

The HTML page title from the request page that was parsed

page-url'

The full URL of the request page that was parsed

time

The time taken to parse the page. Uses the ISO 8601 millisecond time format i.e. T000000.0087 is 87 milliseconds

errors

Is an optional array of string error messages.

Envelope Examples

Example JSON output ( single hCard )

{
    "microformats": {
        "vcard": [{
            "fn": "John Doe",
            "n": {
                "given-name": "John",
                "family-name": "Doe"
            },
            "url": ["http:\/\/www.johndoe.com\/"]
        }]
    },
    "parser-information": {
        "name": "UfXtract",
        "version": "0.1",
        "page-http-status": "200",
        "page-title": "hcard1";
        "page-url": "http:\/\/ufxtract.com\/testsuite\/hcard\/1.0\/hcard1.htm";
        "time": "T000000.0098"
    }
}

Example JSON output ( minimal structure, more likely from a client-side parser )

{
    "microformats": {
        "vcard": [{
            "fn": "John Doe",
            "n": {
                "given-name": "John",
                "family-name": "Doe"
            },
            "url": ["http:\/\/www.johndoe.com\/"]
        }]
    },
    "parser-information": {
        "name": "UfXtract",
        "version": "0.1",
        "page-title": "hcard1"    
    }
}

Example JSON output of microformat level error

{
    "microformats": {
       "vcard": [{
            "n": {
                "given-name": "John",
                "family-name": "Doe"
            },
            "url": ["http:\/\/www.johndoe.com\/"],
            "errors": [ "hCard does not contain the required fn property." ],
        }]

    },
    "parser-information": {
        "name": "UfXtract",
        "version": "0.1",
        "page-http-status": "200",
        "page-title": "hcard1";
        "page-url": "http:\/\/ufxtract.com\/testsuite\/hcard\/1.0\/nofilehere.htm";
        "time": "T000001.0002"
    }
   
}

Example JSON output of a parser/page level error

{
    "microformats": {
        "vcard": []
    },
    "parser-information": {
        "name": "UfXtract",
        "version": "0.1",
        "page-http-status": "404",
        "page-title": "hcard1";
        "page-url": "http:\/\/ufxtract.com\/testsuite\/hcard\/1.0\/nofilehere.htm";
        "time": "T000001.0002"
    },
    "errors": [ "URL not found" ]
}

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
• JSON-Schema Proposal
• SOAPjr's Common DMD's (Data Model Definitions)