Can anyone explain why ATOM was chosen over Plain Old XML (POX)?
From what I can see, ATOM is a great format for XML publishing when it is the only format. It was probably picked because industry wisdom is showing that ATOM is a good format for XML publishing. It does seem to get weak when trying to maintain compatibility between multiple formats. The spec goes through some odd contortions when going from JSONàATOM (I’m not a big fan of the hoisting rules). With the work in portable contacts, it seems pretty obvious that straight up XML avoids those odd contortions.
If this is something folks are interested in (I am!), I’d like to move away from Atom and towards POX. For example, Person would have this representation in JSON and POX:
MySpace.REST.Person as JSON
{
"gender":{"displayvalue":"女性","key":"FEMALE"},
"id":"example.org:34KJDCSKJN2HHF0DW20394",
"name":{"unstructured":"Jane Doe"}
}
MySpace.REST.Person as XML
<person xmlns="http://ns.opensocial.org/2008/opensocial">
<gender>
<displayvalue>女性</displayvalue>
<key>FEMALE</key>
</gender>
<id>example.org:34KJDCSKJN2HHF0DW20394</id>
<name>
<unstructured>Jane Doe</unstructured>
</name>
</person>
An explicit assumption here is that processors could ignore the xmlns for opensocial and just parse the data. Thoughts/comments?
The JSON and Atom versions are both accepted in 0.8 and the JSON features are not using the strict AtomPub CRUD model. Today, we are solving a set of problems with JSON that have solutions in Atom and we are winding up with deltas in capabilities and representations. Because of this set of deltas, we have moved to a place where understanding of the JSON model does not directly translate into an understanding of Atom. If the use cases support having both sets of capabilities, then we should keep both feature sets.
I am suggesting that we should add a third option: a straightforward mapping of JSONàPOX. Users who develop OpenSocial applications in Flash/ActionScript can process XML more easily than they can process JSON. The JSON model is simple and a POX model would be equally simple. I think it’s important to be explicit about what the POX representation looks like so that folks who work with XML have something easy to work with (as shown in the documentation, ATOM has a lot of data that isn’t needed when one chooses JSON).
The POX model should be simple enough to create and maintain. I can work with the REST authors to create the text, XSD, and examples for the POX model. Overall, this should be cheap to do as any problem for JSON is a problem for POX. Likewise, any solution for JSON will solve things for POX. It seems like a no-brainer to add this option.
From:
opensocial-an...@googlegroups.com
[mailto:opensocial-an...@googlegroups.com] On Behalf Of Cassie
Sent: Wednesday, August 13, 2008 4:50 PM
To: opensocial-an...@googlegroups.com
Subject: Re: restful spec - xml vs atom format
So how about the spec requires
format=xml for all calls, and format=atom only for activities calls? Or
something to that effect?
- Cassie
To speak to these points, we are finding that supporting ATOM and JSON is more expensive in terms of development time than supporting JSON and POX. It also seems like the ATOM rules to take advantage of CRUD have questionable value given that we need to tackle those CRUD issues for JSON. At the end of the day, a JSON solution is a POX solution. This minimizes the time we spend discussing how to solve problems. We also minimize the time spent discussing formats since we will never use the term “hoist” when discussing POX + JSON.
I would be more than happy to remove Atom from the spec since it complicates implementation and usage over JSON. Because we need XML for users that don’t have JSON parsers, POX seems to be a simplifying use case that would allow spec development and problem solving to move faster. POX is also more compact that ATOM, a fact that users will appreciate.
I do not disagree with the statement that blogs and activities have a more ATOM feel than POX. I simply state that we are solving these issues with JSON and the solutions have no deltas when we represent the same markup as POX. Example: Even the JSON-RPC proposed for batching has a natural flow to POX. It’s not clear to me that the batching has a natural extension into Atom.
Assuming that we go down this path, here is how the REST spec would change to allow for generic XML in addition to JSON and ATOM. (I’ve attached a PDF as well, in case this is unreadable for some mail clients)
Proposed edits to http://code.google.com/apis/opensocial/docs/0.8/restfulspec.html:
1. Overview
Existing Text |
New Text |
No single data representation is ideal for every client. This protocol defines dual representations for each resource in two widely supported formats, JSON [RFC4627] and Atom/AtomPub [RFC4287][RFC5023], using a set of generic mapping rules. The mapping rules allow a server to write to a single interface rather than implementing the protocol twice.
|
No single data representation is ideal for every client. This protocol defines representations for each resource in three widely supported formats, JSON [RFC4627], Atom/AtomPub [RFC4287][RFC5023], and XML using a set of generic mapping rules. The mapping rules allow a server to write to a single interface rather than implementing the protocol multiple times.
|
OpenSocial container servers are free to define additional representations but MUST support at least the JSON and Atom formats defined in this document.
|
OpenSocial container servers are free to define additional representations but MUST support at least the JSON, Atom, and XML formats defined in this document. |
2. Data Representations
Existing Text |
New Text |
Each resource has a two representations, as JSON and Atom (XML). All data must be representable in both formats, but we do not attempt to map from generic XML or Atom to JSON. Instead, we define an internal data model using English and JSON syntax, and then define the mappings between this and Atom/JSON. |
Each resource has three representations, as JSON, Atom (XML), and generic XML. All data must be representable in both formats, but we do not attempt to map from generic XML or Atom to JSON. Instead, we define an internal data model using English and JSON syntax, and then define the mappings between this and Atom/JSON as well as JSON and generic XML. |
Mapping consists of converting between the internal hierarchy and the JSON / Atom protocol format. |
Mapping consists of converting between the internal hierarchy and the JSON / Atom protocol /generic XML format. |
N/A |
(insert prior to “Examples of the primary types of data follow. Each example shows both representations, JSON and Atom, with the payload data highlighted for ease of comparison.”)
The general rules for mapping between the generic XML and JSON formats are as follows. · The default location for all data in the generic XML format is in datatype, where datatype is a root node naming the type of data delivered: <person>, <group>, <activity>, or <appdata>. · The field names are the same as in the JS documentation, in camelCase (the same format as the JS field accessors; e.g, "lastName". · Strings are represented as strings in both formats. · Dates and timestamps are represented as strings containing XML Schema Part 2, section 3.2.7 values (http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#dateTime). These are also known as "XSD Dates". In cases where only a day-of-the-year is desired, e.g., a birthday, the year SHOULD be specified as 0000. · Enums are represented as objects with "displayvalue" (localizable, customizable string) and "key" (key) fields. · Arrays are represented as arrays in the JSON representation and as repeated fields in the XML representation. · Sub-objects are represented as sub-elements in both formats. · Fields are placed directly in the root object in the JSON format. In the generic XML format, they are by default placed under datatype (e.g., person for person data). Fields are NEVER encoded as attributes on elements. Instead, fields are always included as elements plus text data.
|
Examples of the primary types of data follow. Each example shows both representations, JSON and Atom, with the payload data highlighted for ease of comparison |
Examples of the primary types of data follow. Each example shows representations in JSON, Atom, and generic XML with the payload data highlighted for ease of comparison |
|
|
2.1 Collections
Existing Text |
New Text |
Collections are a useful abstraction for dealing generically with multiple things, whether those things are persons, groups, activities, or application data sets. They have both Atom and JSON representations; the Atom representation is simply a standard Atom feed whose entries are one of the entry types specified above. The default JSON collection representation is a JSON object containing an "entry" slot containing a list of JSON objects. Collections use the OpenSearch conventions for reporting totalResults (for complete unpaged feed), startIndex of current page, and itemsPerPage. |
Collections are a useful abstraction for dealing generically with multiple things, whether those things are persons, groups, activities, or application data sets. They have the Atom, JSON and generic XML representations; the Atom representation is simply a standard Atom feed whose entries are one of the entry types specified above. The default JSON collection representation is a JSON object containing an "entry" slot containing a list of JSON objects. The default generic XML collection representation is a <collection> node containing an “entry” slot containing a list of generic XML elements. Collections use the OpenSearch conventions for reporting totalResults (for complete unpaged feed), startIndex of current page, and itemsPerPage. |
|
(insert as generic XML example) application/xml representation: <collection xmlns="http://ns.opensocial.org/2008/opensocial"> <author> example.org:58UIDCSIOP233FDKK3HD44 </author> <link> <rel>next</rel> <href>http://api.example.org/...</href> </link> <totalResults>100</totalResults> <startIndex>1</startIndex> <itemsPerPage>10</itemsPerPage> <entry> <entry>{...first thingie...}</entry> <entry>{...second thingie...}</entry> ... </entry> </collection> |
2.2 Person
Existing Text |
New Text |
|
(insert as generic XML example) application/xml representation: <person xmlns="http://ns.opensocial.org/2008/opensocial">> |
<id>example.org:34KJDCSKJN2HHF0DW20394</id> <name> <unstructured>Jane Doe</unstructured> </name> <gender> <displayvalue>女性</displayvalue> <key>FEMALE</key> </gender> |
</person> |
2.3 Group
Existing Text |
New Text |
|
(insert as generic XML example) application/xml representation: <group xmlns="http://ns.opensocial.org/2008/opensocial"> <id>example.org:34KJDCSKJN2HHF0DW20394/friends</id> <title>Peeps</title> <link> <rel>alternate</rel> <href>http://api.example.org/people/example.org:34KJDCSKJN2HHF0DW20394/@friends</href> </link> </group> |
2.4 Activity
Existing Text |
New Text |
|
(insert as generic XML example) application/xml representation: <activity xmlns="http://ns.opensocial.org/2008/opensocial"> <id>http://example.org/activities/example.org:87ead8dead6beef/self/af3778</id> <title> <type>html</type> <value> <a href="foo">some activity</a> </value> </title> <updated>2008-02-20T23:35:37.266Z</updated> <body>Some details for some activity</body> <bodyId>383777272</bodyId> <url>http://api.example.org/activity/feeds/.../af3778</url> <userId>example.org:34KJDCSKJN2HHF0DW20394</userId> </activity> |
2.5 AppData
Existing Text |
New Text |
|
(insert as generic XML example for isolated AppData) application/xml representation: <appdata xmlns="http://ns.opensocial.org/2008/opensocial"> <pokes>3</pokes> <last_poke>2008-02-13T18:30:02Z</last_poke> </appdata> |
|
(insert as generic XML example for AppData Collection) application/xml representation: <appdata xmlns="http://ns.opensocial.org/2008/opensocial"> <entry> <entry> <id>example.org:34KJDCSKJN2HHF0DW20394</id> <pokes>3</pokes> <last_poke>2008-02-13T18:30:02Z</last_poke> </entry> <entry> <id>example.org:58UIDCSIOP233FDKK3HD44</id> <pokes>2</pokes> <last_poke>2007-12-16T18:30:02Z</last_poke> </entry> </entry> </appdata> |
Please note that this version of the proposal does leave ATOM in place.
I would like to add that we should specify what ATOM looks like but should also reduce ATOM from a MUST implement to a MAY implement.
I’m not too sure how striking ATOM from OpenSocial prevents an implementation from supporting both ATOM and OpenSocial for uploading activities, messages, and blog posts. ATOM is already out there. We are defining a JSON implementation because not all of our users will have access to ATOM. We are defining a generic XML equivalence class because many environments (such as ActionScript) support XML significantly better than JSON (JSON in ActionScript is community support only and YMMV depending on the toolkit you grab).
Perhaps I’m wrong, but ATOM feels like an orthogonal concern.
I would have no problem if we had an appendix in the spec or a whitepaper that explained how activities, messages, and blog posts map from OpenSocial to ATOM. This would give developers/users an idea of how those concepts map between the worlds. I don’t see a reason to go beyond this and mandate that OpenSocial blog endpoints must also accept ATOM. I think the market will inform an implementation if it does or does not need to offer a feed for those types of resources.
I agree that this discussion is not about JSON. It is more about making sure that we have parity between JSON and XML. It seems that a generic XML piece achieves that goal.
After doing a lot of digging around, I am convinced that having ATOM for activities, messages, and blog posts has significant advantage. Can we agree to only include ATOM in those three cases?
+1 for ATOM.
----- Original Message -----
From: opensocial-an...@googlegroups.com <opensocial-an...@googlegroups.com>
To: opensocial-an...@googlegroups.com <opensocial-an...@googlegroups.com>
Sent: Tue Aug 19 11:01:05 2008
Subject: RE: restful spec - xml vs atom format
I agree that this discussion is not about JSON. It is more about making sure that we have parity between JSON and XML. It seems that a generic XML piece achieves that goal.
After doing a lot of digging around, I am convinced that having ATOM for activities, messages, and blog posts has significant advantage. Can we agree to only include ATOM in those three cases?
From: opensocial-an...@googlegroups.com [mailto:opensocial-an...@googlegroups.com] On Behalf Of John Panzer
Sent: Friday, August 15, 2008 4:06 PM
To: opensocial-an...@googlegroups.com
Subject: Re: restful spec - xml vs atom format
The discussion at the moment is not about JSON, but about an XML representation for the various types and operations that OpenSocial supports. What I'm saying is that there is an existing industry standard for activities/messages/blogposts that is almost completely a 1:1 semantic mapping to what OpenSocial supports. It can support those ActionScript clients as well as a bespoke format, and has significantly higher existing infrastructure and ecosystems to plug into.
The problem with making Atom support a MAY is that it doesn't really specify anything -- any container MAY add whatever interfaces it likes. However, clients can't depend on it, hence must write to the MUSTs or (if they're feeling adventurous) the SHOULDs.
For example, should we go to the My Life Cast <http://lifecast.sleepydog.net/> iPhone app (AtomPub client) and tell them they'll have to add a non-standard format for OpenSocial activities rather than just using their existing code? (That's just an offhand example.)
+1
+1