Align OpenSocial and Poco in fields definitions in v 1.0

According to the discussions on:
http://wiki.opensocial.org/index.php?title=PoCo_Alignment_for_v1.0

And some early discussions:
http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/dab9259d623c1397/bc704b41e6f5672b

[Lane, 2009-11-23 18:00:14]

Thanks for digging into all these details!  I think there are a few high-level
issues we need to iron out...

1) Make sure to work with Jon Weygandt and make sure the changes to the data
model make it into the Social-Data.xml spec.

2a) A request for a single object, should get a single object (without fields
like itemsPerPage, etc).   The way you changed the text makes all requests
return a collection.

2b) A request for a collection should get a collection (even if there's just one
item in it).  The current spec says we should return a single object (instead of
an array) and add fields like itemsPerPage, etc.  I'm proposing we change/fix
this.

3) I'm not sure we can just change <person>, <activities>, etc. to <entry>. 
Seems like I should get a clue about whether to parse the <entry> as a person, 
activity, etc.  This is not an issue for PoCo since they only have one data type
(i.e. person).  Also, this would change the XSD significantly as it currently
refers to <person>, <activity> etc.

-Lane

http://codereview.appspot.com/152119/diff/1/2
File draft/REST-API.xml (right):

http://codereview.appspot.com/152119/diff/1/2#newcode192
draft/REST-API.xml:192: <preamble>or, for those methods designed to return only
one item:</preamble>
This changes the intent of the spec.  The example says if you request a list,
but there is only one result, entry will be a single object, not an array.  this
seems wrong...we should always return a collection if a collection is requested.

The text you have says that all methods return a collection, in that the
response will container fields like itemsPerPage.  This doesn't make sense for
requests like getOnwer - where only a single object will ever be returned.

http://codereview.appspot.com/152119/diff/1/2#newcode271
draft/REST-API.xml:271: &lt;entry
xmlns="http://ns.opensocial.org/2008/opensocial"&gt;
If I get this XML, how do I know to parse it as a person, activity, or something
else?

http://codereview.appspot.com/152119/diff/1/2#newcode1625
draft/REST-API.xml:1625: <section title="Singular Person Fields">
Please work with Jon Weygandt to make sure these changes make it into the
Social-Gadget.xml file.

[Jacky Wang, 2009-11-24 07:36:11]

Fix the multiple / single resp object wording issue.

[Jacky Wang, 2009-11-24 07:40:24]

Thanks for Lane's review!

@Jon, shall we have a quick sync on the XML-schema part? I've made some fields
changes to keep the spec compliant with Portable Contact (PoCo for short) spec.

Thanks,
Jacky

http://codereview.appspot.com/152119/diff/1/2
File draft/REST-API.xml (right):

http://codereview.appspot.com/152119/diff/1/2#newcode192
draft/REST-API.xml:192: <preamble>or, for those methods designed to return only
one item:</preamble>
Totally agree - my idea is: for those methods which designed to return
collection, the return value should be collection, even it contains only 1 item;
for those methods which designed to return item, only 1 item should be returned.

Maybe we need to change the wording here a bit thus make sure the above idea is
clearer. :)

There's a draft about this effort in the patch 2.

On 2009/11/23 18:00:14, Lane wrote:
> This changes the intent of the spec.  The example says if you request a list,
> but there is only one result, entry will be a single object, not an array. 
this
> seems wrong...we should always return a collection if a collection is
requested.
> 
> The text you have says that all methods return a collection, in that the
> response will container fields like itemsPerPage.  This doesn't make sense for
> requests like getOnwer - where only a single object will ever be returned.
> 
>

http://codereview.appspot.com/152119/diff/1/2#newcode271
draft/REST-API.xml:271: &lt;entry
xmlns="http://ns.opensocial.org/2008/opensocial"&gt;
According to the mail I've received on Apr 23:

The only issue here is that we recently came to consensus that we should be
using <entry> for all data types (instead of <person>, <activity>, etc.). 
Although this came after v0.9 was approved, but is basically a bug (since we
state that we're aligned with PoCo) I'm hoping we can patch the spec and get
this impl out for v0.9 releases. 

Thus I change all the tags into <entry>.

On 2009/11/23 18:00:14, Lane wrote:
> If I get this XML, how do I know to parse it as a person, activity, or
something
> else?

http://codereview.appspot.com/152119/diff/1/2#newcode1625
draft/REST-API.xml:1625: <section title="Singular Person Fields">
Thanks for point it out!  Is his addr Jon.Weygandt@gmail.com?

On 2009/11/23 18:00:14, Lane wrote:
> Please work with Jon Weygandt to make sure these changes make it into the
> Social-Gadget.xml file.

[Jon Weygandt, 2009-11-24 18:13:10]

Jacky - Shortly I'll release patch set 7 for:
http://codereview.appspot.com/154120/show that should include the changes
indicated below. Please review it to see that I have correctly applied your
changes.

The RPC document does not seem to have any changes for Social or Core Data docs.
The XML schema would probably go elsewhere as well.

http://codereview.appspot.com/152119/diff/1003/2001
File draft/REST-API.xml (right):

http://codereview.appspot.com/152119/diff/1003/2001#newcode163
draft/REST-API.xml:163: be 0 or 1 matching results. (i.e. "entry": [ { /* first
item */ }, { /* second item */ } ]).</t>
See the diffs for Core-Data.xml

http://codereview.appspot.com/152119/diff/1003/2001#newcode1655
draft/REST-API.xml:1655: <c>age</c>
Added to Social-Data.xml

http://codereview.appspot.com/152119/diff/1003/2001#newcode1692
draft/REST-API.xml:1692: <c>hasApp</c>
Added to Social-Data.xml.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1749
draft/REST-API.xml:1749: smoker, status, and thumbnailUrl.  The field
currentLocation is deprecated in 1.0
profileUrl and thumbnailUrl, added to Social-Data.xml.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1845
draft/REST-API.xml:1845: <c>appData</c>
Changed in Social-Data.xml

http://codereview.appspot.com/152119/diff/1003/2001#newcode1849
draft/REST-API.xml:1849: </texttable>The following additional Plural Fields are
defined, based on
Seems we missed all of these, all added to Social-Data.xml

http://codereview.appspot.com/152119/diff/1003/2001#newcode1944
draft/REST-API.xml:1944: <c>salary</c>
Added to Social-Data.xml

http://codereview.appspot.com/152119/diff/1003/2001#newcode1966
draft/REST-API.xml:1966: <c>address</c>
Added to Social-Data.xml

http://codereview.appspot.com/152119/diff/1003/2001#newcode1971
draft/REST-API.xml:1971: <c>The physical location of this organization. This is
an abbreviated
Update in Social-Data.xml

http://codereview.appspot.com/152119/diff/1003/2001#newcode1977
draft/REST-API.xml:1977: <c>webpage</c>
Added to Social-Data.xml

[Jacky Wang, 2009-12-01 10:40:34]

Thanks for Jon's review!  I've reviewed these changes are merged into Issue
154120: http://codereview.appspot.com/154120

Thanks for Jon's great work!
- Jacky

http://codereview.appspot.com/152119/diff/1003/2001
File draft/REST-API.xml (right):

http://codereview.appspot.com/152119/diff/1003/2001#newcode163
draft/REST-API.xml:163: be 0 or 1 matching results. (i.e. "entry": [ { /* first
item */ }, { /* second item */ } ]).</t>
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> See the diffs for Core-Data.xml

Done.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1655
draft/REST-API.xml:1655: <c>age</c>
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> Added to Social-Data.xml

Done.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1692
draft/REST-API.xml:1692: <c>hasApp</c>
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> Added to Social-Data.xml.

Done.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1749
draft/REST-API.xml:1749: smoker, status, and thumbnailUrl.  The field
currentLocation is deprecated in 1.0
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> profileUrl and thumbnailUrl, added to Social-Data.xml. 

Done.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1845
draft/REST-API.xml:1845: <c>appData</c>
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> Changed in Social-Data.xml

Done.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1849
draft/REST-API.xml:1849: </texttable>The following additional Plural Fields are
defined, based on
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> Seems we missed all of these, all added to Social-Data.xml

Done.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1944
draft/REST-API.xml:1944: <c>salary</c>
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> Added to Social-Data.xml

Done.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1966
draft/REST-API.xml:1966: <c>address</c>
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> Added to Social-Data.xml

Done.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1971
draft/REST-API.xml:1971: <c>The physical location of this organization. This is
an abbreviated
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> Update in Social-Data.xml

Done.

http://codereview.appspot.com/152119/diff/1003/2001#newcode1977
draft/REST-API.xml:1977: <c>webpage</c>
On 2009/11/24 18:13:11, Jon Weygandt wrote:
> Added to Social-Data.xml

Done.

[Jacky Wang, 2009-12-01 10:44:17]

On 2009/11/24 07:40:24, Jacky.Chao.Wang wrote:
> Thanks for Lane's review!
> 
> @Jon, shall we have a quick sync on the XML-schema part? I've made some fields
> changes to keep the spec compliant with Portable Contact (PoCo for short)
spec.
> 
> Thanks,
> Jacky
> 
> http://codereview.appspot.com/152119/diff/1/2
> File draft/REST-API.xml (right):
> 
> http://codereview.appspot.com/152119/diff/1/2#newcode192
> draft/REST-API.xml:192: <preamble>or, for those methods designed to return
only
> one item:</preamble>
> Totally agree - my idea is: for those methods which designed to return
> collection, the return value should be collection, even it contains only 1
item;
> for those methods which designed to return item, only 1 item should be
returned.
> 
> Maybe we need to change the wording here a bit thus make sure the above idea
is
> clearer. :)
> 
> There's a draft about this effort in the patch 2.
> 
> On 2009/11/23 18:00:14, Lane wrote:
> > This changes the intent of the spec.  The example says if you request a
list,
> > but there is only one result, entry will be a single object, not an array. 
> this
> > seems wrong...we should always return a collection if a collection is
> requested.
> > 
> > The text you have says that all methods return a collection, in that the
> > response will container fields like itemsPerPage.  This doesn't make sense
for
> > requests like getOnwer - where only a single object will ever be returned.
> > 
> >
> 
> http://codereview.appspot.com/152119/diff/1/2#newcode271
> draft/REST-API.xml:271: &lt;entry
> xmlns="http://ns.opensocial.org/2008/opensocial"&gt;
> According to the mail I've received on Apr 23:
> 
> The only issue here is that we recently came to consensus that we should be
> using <entry> for all data types (instead of <person>, <activity>, etc.). 
> Although this came after v0.9 was approved, but is basically a bug (since we
> state that we're aligned with PoCo) I'm hoping we can patch the spec and get
> this impl out for v0.9 releases. 
> 
> Thus I change all the tags into <entry>.
> 
> On 2009/11/23 18:00:14, Lane wrote:
> > If I get this XML, how do I know to parse it as a person, activity, or
> something
> > else?
> 
> http://codereview.appspot.com/152119/diff/1/2#newcode1625
> draft/REST-API.xml:1625: <section title="Singular Person Fields">
> Thanks for point it out!  Is his addr Jon.Weygandt@gmail.com?
> 
> On 2009/11/23 18:00:14, Lane wrote:
> > Please work with Jon Weygandt to make sure these changes make it into the
> > Social-Gadget.xml file.

Hi Lane,

Ping. :)

