Poco alignment: some minor mistakes need to be changed on the 0.9 RESTful spec?

[Jacky]

Hi All,

I'm doing the poco alignment for PHP Shindig recently. When reading
through the spec, I found some small mistakes on the 0.9 RESTful spec
as following:

- in 3.2 Person / 3.3 Group / 3.4 Activity / 3.5 AppData
All items should use "entry" in XML format, instead of "person",
"group", "activity" or "appdata".

- need to change all "Singluar" into "Singular".

- Sometimes the description and XML schema are not consistent.
I've composed a complete side-by-side comparison matrix of Portable
Contacts, OpenSocial 0.9 Spec (description), OpenSocial 0.9 XML
schema, Java Shindig and PHP Shindig on http://bit.ly/PocoAlignment.
And it seems like the following attributes need to be adjusted:

Person: age, appdata, hasApp
Name: additionalName
Address: extendedAddress, poBox, primary
Organization: address, field, location, primary, salary, subField,
webpage
Account: primary

Thanks,
- Jacky

[Chris Chabot]

Awesome job going through that Jacky!

The list looks quite comprehensive, and more importantly, correct too me. Since this affects both the spec and the php and java reference implementations I would like to invite everyone to take a quick gander at the spreadsheet, and once we all agree about what is or isn't correct, we can go and make the adjustments that are required.

Wha'da'ya'all think?

    -- Chris

[Arne Roomann-Kurrik]

Awesome work!  I'd love to get these truly aligned for the next version.  Most of these changes seem fairly simple too.

What's the difference between "languages" and "languagesSpoken"?  Seems redundant.

~Arne

[Chris Chabot]

Ok that's all fine and well, but my larger concern right now is: but what do we practically implement in php-shindig for 0.9? For 0.9 we've already stated that we wanted to be (re)aligned with PoCo, and it seems there's some inconsistencies left.

So what *should* we implement right now? Go for complete alignment (since we stated that as goal for this revision) in php-shindig, and deal with the confusion and/or incompatibilities with java-shindig (and/or other implementations), do we align with the java & javascript implementations, or ... ?

   -- Chris

[Scott Seely]

Chris-- I think that the PHP Shindig issue is a question for another list. I believe that the real question is "what should we look for in a conforming 0.9 implementation?"

 

The XML alignment is a bit trickier. PoCo has pushed back on an XSD (and continues to not have one) whereas OpenSocial constituents have been adamant that we have an XSD. The XSD argument seems to be centered around code generation concerns. Also note that since a PoCo response lives in the global XMLNS, the current direction of PoCo and OpenSocial generate different infosets. Because of this, the code generation advocates still would have issues.

 

The primary issue we need to address is this: a PoCo request will only EVER return person data and an OpenSocial request may return person, appdata, activities, groups, etc. We both wrap our responses in a response object that indicates which page of data was returned. The key problem that we have been trying to tackle is how to cleanly wrap these items to make the entry items self describing.

 

We can do the following to get self describing 'entry' elements in XML:

1. Use xsi:type attributes on each entry. xsi:type is used to denote the type of an element when the data is ambiguous. This is easy to parse, but many code generators don't know how to handle parsing this type of attribute. To me, this isn't a concern. If a person MUST use XML, they can probably parse it. All other issues should be able to be handled by simple client libraries and a few days of effort. The client library is equivalent to the code-gen'd issue in that someone else handles parsing markup into program data.

 

2. Use separate XMLNS for each entry. This option seems appealing until one sees that the resulting XSD uses options that aren't commonly available on most code generators. Altova produces commercial generators that do handle the cases, but then we are in a place where users must purchase a commerical tool to use the XSD.

 

3. Indicate the types in the result via the HTTP Content header. This idea is very appealing because it handles making the JSON and XML responses self describing.

 

I'm sure that there are other options-- these are the 3 I've investigated to solve this problem.

---

From: opensocial-an...@googlegroups.com on behalf of Chris Chabot
Sent: Sun 6/14/2009 7:09 AM
To: opensocial-an...@googlegroups.com; shind...@incubator.apache.org
Subject: [opensocial-and-gadgets-spec] Re: Poco alignment: some minor mistakes need to be changed on the 0.9 RESTful spec?

[Bess Ho]

