Difference between revisions of "old-json-serializations"

From Microformats Wiki
old-json-serializations
Jump to navigation Jump to search
m (Replace <entry-title> with {{DISPLAYTITLE:}})
 
(9 intermediate revisions by 6 users not shown)
Line 1: Line 1:
= Standardised microformats representation in JSON - ufJSON =
+
{{DISPLAYTITLE:ufJSON or a Standard JSON Serialization for Microformats}}
  
==Introduction==
+
= 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.  
 
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.
+
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==
+
{{TOC-right}}
  
 +
= Authoring Rules =
  
 
'''Follow the logical structure of the microformat'''
 
'''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.  
+
 
 +
* The structure of the JSON should follow the logical structure of the microformat in regard to nesting elements.
 +
 
 
<pre>// Correct
 
<pre>// Correct
 
"fn" : "John Doe",
 
"fn" : "John Doe",
"n" : {,
+
"n" : {
 
     "given-name" : ["John"],
 
     "given-name" : ["John"],
 
     "family-name" : ["Doe"]
 
     "family-name" : ["Doe"]
Line 26: Line 28:
 
</pre>
 
</pre>
  
 +
'''Use the same property names as microformat equivalents'''
  
'''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 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.
+
* 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?
  
 
<pre>// Correct
 
<pre>// Correct
 
"fn" : "John Doe",
 
"fn" : "John Doe",
"n" : {,
+
"n" : {
 
     "given-name" : ["John"],
 
     "given-name" : ["John"],
 
     "family-name" : ["Doe"]
 
     "family-name" : ["Doe"]
Line 40: Line 43:
 
// Wrong - givenName has been camel cased, it should be given-name
 
// Wrong - givenName has been camel cased, it should be given-name
 
"fn" : "John Doe",
 
"fn" : "John Doe",
"n" : {,
+
"n" : {
 
     "givenName" : ["John"],
 
     "givenName" : ["John"],
 
     "familyName" : ["Doe"]
 
     "familyName" : ["Doe"]
 
+
}
 
</pre>
 
</pre>
  
 +
'''Always use arrays for properties which can have multiple values'''
  
'''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.
 
* Where the microformat specification allows a property to have multiple values always use an array even if only one value exists.
  
Line 60: Line 63:
 
</pre>
 
</pre>
  
 +
'''Properties that are not set must be omitted'''
  
'''Properties that are not set must be omitted'''
 
 
<pre> // Wrong
 
<pre> // Wrong
 
  &quot;email&quot;&nbsp;: [],
 
  &quot;email&quot;&nbsp;: [],
Line 67: Line 70:
 
</pre>
 
</pre>
  
 +
'''Escape JSON where needed'''
  
'''Escape JSON where needed'''
 
 
* Escape JSON values where needed.
 
* Escape JSON values where needed.
 
* This is a http://json.org syntax rule
 
* 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.
 +
 +
<pre>
 +
// Correct
 +
&quot;note&quot; : [ &quot;My current job title is \"Interactive Designer\"&quot; ]
  
<pre>
+
// Wrong
// Correct
+
&quot;note&quot; : [ &quot;My current job title is "Interactive Designer"&quot; ]
 +
 +
// Optional
 
  &quot;url&quot; : [ &quot;http:\/\/www.joeblogs.com\/&quot; ]
 
  &quot;url&quot; : [ &quot;http:\/\/www.joeblogs.com\/&quot; ]
 
// Wrong
 
&quot;url&quot; : [ &quot;http://www.joeblogs.com/&quot; ]
 
 
</pre>
 
</pre>
  
==Authoring rules that need discussion==
+
= 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.
 
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'''
 
'''Representing XFN'''
Line 96: Line 103:
 
}]   
 
}]   
 
</pre>
 
</pre>
 
  
 
'''Representing rel-tag'''
 
'''Representing rel-tag'''
Line 110: Line 116:
 
</pre>
 
</pre>
  