1. Is the current patch interpreting the diff between returning an collection
and returning an object looks clear to you?

2. Do we need to convert people/activity... into "entry"?

Thanks,
Jacky

[Lane, 2009-12-01 17:05:35]

On Tue, Dec 1, 2009 at 2:44 AM, <Jacky.Chao.Wang@gmail.com> wrote:

> On 2009/11/24 07:40:24, Jacky.Chao.Wang wrote:
>
>> Thanks for Lane's review!
>>
>
>  @Jon, shall we have a quick sync on the XML-schema part? I've made
>>
> some fields
>
>> changes to keep the spec compliant with Portable Contact (PoCo for
>>
> short) spec.
>
>  Thanks,
>> Jacky
>>
>
>  http://codereview.appspot.com/152119/diff/1/2
>>
>> File draft/REST-API.xml (right):
>>
>
>  http://codereview.appspot.com/152119/diff/1/2#newcode192
>> draft/REST-API.xml:192: <preamble>or, for those methods designed to
>>
> return only
>
>> one item:</preamble>
>>
>> Totally agree - my idea is: for those methods which designed to return
>> collection, the return value should be collection, even it contains
>>
> only 1 item;
>
>> for those methods which designed to return item, only 1 item should be
>>
> returned.
>
>  Maybe we need to change the wording here a bit thus make sure the
>>
> above idea is
>
>> clearer. :)
>>
>
>  There's a draft about this effort in the patch 2.
>>
>
>  On 2009/11/23 18:00:14, Lane wrote:
>> > This changes the intent of the spec.  The example says if you
>>
> request a list,
>
>> > but there is only one result, entry will be a single object, not an
>>
> array.
>
>> this
>> > seems wrong...we should always return a collection if a collection
>>
> is
>
>> requested.
>> >
>> > The text you have says that all methods return a collection, in that
>>
> the
>
>> > response will container fields like itemsPerPage.  This doesn't make
>>
> sense for
>
>> > requests like getOnwer - where only a single object will ever be
>>
> returned.
>
>> >
>> >
>>
>
>  http://codereview.appspot.com/152119/diff/1/2#newcode271
>> draft/REST-API.xml:271: &lt;entry
>> xmlns="http://ns.opensocial.org/2008/opensocial"&gt;
>> According to the mail I've received on Apr 23:
>>
>
>  The only issue here is that we recently came to consensus that we
>>
> should be
>
>> using <entry> for all data types (instead of <person>, <activity>,
>>
> etc.).
>
>> Although this came after v0.9 was approved, but is basically a bug
>>
> (since we
>
>> state that we're aligned with PoCo) I'm hoping we can patch the spec
>>
> and get
>
>> this impl out for v0.9 releases.
>>
>
>  Thus I change all the tags into <entry>.
>>
>
>  On 2009/11/23 18:00:14, Lane wrote:
>> > If I get this XML, how do I know to parse it as a person, activity,
>>
> or
>
>> something
>> > else?
>>
>
>  http://codereview.appspot.com/152119/diff/1/2#newcode1625
>> draft/REST-API.xml:1625: <section title="Singular Person Fields">
>> Thanks for point it out!  Is his addr Jon.Weygandt@gmail.com?
>>
>
>  On 2009/11/23 18:00:14, Lane wrote:
>> > Please work with Jon Weygandt to make sure these changes make it
>>
> into the
>
>> > Social-Gadget.xml file.
>>
>
> Hi Lane,
>
> Ping. :)
>
> 1. Is the current patch interpreting the diff between returning an
> collection and returning an object looks clear to you?
>