My response will be: I rather see complete alignment. The cost of dealing with confusion will cost more engineering time to explain and provide troubleshooting support.

--
Bess Ho

[Jacky]

It will be great if we got 2 pretty align protocols --- therefore the
client of either side could talk to each other happily.

It might be okay to have some app-related fields that OpenSocial has
but Poco don't --- since OpenSocial has more sense about
"application".

For other fields like "latitude" and "longitude" in address, it's
happy to see if we could keep them the same on both Poco and
OpenSocial. IMHO, the reason is quite simple: if we could prove that
a field is useful to describe a person/object on Poco or OpenSocial,
the same argument should be valid on the other side too.

Just my 2 cents. =)

- Jacky

On Jun 15, 5:20 am, Bess Ho <bess...@gmail.com> wrote:
> My response will be: I rather see complete alignment. The cost of dealing
> with confusion will cost more engineering time to explain and provide
> troubleshooting support.
>
>
>
> On Sun, Jun 14, 2009 at 7:09 AM, Chris Chabot <chab...@google.com> wrote:
> > Ok that's all fine and well, but my larger concern right now is: but what
> > do we practically implement in php-shindig for 0.9? For 0.9 we've already
> > stated that we wanted to be (re)aligned with PoCo, and it seems there's some
> > inconsistencies left.
>
> > So what *should* we implement right now? Go for complete alignment (since
> > we stated that as goal for this revision) in php-shindig, and deal with the
> > confusion and/or incompatibilities with java-shindig (and/or other
> > implementations), do we align with the java & javascript implementations, or
> > ... ?
>
> > -- Chris
>
> > On Fri, Jun 12, 2009 at 8:55 PM, Arne Roomann-Kurrik <kur...@google.com>wrote:
>
> >> Awesome work! I'd love to get these truly aligned for the next version.
> >> Most of these changes seem fairly simple too.
>
> >> What's the difference between "languages" and "languagesSpoken"? Seems
> >> redundant.
>
> >> ~Arne
>

> >> On Fri, Jun 12, 2009 at 6:58 AM, Chris Chabot <chab...@google.com> wrote:
>
> >>> Awesome job going through that Jacky!
>
> >>> The list looks quite comprehensive, and more importantly, correct too me.
> >>> Since this affects both the spec and the php and java reference
> >>> implementations I would like to invite everyone to take a quick gander at
> >>> the spreadsheet, and once we all agree about what is or isn't correct, we
> >>> can go and make the adjustments that are required.
>
> >>> Wha'da'ya'all think?
>
> >>> -- Chris
>

> >>> On Fri, Jun 12, 2009 at 3:25 PM, Jacky <Jacky.Chao.W...@gmail.com>wrote:
>
> >>>> Hi All,
>
> >>>> I'm doing the poco alignment for PHP Shindig recently. When reading
> >>>> through the spec, I found some small mistakes on the 0.9 RESTful spec
> >>>> as following:
>
> >>>> - in 3.2 Person / 3.3 Group / 3.4 Activity / 3.5 AppData
> >>>> All items should use "entry" in XML format, instead of "person",
> >>>> "group", "activity" or "appdata".
>
> >>>> - need to change all "Singluar" into "Singular".
>
> >>>> - Sometimes the description and XML schema are not consistent.
> >>>> I've composed a complete side-by-side comparison matrix of Portable
> >>>> Contacts, OpenSocial 0.9 Spec (description), OpenSocial 0.9 XML

> >>>> schema, Java Shindig and PHP Shindig onhttp://bit.ly/PocoAlignment.

[Lane LiaBraaten]

+portablecontacts list

The question is no longer "if" we should align these protocols...we need to focus on how.

For the XSD stuff...if we're trying to do this for the benefit of code generators and 1) and 2) don't meet that goal, let's take a closer look at 3).  Does specifying people, activities, etc. to the content type make it possible to auto-generate code?

As for the spreadsheet Jackie put together...awesome work!  Looks like most of the changes are straightforward, but a few warrant further discussion...

age - I think we added this to support knowing if a user is over/under a particular age without having to share their birthday.  Unless someone reminds me why this is useful, I agree we should remove it in favor of birthday.

languages - let's remove this in favor of 'languagesSpoken' which is already supported everywhere

