restful spec - xml vs atom format

[Cassie]

While going through the portable contacts changes for 0.8.1 I realized we have a slight formatting discrepancy between portable contacts xml format and the opensocial restful atom format.

The portable contacts description of the format parameter is very simple:

Specifies the format in which the response data is returned. Service Providers MUST support the values json for JSON (http://json.org) and xml for XML (http://www.w3.org/XML/) and MAY support additional formats if desired. The format defaults to json if no format is specified. The data structure returned is equivalent in both formats; the only difference is in the encoding of the data. Singular Fields are encoded as string key/value pairs in JSON and tags with text content in XML, e.g. "field": "value" and <field>value</field> respectively. Plural Fields and Plural Bundles are encoded as arrays in JSON and repeated tags in XML, e.g. "fields": [ "value1", "value2" ] and <fields>value1</field><fields<value2</field> respectively. Nodes with multiple sub-nodes are represented as objects in JSON and tags with sub-tags in XML, e.g. "field": { "subfield1": "value1", "subfield2": "value2" } and <field><subfield1><value1></subfield1><subfield2>value2</subfield2></field> respectively.

Whereas the opensocial restful docs are more complicated in that it includes a lot of discussion about conforming to atom/atompub.

So, the first point is that opensocial restful will have to support format=xml in order to be compliant with the portable contacts spec.

And my second point here is.. do we really need the atom format? Can we change our spec to only demand a simpler xml format - just like portable contacts? The portable contacts spec also says that containers are free to add support for other formats, so some containers could support an "atom" format if they wished (with their own hoisting rules defined), but we would only require a simple xml format to be compliant.

What do people think?
Thanks.

- Cassie

[Scott Seely]

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.

[Chris Chabot]

+1 on the concept of Plain Old XML.

Atom is great for a lot of things, but i don't really see the data domains of what Atom was 'intended for' and social data being a match made in heaven, and the hoisting rules seem to reflect that fact.

-- Chris

[Scott Seely]

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?

[John Panzer]

Do you mean this question specifically for the People data, or for all of the data that OpenSocial supports (including activity streams and messages specifically)?  My answer would be somewhat different depending on the scope :).

