---------- Forwarded message ---------- From: Dan Peterson <dpeter...@google.com> Date: Fri, May 9, 2008 at 6:27 PM Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related
spec updates To: opensocial-and-gadgets-spec < opensocial-and-gadgets-spec@googlegroups.com>
Hi folks,
As discussed last week, the full draft of OpenSocial v0.8 specification is ready for your review. This draft specification includes updates to existing specs, inclusion of the RESTful spec, release notes, and detailed JavaScript doc (JSDoc). The intent was to clearly capture all of the 40+ changes/additions that we have developed on this mailing list since version 0.7 of the spec (as tracked in http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). Let's use the next week or two to make improvements to these docs and then we can lock down 0.8.
I have conveniently numbered these documents so it is easier for you to walk through them in a clear order. In addition, documents 1 through 4 have their additions/updates highlighted for ease of reference. To better organize detailed feedback for each document, I will now start a thread for each of the 6 documents. Please be sure to direct your feedback to the appropriate thread.
Also, as a reminder, this coming Wednesday, May 15, we'll be holding an OpenSocial Summit in Mountain View, California. This event is an ideal opportunity to discuss this draft specification, propose ideas for future iterations, and learn about the latest happenings in the community -- as well as get to know each other in person.
Might I propose that all opensocial-related specifications use this format? Even though there are some known issues with implementing the RESTful spec, there is very little ambiguity here and it's very easy to reference subsections of it. Right now, the gadget spec is wildly different (although slightly closer in format), and the primary opensocial spec is a different type of document altogether.
I consider myself pretty familiar with all aspects of the spec, but when I read it today I can't help but be confused, as my comments on the other threads indicated. The format used by the RESTful spec is a perfect example of how to do this right.
On Fri, May 9, 2008 at 6:33 PM, Dan Peterson <dpeter...@google.com> wrote: > As per below, please use this thread to discuss potential improvements to > the OpenSocial API RESTful spec (v0.8):
> ---------- Forwarded message ---------- > From: Dan Peterson <dpeter...@google.com> > Date: Fri, May 9, 2008 at 6:27 PM > Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related > spec updates > To: opensocial-and-gadgets-spec < > opensocial-and-gadgets-spec@googlegroups.com>
> Hi folks,
> As discussed last week, the full draft of OpenSocial v0.8 specification is > ready for your review. This draft specification includes updates to existing > specs, inclusion of the RESTful spec, release notes, and detailed JavaScript > doc (JSDoc). The intent was to clearly capture all of the 40+ > changes/additions that we have developed on this mailing list since version > 0.7 of the spec (as tracked in > http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). > Let's use the next week or two to make improvements to these docs and then > we can lock down 0.8.
> I have conveniently numbered these documents so it is easier for you to > walk through them in a clear order. In addition, documents 1 through 4 have > their additions/updates highlighted for ease of reference. To better > organize detailed feedback for each document, I will now start a thread for > each of the 6 documents. Please be sure to direct your feedback to the > appropriate thread.
> Also, as a reminder, this coming Wednesday, May 15, we'll be holding an > OpenSocial Summit in Mountain View, California. This event is an ideal > opportunity to discuss this draft specification, propose ideas for future > iterations, and learn about the latest happenings in the community -- as > well as get to know each other in person.
One general observation (that applies to all of Kevin's suggestions on all the threads) -- there are two sorts of comments being made here:- ways we could tighten up all the spec documents, regardless of any content changes from 0.7 to 0.8 - ways we could better improve the substance and/or wording of the 0.8 changes
I think both are good sets of feedback; it might help the conversation to clearly highlight which are which. Personally, I consider the second set to be the most urgent to agree on, since that's more blocking to people (shindig, containers) who already have 0.7 implementations and want to upgrade them. But in the long run, the first set will end up being more important, since there will be many more new eyes than old over time.
On Sat, May 10, 2008 at 3:07 AM, Kevin Brown <e...@google.com> wrote: > Might I propose that all opensocial-related specifications use this format? > Even though there are some known issues with implementing the RESTful spec, > there is very little ambiguity here and it's very easy to reference > subsections of it. Right now, the gadget spec is wildly different (although > slightly closer in format), and the primary opensocial spec is a different > type of document altogether.
> I consider myself pretty familiar with all aspects of the spec, but when I > read it today I can't help but be confused, as my comments on the other > threads indicated. The format used by the RESTful spec is a perfect example > of how to do this right.
> On Fri, May 9, 2008 at 6:33 PM, Dan Peterson <dpeter...@google.com> wrote:
>> As per below, please use this thread to discuss potential improvements to >> the OpenSocial API RESTful spec (v0.8):
>> ---------- Forwarded message ---------- >> From: Dan Peterson <dpeter...@google.com> >> Date: Fri, May 9, 2008 at 6:27 PM >> Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related >> spec updates >> To: opensocial-and-gadgets-spec < >> opensocial-and-gadgets-spec@googlegroups.com>
>> Hi folks,
>> As discussed last week, the full draft of OpenSocial v0.8 specification is >> ready for your review. This draft specification includes updates to existing >> specs, inclusion of the RESTful spec, release notes, and detailed JavaScript >> doc (JSDoc). The intent was to clearly capture all of the 40+ >> changes/additions that we have developed on this mailing list since version >> 0.7 of the spec (as tracked in >> http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). >> Let's use the next week or two to make improvements to these docs and then >> we can lock down 0.8.
>> I have conveniently numbered these documents so it is easier for you to >> walk through them in a clear order. In addition, documents 1 through 4 have >> their additions/updates highlighted for ease of reference. To better >> organize detailed feedback for each document, I will now start a thread for >> each of the 6 documents. Please be sure to direct your feedback to the >> appropriate thread.
>> Also, as a reminder, this coming Wednesday, May 15, we'll be holding an >> OpenSocial Summit in Mountain View, California. This event is an ideal >> opportunity to discuss this draft specification, propose ideas for future >> iterations, and learn about the latest happenings in the community -- as >> well as get to know each other in person.
Could we replace the links to the RFC documents with the canonical IETF versions? Linking to versions on the OAuth site doesn't seem to make a lot of sense.
On Fri, May 9, 2008 at 6:33 PM, Dan Peterson <dpeter...@google.com> wrote: > As per below, please use this thread to discuss potential improvements to > the OpenSocial API RESTful spec (v0.8):
> ---------- Forwarded message ---------- > From: Dan Peterson <dpeter...@google.com> > Date: Fri, May 9, 2008 at 6:27 PM > Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related > spec updates > To: opensocial-and-gadgets-spec < > opensocial-and-gadgets-spec@googlegroups.com>
> Hi folks,
> As discussed last week, the full draft of OpenSocial v0.8 specification is > ready for your review. This draft specification includes updates to existing > specs, inclusion of the RESTful spec, release notes, and detailed JavaScript > doc (JSDoc). The intent was to clearly capture all of the 40+ > changes/additions that we have developed on this mailing list since version > 0.7 of the spec (as tracked in > http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). > Let's use the next week or two to make improvements to these docs and then > we can lock down 0.8.
> I have conveniently numbered these documents so it is easier for you to > walk through them in a clear order. In addition, documents 1 through 4 have > their additions/updates highlighted for ease of reference. To better > organize detailed feedback for each document, I will now start a thread for > each of the 6 documents. Please be sure to direct your feedback to the > appropriate thread.
> Also, as a reminder, this coming Wednesday, May 15, we'll be holding an > OpenSocial Summit in Mountain View, California. This event is an ideal > opportunity to discuss this draft specification, propose ideas for future > iterations, and learn about the latest happenings in the community -- as > well as get to know each other in person.
A Person contains a scoial network oriented data about a single person.
/q
How about: A Person represents a user of the social network.
q
- The field names are the same as in the JS doc, but lowercased.
/q
Does this mean keeping the underscores? Are we not using camel casing in order to be consistent w/ common practices of XML and JSON (including OpenSearch)? Perhaps we should actually enumerate the fields in the doc with their exact spelling capitalization?
~Paul
From: opensocial-and-gadgets-spec@googlegroups.com [mailto:opensocial-and-gadgets-spec@googlegroups.com] On Behalf Of David Glazer Sent: Saturday, May 10, 2008 11:28 AM To: opensocial-and-gadgets-spec@googlegroups.com Subject: Re: Detailed feedback thread: 3-OpenSocial_0_8_REST_API_Spec.html
One general observation (that applies to all of Kevin's suggestions on all the threads) -- there are two sorts of comments being made here:
- ways we could tighten up all the spec documents, regardless of any content changes from 0.7 to 0.8
- ways we could better improve the substance and/or wording of the 0.8 changes
I think both are good sets of feedback; it might help the conversation to clearly highlight which are which. Personally, I consider the second set to be the most urgent to agree on, since that's more blocking to people (shindig, containers) who already have 0.7 implementations and want to upgrade them. But in the long run, the first set will end up being more important, since there will be many more new eyes than old over time.
- dG
On Sat, May 10, 2008 at 3:07 AM, Kevin Brown <e...@google.com> wrote:
Might I propose that all opensocial-related specifications use this format? Even though there are some known issues with implementing the RESTful spec, there is very little ambiguity here and it's very easy to reference subsections of it. Right now, the gadget spec is wildly different (although slightly closer in format), and the primary opensocial spec is a different type of document altogether.
I consider myself pretty familiar with all aspects of the spec, but when I read it today I can't help but be confused, as my comments on the other threads indicated. The format used by the RESTful spec is a perfect example of how to do this right.
On Fri, May 9, 2008 at 6:33 PM, Dan Peterson <dpeter...@google.com> wrote:
---------- Forwarded message ---------- From: Dan Peterson <dpeter...@google.com> Date: Fri, May 9, 2008 at 6:27 PM Subject: Ready for review: Complete drafts of OpenSocial v0.8 and
related spec updates To: opensocial-and-gadgets-spec <opensocial-and-gadgets-spec@googlegroups.com>
Hi folks,
As discussed last week, the full draft of OpenSocial v0.8 specification is ready for your review. This draft specification includes updates to existing specs, inclusion of the RESTful spec, release notes, and detailed JavaScript doc (JSDoc). The intent was to clearly capture all of the 40+ changes/additions that we have developed on this mailing list since version 0.7 of the spec (as tracked in http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). Let's use the next week or two to make improvements to these docs and then we can lock down 0.8.
I have conveniently numbered these documents so it is easier for you to walk through them in a clear order. In addition, documents 1 through 4 have their additions/updates highlighted for ease of reference. To better organize detailed feedback for each document, I will now start a thread for each of the 6 documents. Please be sure to direct your feedback to the appropriate thread.
Also, as a reminder, this coming Wednesday, May 15, we'll be holding an OpenSocial Summit in Mountain View, California. This event is an ideal opportunity to discuss this draft specification, propose ideas for future iterations, and learn about the latest happenings in the community -- as well as get to know each other in person.
atom:entry/atom:id aliases the "id" field. In the Atom format, it is translated into the required URI data type by prepending "urn:guid:" to the OpenSocial ID string.
/q
That's not the only way to translate the id field into a valid URI. The text reads as if OS Providers must use urn:guid. Is that the case?
q
atom:entry/atom:published aliases the JSON field indicating creation time (POSTED_TIME for Activity).
/q
The example atom instance does not contain this atom field. Perhaps the text could be a little more clear on what atom fields are required/optional?
The example instance mixes two default namespaces. Shouldn't one of them include a prefix?
On Wed, May 14, 2008 at 1:55 AM, Paul Walker <pwal...@myspace.com> wrote: > *2.2 Person*
> q
> A Person contains a scoial network oriented data about a single person.
> /q
> How about: A Person represents a user of the social network.
> q
> - The field names are the same as in the JS doc, but lowercased.
> /q
> Does this mean keeping the underscores? Are we not using camel casing in > order to be consistent w/ common practices of XML and JSON (including > OpenSearch)? Perhaps we should actually enumerate the fields in the doc > with their exact spelling capitalization?
Common conventions for most XML and JSON is to use camel casing. It's not clear to me why the lower casing is necessary at all. Why not simply use the same field names as the JS?
> *From:* opensocial-and-gadgets-spec@googlegroups.com [mailto: > opensocial-and-gadgets-spec@googlegroups.com] *On Behalf Of *David Glazer > *Sent:* Saturday, May 10, 2008 11:28 AM > *To:* opensocial-and-gadgets-spec@googlegroups.com > *Subject:* Re: Detailed feedback thread: > 3-OpenSocial_0_8_REST_API_Spec.html
> One general observation (that applies to all of Kevin's suggestions on all > the threads) -- there are two sorts of comments being made here:
> - ways we could tighten up all the spec documents, regardless of any > content changes from 0.7 to 0.8
> - ways we could better improve the substance and/or wording of the 0.8 > changes
> I think both are good sets of feedback; it might help the conversation to > clearly highlight which are which. Personally, I consider the second set to > be the most urgent to agree on, since that's more blocking to people > (shindig, containers) who already have 0.7 implementations and want to > upgrade them. But in the long run, the first set will end up being more > important, since there will be many more new eyes than old over time.
> - dG
> On Sat, May 10, 2008 at 3:07 AM, Kevin Brown <e...@google.com> wrote:
> Might I propose that all opensocial-related specifications use this format? > Even though there are some known issues with implementing the RESTful spec, > there is very little ambiguity here and it's very easy to reference > subsections of it. Right now, the gadget spec is wildly different (although > slightly closer in format), and the primary opensocial spec is a different > type of document altogether.
> I consider myself pretty familiar with all aspects of the spec, but when I > read it today I can't help but be confused, as my comments on the other > threads indicated. The format used by the RESTful spec is a perfect example > of how to do this right.
> On Fri, May 9, 2008 at 6:33 PM, Dan Peterson <dpeter...@google.com> wrote:
> As per below, please use this thread to discuss potential improvements to > the OpenSocial API RESTful spec (v0.8):
> ---------- Forwarded message ---------- > From: *Dan Peterson* <dpeter...@google.com> > Date: Fri, May 9, 2008 at 6:27 PM > Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related > spec updates > To: opensocial-and-gadgets-spec < > opensocial-and-gadgets-spec@googlegroups.com>
> Hi folks,
> As discussed last week, the full draft of OpenSocial v0.8 specification is > ready for your review. This draft specification includes updates to existing > specs, inclusion of the RESTful spec, release notes, and detailed JavaScript > doc (JSDoc). The intent was to clearly capture all of the 40+ > changes/additions that we have developed on this mailing list since version > 0.7 of the spec (as tracked in > http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). > Let's use the next week or two to make improvements to these docs and then > we can lock down 0.8.