Address.extendedAddress, poBox - speak up if you don't want these removed

Organization.address vs. Organization.location - I think we should use address since that is the type of object this field will contain.

-Lane

[Lane LiaBraaten]

(reposting to add portablecontacts list)

[Jacky]

Copy Joseph's reply on shindig's mail-list here:

---
Ok I've added a "Joseph Smarr's feedback" column and put notes in for
all the current descrepencies. Looks like it should be pretty painless
to get things fully aligned!

Two things to keep in mind throughout this process:

1) The goal of the alignment, as per the spec, is that "any compliant
OpenSocial RESTful Protocol 0.8.1 [or greater] Provider is also a
compliant Portable Contacts Provider". In other words, OS must be a
strict superset of PoCo, but PoCo need not include every field in OS
(since OS is tackling a wider scope, and the goal is that the subset
of OS that relates to PoCo should be the same so developers can talk
to an OS API just like a PoCo-only API).

2) This alignment was fully agreed-to back when drafting 0.8.1, so any
outstanding descrepencies are bugs that should have been fixed a while
ago, but we just missed (until we were fortunate to get such a
detailed inspection from Jackie!). So as was mentioned before, let's
try to keep the discussion focused on the execution of fixing these
bugs--we're so close already! :)

Thanks! js
---

It's really great to receive all the invaluable feedbacks! We now
stand very close to the target! =)

According to the matrix, it seems only the following 5 items remain
opening (please correct me if I missed anything):

- Person.age: seems we've reached the agreement that it will stay in
os spec and it would be easy to add later to PoCo if there's clear
demand.

- Person.profileUrl: shall we remove it everywhere? It might be fine
to make this decision consistent with the one for thumbnailUrl ---
suggest remove.

- Name.additionName / middleName: voting opening. we don't want both
fields. :P I suggest "middleName".

- Organization.address / location: shall we keep both? or use only
"location"?

- Organization.field / salary / subField / webpage: it's okay to keep
them in os but leave poco unchanged. are they useful in os?

Your feedback are warmly welcome! =)

Thanks,
- Jacky

On Jun 16, 12:49 am, Lane LiaBraaten <api.lliab...@gmail.com> wrote:
> (reposting to add portablecontacts list)
>

> On Mon, Jun 15, 2009 at 9:14 AM, Lane LiaBraaten <lliab...@google.com>wrote:
>
> > +portablecontacts list
>
> > The question is no longer "if" we should align these protocols...we need to
> > focus on how.
>
> > For the XSD stuff...if we're trying to do this for the benefit of code
> > generators and 1) and 2) don't meet that goal, let's take a closer look at
> > 3). Does specifying people, activities, etc. to the content type make it
> > possible to auto-generate code?
>
> > As for the spreadsheet Jackie put together...awesome work! Looks like most
> > of the changes are straightforward, but a few warrant further discussion...
>
> > age - I think we added this to support knowing if a user is over/under a
> > particular age without having to share their birthday. Unless someone
> > reminds me why this is useful, I agree we should remove it in favor of
> > birthday.
>
> > languages - let's remove this in favor of 'languagesSpoken' which is
> > already supported everywhere
>
> > Address.extendedAddress, poBox - speak up if you don't want these removed
>
> > Organization.address vs. Organization.location - I think we should use
> > address since that is the type of object this field will contain.
>
> > -Lane
>

[Chris Chabot]

On Wed, Jun 17, 2009 at 8:34 AM, Jacky <Jacky.C...@gmail.com> wrote:

- Person.profileUrl: shall we remove it everywhere? It might be fine
to make this decision consistent with the one for thumbnailUrl ---
suggest remove.