==Envelope structure==
+
= 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.
 
  
 +
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,  
+
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.
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.  
+
A new proposal that also addresses this area is [http://SOAPjr.org SOAPjr] - a hybrid of [http://en.wikipedia.org/wiki/SOAP_(protocol) SOAP] and [http://en.wikipedia.org/wiki/JSON-RPC JR (JSON-RPC)].  This adapts the SOAP/MIME Envelope/Head/Body separation into JSON.
Each individual microformat data set can also have an optionally attached array  
 
of error messages where it is appropriate.
 
  
 
<pre>
 
<pre>
Line 143: Line 142:
 
</pre>
 
</pre>
  
===Envelope properties===
+
== Envelope Properties ==
 +
 
 +
'''microformats'''
  
'''microformats'''<br/>
 
 
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".  
 
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'''<br/>
+
'''parser-information'''
 +
 
 
Is an array of optional properties about the parser used and the document parsed
 
Is an array of optional properties about the parser used and the document parsed
 
   
 
   
'''name'''<br/>
+
'''name'''
 +
 
 
The parser of the application used to create the JSON  
 
The parser of the application used to create the JSON  
  
'''version'''<br/>
+
'''version'''
 +
 
 
A string that represents the application version number i.e. "version 2" or "2.0"  
 
A string that represents the application version number i.e. "version 2" or "2.0"  
  
'''page-http-status'''<br/>
+
'''page-http-status'''
 +
 
 
The HTTP status number from the request page that was parsed. i.e. "200" or "404"  
 
The HTTP status number from the request page that was parsed. i.e. "200" or "404"  
  
'''page-title'''<br/>
+
'''page-title'''
 +
 
 
The HTML page title from the request page that was parsed  
 
The HTML page title from the request page that was parsed  
  
''page-url'''<br/>
+
''page-url'''
 +
 
 
The full URL of the request page that was parsed  
 
The full URL of the request page that was parsed  
  
'''time'''<br/>
+
'''time'''
 +
 
 
The time taken to parse the page. Uses the ISO 8601 millisecond time format i.e. T000000.0087 is 87 milliseconds  
 
The time taken to parse the page. Uses the ISO 8601 millisecond time format i.e. T000000.0087 is 87 milliseconds  
  
'''errors'''<br/>
+
'''errors'''
 +
 
 
Is an optional array of string error messages.  
 
Is an optional array of string error messages.  
  
 +
== Envelope Examples ==
  
===Envelope examples===
+
'''Example JSON output ( single hCard )'''
  
'''Example JSON output ( single hCard )'''
 
 
<pre>{
 
<pre>{
 
     "microformats": {
 
     "microformats": {
Line 198: Line 206:
 
</pre>
 
</pre>
  
 +
'''Example JSON output ( minimal structure, more likely from a client-side parser )'''
  
'''Example JSON output ( minimal structure, more likely from a client-side parser )'''
 
 
<pre>{
 
<pre>{
 
     "microformats": {
 
     "microformats": {
Line 219: Line 227:
 
</pre>
 
</pre>
  
 +
'''Example JSON output of microformat level error'''
  
'''Example JSON output of microformat level error'''
 
 
<pre>{
 
<pre>{
 
     "microformats": {
 
     "microformats": {
Line 245: Line 253:
 
</pre>
 
</pre>
  
 +
'''Example JSON output of a parser/page level error'''
  
'''Example JSON output of a parser/page level error'''
 
 
<pre>{
 
<pre>{
 
     "microformats": {
 
     "microformats": {
Line 263: Line 271:
 
</pre>
 
</pre>
  
 
+
= References =
 
 
==References==
 
  
 
*[http://www.json.org www.json.org]: the original specification, documentation, and list of implementations for many different programming languages.
 
*[http://www.json.org www.json.org]: the original specification, documentation, and list of implementations for many different programming languages.
 
*RFC 4627, current formal JSON specification.
 
*RFC 4627, current formal JSON specification.
 
*[http://en.wikipedia.org/wiki/JSON JSON on Wikipedia]
 
*[http://en.wikipedia.org/wiki/JSON JSON on Wikipedia]
 +
*[http://json-schema.org/ JSON-Schema Proposal]
 +
*[http://soapjr.org/specs.html#dmd SOAPjr's Common DMD's (Data Model Definitions)]

Latest revision as of 16:30, 18 July 2020


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