I'm not sure what the 'current patch' is - there are a couple in this
thread.  Please send a link.

>
> 2. Do we need to convert people/activity... into "entry"?
>

For PoCo client/servers to interact w/ OpenSocial these have to be 'entry'.
 Returning a <person> element to a PoCo client is meaningless since PoCo
only defines <entry>.

For OpenSocial's sake, I think we need some indication of the type of object
in the entry so we can disambiguate the <entry> elements that contain person
objects from those that contain activities.  Maybe this disambiguation isn't
necessary - I think we need more input from the REST folks.

In any case, switching from <person> to <entry> is going to totally hose
existing clients.  Any suggestions for a migration plan?  I think this comes
back to versioning the API.

-Lane

>
> Thanks,
>
> Jacky
>
> http://codereview.appspot.com/152119
>

[Jacky Wang, 2009-12-07 08:38:57]

On 2009/12/01 17:05:35, Lane wrote:
> On Tue, Dec 1, 2009 at 2:44 AM, <mailto:Jacky.Chao.Wang@gmail.com> wrote:
> 
> > On 2009/11/24 07:40:24, Jacky.Chao.Wang wrote:
> >
> >> Thanks for Lane's review!
> >>
> >
> >  @Jon, shall we have a quick sync on the XML-schema part? I've made
> >>
> > some fields
> >
> >> changes to keep the spec compliant with Portable Contact (PoCo for
> >>
> > short) spec.
> >
> >  Thanks,
> >> Jacky
> >>
> >
> >  http://codereview.appspot.com/152119/diff/1/2
> >>
> >> File draft/REST-API.xml (right):
> >>
> >
> >  http://codereview.appspot.com/152119/diff/1/2#newcode192
> >> draft/REST-API.xml:192: <preamble>or, for those methods designed to
> >>
> > return only
> >
> >> one item:</preamble>
> >>
> >> Totally agree - my idea is: for those methods which designed to return
> >> collection, the return value should be collection, even it contains
> >>
> > only 1 item;
> >
> >> for those methods which designed to return item, only 1 item should be
> >>
> > returned.
> >
> >  Maybe we need to change the wording here a bit thus make sure the
> >>
> > above idea is
> >
> >> clearer. :)
> >>
> >
> >  There's a draft about this effort in the patch 2.
> >>
> >
> >  On 2009/11/23 18:00:14, Lane wrote:
> >> > This changes the intent of the spec.  The example says if you
> >>
> > request a list,
> >
> >> > but there is only one result, entry will be a single object, not an
> >>
> > array.
> >
> >> this
> >> > seems wrong...we should always return a collection if a collection
> >>
> > is
> >
> >> requested.
> >> >
> >> > The text you have says that all methods return a collection, in that
> >>
> > the
> >
> >> > response will container fields like itemsPerPage.  This doesn't make
> >>
> > sense for
> >
> >> > requests like getOnwer - where only a single object will ever be
> >>
> > returned.
> >
> >> >
> >> >
> >>
> >
> >  http://codereview.appspot.com/152119/diff/1/2#newcode271
> >> draft/REST-API.xml:271: &lt;entry
> >> xmlns="http://ns.opensocial.org/2008/opensocial"&gt;
> >> According to the mail I've received on Apr 23:
> >>
> >
> >  The only issue here is that we recently came to consensus that we
> >>
> > should be
> >
> >> using <entry> for all data types (instead of <person>, <activity>,
> >>
> > etc.).
> >
> >> Although this came after v0.9 was approved, but is basically a bug
> >>
> > (since we
> >
> >> state that we're aligned with PoCo) I'm hoping we can patch the spec
> >>
> > and get
> >
> >> this impl out for v0.9 releases.
> >>
> >
> >  Thus I change all the tags into <entry>.
> >>
> >
> >  On 2009/11/23 18:00:14, Lane wrote:
> >> > If I get this XML, how do I know to parse it as a person, activity,
> >>
> > or
> >
> >> something
> >> > else?
> >>
> >
> >  http://codereview.appspot.com/152119/diff/1/2#newcode1625
> >> draft/REST-API.xml:1625: <section title="Singular Person Fields">
> >> Thanks for point it out!  Is his addr Jon.Weygandt@gmail.com?
> >>
> >
> >  On 2009/11/23 18:00:14, Lane wrote:
> >> > Please work with Jon Weygandt to make sure these changes make it
> >>
> > into the
> >
> >> > Social-Gadget.xml file.
> >>
> >
> > Hi Lane,
> >
> > Ping. :)
> >
> > 1. Is the current patch interpreting the diff between returning an
> > collection and returning an object looks clear to you?
> >
> 
> I'm not sure what the 'current patch' is - there are a couple in this
> thread.  Please send a link.
> 
> >
> > 2. Do we need to convert people/activity... into "entry"?
> >
> 
> For PoCo client/servers to interact w/ OpenSocial these have to be 'entry'.
>  Returning a <person> element to a PoCo client is meaningless since PoCo
> only defines <entry>.
> 
> For OpenSocial's sake, I think we need some indication of the type of object
> in the entry so we can disambiguate the <entry> elements that contain person
> objects from those that contain activities.  Maybe this disambiguation isn't
> necessary - I think we need more input from the REST folks.
> 
> In any case, switching from <person> to <entry> is going to totally hose
> existing clients.  Any suggestions for a migration plan?  I think this comes
> back to versioning the API.
> 
> -Lane
> 
> >
> > Thanks,
> >
> > Jacky
> >
> > http://codereview.appspot.com/152119
> >
> 

Hi Lane,

Sorry for the late reply.

I'm contacting Jon and Arne, to merge my thoughts/changes with their patches,
given these 2 files actually will be replaced by those Core-*.xml and
Social-*.xml.

Thanks for your review!
- Jacky