profileUrl and thumbnailUrl should definitely stay in the OpenSocial spec, combined with the name they are the bases of social apps (can't show a list of your friends with pictures and clickable links without those)

[Jacky]

It seems like the field Person.url covers this:
Person.url@type=profile, Person.url@type=thumbnail, etc...

On Jun 17, 2:44 pm, Chris Chabot <chab...@google.com> wrote:

[Joseph Smarr]

For profileUrl and thumbnailUrl, yes they're technically redundant,
but they're very convenient (and commonly used) by OpenSocial gadget
developers, so when we did the initial alignment, we agreed to leave
them in OS as "convenience fields" but under the stipulation that the
data ALSO has to show up in the official location (e.g. profileUrl
should also be in the list of urls with type=profile). I think that's
a smart compromise, so we should leave it as is.

As for the remaining issues (middleName vs additionalName and the
extra organization fields in OS), my vote (not surprisingly) is to
standardize on what PoCo uses (since we already went thru a lengthy
debate process to agree on those field names), but in the case where
OS wants to keep some additional fields (like field/subField for org)
that's also fine by me since it still keeps PoCo a strict subset of
OS.

Can anyone else weigh in on these remaining issues? In particular, how
painful would it be to change additionalName to middleName in OS?

Thanks, js

> > of your friends with pictures and clickable links without those)- Hide quoted text -
>
> - Show quoted text -

[Kevin Marks]

On Wed, Jun 17, 2009 at 8:35 AM, Joseph Smarr <jsm...@gmail.com> wrote:

For profileUrl and thumbnailUrl, yes they're technically redundant,
but they're very convenient (and commonly used) by OpenSocial gadget
developers, so when we did the initial alignment, we agreed to leave
them in OS as "convenience fields" but under the stipulation that the
data ALSO has to show up in the official location (e.g. profileUrl
should also be in the list of urls with type=profile). I think that's
a smart compromise, so we should leave it as is.

As for the remaining issues (middleName vs additionalName and the
extra organization fields in OS), my vote (not surprisingly) is to
standardize on what PoCo uses (since we already went thru a lengthy
debate process to agree on those field names), but in the case where
OS wants to keep some additional fields (like field/subField for org)
that's also fine by me since it still keeps PoCo a strict subset of
OS.

Can anyone else weigh in on these remaining issues? In particular, how
painful would it be to change additionalName to middleName in OS?

If we are going to do this, can we add mappings from vcard to the spec(s) so that people can tell which field goes where (I know you've done this in practice, Joe)

[Scott Seely]

I’m missing a statement on how we are proposing to handle entries of type Activity, AppData, etc.

 

We need to understand how we handle Activity living at the same place as Person—did I miss that in the discussion so far?

[Joseph Smarr]

Scott-are you talking about the XSD issue of how to represent <entry> values for people vs activities, etc.? If so, I thought the resolution was to get rid of the <person> element and just use <entry> and then also add the xsi:type thing if that helps validation, which was deferred to you and other XML experts to say if it's worth it. I agree that issue should go in the spreadsheet! :)

Thanks, js

[Scott Seely]

That was a solution. Again—I just didn’t see this logged anywhere. I will happily go with the xsi:type solution.

 

I’m also concerned that the OpenSocial use of XMLNS on the serialization will impair the ability to handle XML from PoCo. The reason for an XMLNS is to handle versioning on XML docs. This means we should probably have a schema but put all the names into the global namespace. This is not great for XML, but enhances compatibility. I’m not willing to fight for XMLNS because we also support JSON which doesn’t have a versioning story like XMLNS. Any versioning solution we come up with for JSON should also work for XML.

[Joseph Smarr]

Right, I think the spirit of whatever we do should be a) make it work like JSON when possible, b) make it compatible for XML consumers, and c) make it minimally painful for XML consumers that just want/expect POX.

Thanks, js

[Jacky]

Hi Everyone,

Thanks for all the great inputs!!! =)

According to the feedback, the final decision has been put into the
"final" column of http://bit.ly/PocoAlignment.

Especially, the decisions on the issues stated before are:

- Person.age: add to spec description
- Person.profileUrl: add to spec description
- Person.thumbnailUrl: add to both spec description and XML
- Name.additionName / middleName: change to "middle name" to both spec
description, PHP and Java Shindig
- Organization.address / location: change to "location" to both XML,
PHP and Java Shindig
- Organization.field / salary / subField / webpage: keep in
OpenSocial, add to spec description

Please raise your hands if there's any concern remains --- we're about
to work on the detailed alignment job such like spec change/code
change soon. :)

Thanks,
Jacky

