Difference between revisions of "old-json-serializations"

From Microformats Wiki
old-json-serializations
Jump to navigation Jump to search
Line 109: Line 109:
 
}]   
 
}]   
 
</pre>
 
</pre>
 +
 +
==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.
 +
 +
<pre>
 +
microformats
 +
  vcard
 +
    ...
 +
      errors
 +
  xfn
 +
    ...
 +
      errors
 +
parser-information
 +
  name
 +
  version
 +
  page-http-status
 +
  page-title
 +
  page-url
 +
  time
 +
errors
 +
</pre>
 +
 +
===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 )'''
 +
<pre>{
 +
    "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"
 +
    }
 +
}
 +
</pre>
 +
 +
 +
'''Example JSON output ( minimal structure, more likely from a client-side parser )'''
 +
<pre>{
 +
    "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"   
 +
    }
 +
}
 +
</pre>
 +
 +
 +
'''Example JSON output of microformat level error'''
 +
<pre>{
 +
    "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"
 +
    }
 +
 
 +
}
 +
</pre>
 +
 +
 +
'''Example JSON output of a parser/page level error'''
 +
<pre>{
 +
    "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" ]
 +
}
 +
</pre>
 +
  
  

Revision as of 16:10, 10 May 2008

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

 
// 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"
}]  

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.

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