John Panzer (http://abstractioneer.org)

[Cassie]

Scott - I definitely think this is important too.

John - well we need to address this for people first off in order to align with the portable contacts proposal. However, I agree with Scott's sentiment in that atom at this point in time is overkill for the spec. Containers could still support format=atom but the spec should only require format=xml. (Which is exactly how portable contacts works)

- Cassie

[John Panzer]

Yes, except that portable contacts is only about people data, whereas OpenSocial has more kinds of data.

I think it would be very reasonable to use our own XML format for People and AppData; there is no standard for these anyway.

It's another kettle of fish to invent yet another XML format for feed data (which is what Activities are).  Same comment for blog posts and probably messages, all of which fit into this general category. 

John Panzer (http://abstractioneer.org)

[Kevin Marks]

Also, PortableContacts is read-only, whereas OpenSocial is read/write, and the existing AtomPub protocol makes sense for feed entry posting (and will get de facto support for activity streams integrated into blogging tools).

The strict AtomPub CRUD model has some potential problems with subfields and required round-tripping, but the partial updates discussion for UserData seems to clarify that.

[Cassie]

So how about the spec requires format=xml for all calls, and format=atom only for activities calls? Or something to that effect?

- Cassie

[Scott Seely]

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

[Chris Chabot]

One concern i have though is the impact that this growth of formats will have on the likeliness that everyone will support everything.

In the open source world there's the php and java versions of shindig, and I'm not worried about those two, however there's also work in progress for a c# version, and we all hope to see more implementations i think. Next to that there's also an N number of non open source implementations. (where i think N = 2, but it could be more so don't hold me to that :))

Right now as it looks a implementation would have to support:

- Atom in & output

- POX in & output

- JSON in & output

- JSON-RPC in & output.

Are at risk that this will create a barrier, both for implementation and thus also for adaptation (common denominator)?

Ps: I'm well aware that with a decent internal data representation implementation of all those formats is somewhat trivial, but i think experience has also shown us that such complex solutions do hinder adaptation.

-- Chris

[Scott Seely]

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.

[David Primmer]

Would it be possible for us to use somewhat more precise language when
talking about these APIs?. It's often helpful to refer to the wire
format, Atom Syndication format, and the CRUD protocol, Atom
Publishing Protocol as individual standards (they are separate RFCs).
You cannot really conflate POX with Atom Pub, but you can compare the
Atom Synd wire format to POX. I've often felt like it would be more
illustrative of the power of Atom Pub to have more standard wire
formats for it, especially one that allows a looser schema. I just
wanted to point out that there are interop benefits to both the wire
format and the crud ops and the initial spec was an attempt to
separate the two and have Atom Pub used by two different wire formats.

davep

[Kevin Brown]

The most likely outcome is going to be that many organizations will simply stop supporting some formats. It's not practical to maintain a half dozen, especially as their semantics continue to further diverge.

[Evan Gilbert]

I think the underlying assumption with POX and JSON is that the implementation will be exactly 1:1, and it is just a different serialization format for the data structure. If so, the cost to maintain & document the additional API is minimal.

+1 on supporting format=xml as long as the implementers feel this is minimal work.

No opinion yet on removing format=atom - I don't feel like I know what we'd be giving up.

[Scott Seely]

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>

[Scott Seely]

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.

[Cassie]

+1 for scott's modifications.

2008/8/14 Scott Seely <SSe...@myspace.com>

[Chris Chabot]

I'm +1 on removing the Atom part of the REST spec.

We need the &format=xml protocol to support PortableContacts, and implementation wise it seems a lot easier to have a 1:1 mapping between the JSON and XML formats, then to force the hoisting rules of Atom conversion on our selves. 

If we'd end up with the situation where one container supports xml+json, another atom+xml and another json+atom (which is likely to happen if we force such complexities), what's a gadget dev supposed to do ? :) Lets please try to avoid that.

-- Chris

[John Panzer]

I'm -1 on removing Atom for activities / messages / blog posts.  The delta for People and AppData is basically "move the stuff that would otherwise be in the Atom <content> and make it top level, and create a <collection> type to hold multiple of these".  That's a fairly minor change, and standard libraries don't give you as much leverage with these (though I suspect we're going to re-invent the same synchronization protocol that AtomPub already has... and your XML collection is exactly the same as an Atom feed, except with the root node renamed, so it seems a bit silly.)

The argument for re-inventing feeds is a lot less compelling.  We'd be throwing away compatibility with an entire ecosystem of tools and web services in order to have some (slight) compatibility with a newly invented format.

Finally, putting on my Blogger hat, we already have developers creating solutions that work with AtomPub (just got a new one on my iPhone today) and making them learn Yet Another Way to push time oriented series of entries in a new format is just plain silly.  Sure, if they want to use JSON, they need to learn a new syntax; if they like XML already then AtomPub is designed for exactly this task.

It's an unfortunate fact that the existing OpenSocial Activity fields, while they map 90% to standard AtomPub fields, weren't named that way.  Rather than invent a new competing feed format, I'd propose that we rename the fields to the industry standard terms and just use AtomPub.  So for Activities, your collection is spelled <feed> but everything else is the same.

John Panzer (http://abstractioneer.org)

[Scott Seely]

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.

[John Panzer]

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 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.)

John Panzer (http://abstractioneer.org)

[anand sharma]

Hi to All
i checked out latest Shindig code of Revision no : 686151
I have created my own PHP shindig Basic{People,Activities,Data}.php 
and few gadgets like "helloworld.xml" , "GeoLocation.xml" are working absoultely fine,
THX to Chris who help me out so that shindig PHP is working fine.
But whenever i am running any gadget which is using Basic{people,activities,data}.php , it has some probs.
suppose whenever i am running ListFriends.xml file in Shindig PHP , its giving response in firebug as :
1.
POST http://localhost/shindig/php/social/rest/jsonBatch?st=6%3A6%3A6396%3Ashindig%3Ahttp%253A%2F%2Flocalhost%2FGOSDemoAppPHP%2Fgadgets%2FListFriends.xml%3A0 (1062ms) 


POST:

{"viewer":{"url":"/people/@viewer/@self?fields=id,name,thumbnailUrl&startIndex=0&count=20&orderBy=topFriends

&filterBy=all&networkDistance=","method":"GET"},"viewerFriends":{"url":"/people/@viewer/@friends?fields

=id,name,thumbnailUrl&startIndex=0&count=20&orderBy=topFriends&filterBy=all&networkDistance=","method"

:"GET"}}


RESPONSE:

{"responses":{"viewer":{"response":{"6":{"aboutMe":"Its all abt the fact :-)","dateOfBirth":"1985-11-22"

,"id":"6","name":{"unstructured":"ak47"},"isOwner":false,"isViewer":false}}},"viewerFriends":{"response"

:{"1":{"aboutMe":"\tWhen I am working on a problem I never think about beauty. I only think about how

 to solve the problem. But when I have finished, if the solution is not beautiful, I know it is wrong

.\r\n","dateOfBirth":"1991-01-01","id":"1","name":{"unstructured":"Venkata Suresh"},"isOwner":false,"isViewer"

:false},"2":{"aboutMe":"\tI am a man of fixed and unbending principles, the first of which is to be flexible

 at all times.","dateOfBirth":"1992-02-01","id":"2","name":{"unstructured":"Ganesh Kumar"},"isOwner"

:false,"isViewer":false},"3":{"aboutMe":"\tI always try to believe the best of everybody -- it saves

 so much trouble.\r\n","dateOfBirth":"1993-03-01","id":"3","name":{"unstructured":"Ashok kumar"},"isOwner"

:false,"isViewer":false},"4":{"aboutMe":"Kool!!!","dateOfBirth":"1985-01-01","id":"4","name":{"unstructured"

:"Sanjeev Srinidhi"},"isOwner":false,"isViewer":false},"5":{"aboutMe":"nagraju mast maja maadi !!!!!

!!!!","dateOfBirth":"1985-12-11","id":"5","name":{"unstructured":"nagraju"},"isOwner":false,"isViewer"

:false},"7":{"aboutMe":"Devil also scare to enter in my domain","dateOfBirth":"1985-11-22","id":"7","name"

:{"unstructured":"machi"},"isOwner":false,"isViewer":false}}}},"error":false}



As far i know that i am getting right response but i cannot able to see these response as my result of gadget(ListFriends.xml) output.

i think according to my own BasicPeople.php , i have to change any other files.

if is it so then please let me own the way .

may be i going in wrong way .


Cheers

Anand 

[Scott Seely]

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?

[Chuck Rosendahl]

+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.)

[Cassie]

Okay, so this is obviously not resolving very quickly. Here is what I am going to do for 0.8.1:
- leave the atom stuff in the spec as is
- add a new format called "xml" which matches the portable contacts format. declare that this is MUST for people uris and a MAY for everything else

Note that:
- I do not believe this is the right long term answer for either developers or container implementers
- I do believe that there more discussion that needs to happen but I believe the actual implementations and client libraries will give us better feedback than just theorizing.

So, we can reconsider this for 0.9 but for now the change is staying as minimal as possible in order to get 0.8.1 out the door.
Thanks!

- Cassie

[Scott Seely]

+1

[Kevin Marks]

+1 on this for now.
We should indeed keep Atom for activities and messages as this is the de facto standard for feeds, and a common format for activity streams is something we should be encouraging even across sites that don't fall into our current model of Containers - twitter, jaiku, pownce, identi.ca, friednfeed, socialthing and others all have users, some kind of friend relationship and activity streams, and all support feeds at the moment, so picking something arbitrarily different seems very wrong to me.

Also, with the various blogging services such as MT, Wordpress and DiSo thinking about thsi space too, adapting to a world of feeds is a good thign - feeds are the only real success of XML on the web.

[John Panzer]

+1 - though I'd be happier to:

1. Eliminate Atom for people and appdata now, and
2. Keep Atom for activities, messages, and blog posts (feed/message oriented data)

So each type of data has only 2 dialects, though you have to read each section in order to figure out what they are. 

If there were consensus around that I'd give it a +1 too.

John Panzer (http://abstractioneer.org)

[Chris Chabot]

+1 on this proposal, better to keep moving forward and punt it for 0.9 then keep stalling on this.

Thanks for summarizing- & taking action on this Cassie!

-- Chris

[Evan Gilbert]

+1

[Scott Seely]

+1

[Balaji Srinivasan]

+1 (same comments as John)

[Marco Ensing]

+1 for Atom

> On Fri, Aug 15, 2008 at 11:10 AM, Chris Chabot <chab...@xs4all.nl> wrote:
>
> I'm +1 on removing the Atom part of the REST spec.
>
> We need the &format=xml protocol to support PortableContacts, and implementation wise it seems a lot easier to have a 1:1 mapping between the JSON and XML formats, then to force the hoisting rules of Atom conversion on our selves.
>
> If we'd end up with the situation where one container supports xml+json, another atom+xml and another json+atom (which is likely to happen if we force such complexities), what's a gadget dev supposed to do ? :) Lets please try to avoid that.
>
>             -- Chris
>
> On Aug 14, 2008, at 8:00 PM, Evan Gilbert wrote:
>
> I think the underlying assumption with POX and JSON is that the implementation will be exactly 1:1, and it is just a different serialization format for the data structure. If so, the cost to maintain & document the additional API is minimal.
>
> +1 on supporting format=xml as long as the implementers feel this is minimal work.
>
> No opinion yet on removing format=atom - I don't feel like I know what we'd be giving up.
>

> On Thu, Aug 14, 2008 at 9:50 AM, Kevin Brown <e...@google.com> wrote:
>
> The most likely outcome is going to be that many organizations will simply stop supporting some formats. It's not practical to maintain a half dozen, especially as their semantics continue to further diverge.
>

> On Thu, Aug 14, 2008 at 4:25 AM, Chris Chabot <chab...@xs4all.nl> wrote:
>
> One concern i have though is the impact that this growth of formats will have on the likeliness that everyone will support everything.
>
> In the open source world there's the php and java versions of shindig, and I'm not worried about those two, however there's also work in progress for a c# version, and we all hope to see more implementations i think. Next to that there's also an N number of non open source implementations. (where i think N = 2, but it could be more so don't hold me to that :))
>
> Right now as it looks a implementation would have to support:
>
> - Atom in & output
>
> - POX in & output
>
> - JSON in & output
>
> - JSON-RPC in & output.
>
> Are at risk that this will create a barrier, both for implementation and thus also for adaptation (common denominator)?
>
> Ps: I'm well aware that with a decent internal data representation implementation of all those formats is somewhat trivial, but i think experience has also shown us that such complex solutions do hinder adaptation.
>
>             -- Chris
>
> On Aug 14, 2008, at 2:07 AM, Scott Seely wrote:
>
> 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
>

> On Wed, Aug 13, 2008 at 4:47 PM, Kevin Marks <kevinma...@google.com> wrote:
>
> Also, PortableContacts is read-only, whereas OpenSocial is read/write, and the existing AtomPub protocol makes sense for feed entry posting (and will get de facto support for activity streams integrated into blogging tools).
>
> The strict AtomPub CRUD model has some potential problems with subfields and required round-tripping, but the partial updates discussion for
>

> ...
>
> read more »- Hide quoted text -
>
> - Show quoted text -