On Jun 24, 3:05 am, Joseph Smarr <jsm...@gmail.com> wrote:
> Right, I think the spirit of whatever we do should be a) make it work like
> JSON when possible, b) make it compatible for XML consumers, and c) make it
> minimally painful for XML consumers that just want/expect POX.
>
> Thanks, js
>
> On Tue, Jun 23, 2009 at 10:25 AM, Scott Seely <sSe...@myspace-inc.com>wrote:
>
> >  That was a solution. Again—I just didn’t see this logged anywhere. I will
> > happily go with the xsi:type solution.
>
> > I’m also concerned that the OpenSocial use of XMLNS on the serialization
> > will impair the ability to handle XML from PoCo. The reason for an XMLNS is
> > to handle versioning on XML docs. This means we should probably have a
> > schema but put all the names into the global namespace. This is not great
> > for XML, but enhances compatibility. I’m not willing to fight for XMLNS
> > because we also support JSON which doesn’t have a versioning story like
> > XMLNS. Any versioning solution we come up with for JSON should also work for
> > XML.
>

> > *From:* portable...@googlegroups.com [mailto:
> > portable...@googlegroups.com] *On Behalf Of *Joseph Smarr
> > *Sent:* Monday, June 22, 2009 6:07 PM
> > *To:* portable...@googlegroups.com
> > *Cc:* opensocial-an...@googlegroups.com;
> > portableconta...@groups.google.com
>
> > *Subject:* Re: [opensocial-and-gadgets-spec] Re: Poco alignment: some

> > minor mistakes need to be changed on the 0.9 RESTful spec?
>
> > Scott-are you talking about the XSD issue of how to represent <entry>
> > values for people vs activities, etc.? If so, I thought the resolution was
> > to get rid of the <person> element and just use <entry> and then also add
> > the xsi:type thing if that helps validation, which was deferred to you and
> > other XML experts to say if it's worth it. I agree that issue should go in
> > the spreadsheet! :)
>
> > Thanks, js
>
> > On Mon, Jun 22, 2009 at 2:11 PM, Scott Seely <sSe...@myspace-inc.com>
> > wrote:
>
> > I’m missing a statement on how we are proposing to handle entries of type
> > Activity, AppData, etc.
>
> > We need to understand how we handle Activity living at the same place as
> > Person—did I miss that in the discussion so far?
>

> > *From:* portable...@googlegroups.com [mailto:
> > portable...@googlegroups.com] *On Behalf Of *Kevin Marks
> > *Sent:* Wednesday, June 17, 2009 8:38 AM
> > *To:* opensocial-an...@googlegroups.com
> > *Cc:* portableconta...@groups.google.com
> > *Subject:* Re: [opensocial-and-gadgets-spec] Re: Poco alignment: some

[Joseph Smarr]

Looks great! :) One question on location for organization--are you changing that to just a simple string value (like in PoCo) or keeping it as a complex Address type (as it was when called address)? I'd of course vote for the former since it's aligned with PoCo, but just wanted to confirm.

 

Thanks, js

[Lane LiaBraaten]

+1 or a structured address field as it's consistent w/ other addresses in the spec.

-Lane

[Jacky]

Joe and Lane, thanks for the reply!

I changed the column a bit according to the inputs:
- Organization.address: keep in OpenSocial spec, contain Address
values.
- Organization.location: keep in both PoCo and OpenSocial, contain
simple string values.

...

+1 for this idea. =)

Thanks,
- Jacky

On Jun 24, 10:43 pm, Lane LiaBraaten <api.lliab...@gmail.com> wrote:
> +1 or a structured address field as it's consistent w/ other addresses in
> the spec.
>
> -Lane
>
> On Wed, Jun 24, 2009 at 7:33 AM, Joseph Smarr <jsm...@gmail.com> wrote:
> > Looks great! :) One question on location for organization--are you changing
> > that to just a simple string value (like in PoCo) or keeping it as a complex
> > Address type (as it was when called address)? I'd of course vote for the
> > former since it's aligned with PoCo, but just wanted to confirm.
>
> > Thanks, js
>

> > On Wed, Jun 24, 2009 at 2:24 AM, Jacky <Jacky.Chao.W...@gmail.com> wrote:
>
> >> Hi Everyone,
>
> >> Thanks for all the great inputs!!! =)
>
> >> According to the feedback, the final decision has been put into the

> >> "final" column ofhttp://bit.ly/PocoAlignment.