Detailed feedback thread: 4-a-gadgets_Spec.html, 4-b-Canonical_gadgets_Spec_XSD.html, 4-c-Extended_gadgets_Spec_XSD.html, 4-d-gadgets_Message_Bundle_Spec_XSD.html

[Dan Peterson]

As per below, please use this thread to discuss potential improvements to the gadgets spec and the related XSD files:
http://opensocial-and-gadgets-spec.googlegroups.com/web/4-a-gadgets_Spec.html

Thanks,
-Dan

---------- Forwarded message ----------
From: Dan Peterson <dpet...@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-an...@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.

You can find all 6 of these documents uploaded into the "Files" section of this Google Group: http://groups.google.com/group/opensocial-and-gadgets-spec/files?&sort=name

The draft documents published are (please note that some of the links in the files might not work as this is only a staged copy):

• 1 - OpenSocial 0.8 Release Notes
• 2 - OpenSocial 0.8 Specification
• 3 - OpenSocial 0.8 RESTful API Specification
• 4 - gadgets Specification
• Canonical gadgets XSD
• Extended gadgets XSD
• gadgets Message Bundle XSD
  
• 5 - opensocial.* 0.8 JS doc
• 6 - gadgets.* JS doc

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.

You can learn more about the event at: http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th-at.html
The agenda is here: https://docs.google.com/View?docID=dds2mvj3_1vxvsnzfd
(RSVP is here: http://spreadsheets.google.com/viewform?key=pKy6PfiaRD2NIEhpx692Oaw )

Looking forward to your feedback (in the appropriate thread ;),
-Dan

[Kevin Brown]

Not sure the format here, so I'll do my best to add some clarifications for things I think need to be addressed:

1. Honoring HTTP cache control headers should be a requirement for any implementation that supports caching of HTTP requests. Not doing this creates a situation where developers will have to handle caching completely differently from one container to the next. Cache control header handling is laid out in the HTTP 1.1 spec, and I believe we should, at minimum, require that Cache-Control, Expires, and Pragma: no-cache be supported if the server supports caching. ETags and Last-Modified can be considered, but they're impractical for most systems, so probably not worth addressing.

1.iii.a Requiring a specific parameter being passed to the iframe makes no sense here. This is an implementation detail, and not a terribly flexible one at that. It can't possibly apply when the gadget isn't rendered in an iframe, and there is no way for developers to get at the iframes without losing the context of the containing site.

2.i In the interest of portability, the extended schema should be removed entirely, and several of the attributes should be moved to the canonical spec. Tolerating unknown attributes and tags should be a requirement, so as to allow for extension when needed. Saying that a gadget XML "MUST" conform to the extended spec doesn't really mean anything here. Remove references to igoogle.

3.i We must identify the format of the lang and country attributes here. What are the valid values for country? What are the valid values for lang? Add them or reference them. How are languages with no country resolved? If this is the same as it was for igoogle, please state that here by copying the text if necessary, but don't reference igoogle docs either.

3.ii.2 Need a reference to message bundle processing and substitution instructions

4. Must specify escaping rules and substitution order. Is __MSG_foo__ substituted before __UP_foo__ or after it? If __MSG_foo__ contains the string __UP_foo_, how should it be interpreted? User pref hangman substitutions should be marked deprecated, I think, since they're very dangerous. Require escaping of user pref substitutions since there is no programmatic way to do it, and it will lead to XSS exploits if not done.

5.ii This prose can be removed for the most part since gadgets.util.* is a mandatory library. Documentation for this function belongs in the JS API reference.

5.iii Additionally, there needs to be a concrete explanation of what support means for all features currently standardized under opensocial. These can be separate specification documents entirely, but without them implementation is ambiguous. JS API details are not specific enough, because they don't explain related behavior.

6.i.a Wasn't there an agreement about how quirks would be handled?

6.i Most of this is implementation detail. Implementation detail doesn't belong here.

6.ii What "provided url"? This implies some concrete implementation, such as an iframe. If an iframe is required, the spec needs to say so.
6.ii.b What format are lang and country in? The same as the servers? Are these an exact match for what is in the gadget xml's <Locale>s?
6.ii.c What does "the server" mean here? The parent page? How does the gadget developer's site know what this url is?

Section 6 also does too much hand waving about type=url, which is misleading and gives the wrong impression about how it can be used. Is it required that the libs parameter point to opensocial js if the gadget requires it? Since there's no actual, proven way to make it work, how can we say "MUST"? Ideally, each feature document should identify whether or not it is required to work with type=url.

"Gadget Metadata Request" (no number): This should be removed entirely. It's a vague concept at best, and anything implementing it would be a complete implementation detail. What happens if my implementation doesn't support this "Metadata Request"? What would it even mean to support it in the first place?

"Context (Container side Javascript)": This should also be removed. It's vague and says nothing relevant, so it just serves to confuse. dynamic-height has a contract, and it shouldn't matter at all what means the container uses to satisfy that contract if it supports that feature. When a gadget calls gadgets.window.setHeight, either the container adjusts the height or it does not -- period.

"Sanitized Content...": This should be a footnote, not a part of the spec itself. It's too vague and, again, tells developers and implementors nothing.

There is an enormous gap in this document, in that it does NOT explain, at any level, what the various tags and attributes in the XSD files represent. For instance:

- What does <UserPref name="foo" default_value="bar"> mean? It isn't mentioned.
- The XSD has an enumeration for the "datatype" field of <UserPref> What do these enumerated values mean?
- What does <ModulePrefs title="Yay title!!!"/> do? What does "title" represent here? Same for all other attributes.

Many more examples, too numerous to iterate. Not having details here has led to confusion amongst implementations, and today what is true on MySpace is not necessarily true on Orkut or hi5 or any other site.

[Paul Lindner]

On Fri, May 09, 2008 at 06:35:59PM -0700, Dan Peterson wrote:
> As per below, please use this thread to discuss potential improvements to
> the gadgets spec and the related XSD files:
> http://opensocial-and-gadgets-spec.googlegroups.com/web/4-a-gadgets_Spec.html

The views feature is still optional, right? If so:

In this para:

Multiple Content sections may be specified in gadget XML. Each is
labeled with one or more view identifiers, which allow the gadget to
behave or appear differently depending on the context in which it's
rendered. This context is provided by the gadget container.

Add the word optional before view.

We may also want to mention that views are optional and need to be
explicitly required.

Should we add definitions of how lang= and country= are passed in on
the URL? Under section 3 we could add:

The server needs to identify the language and country of the request
HTTP-based request servers SHOULD(MUST?) support the 'country' and
'lang' URL parameters.

--
Paul Lindner ||||| | | | | | | | | |
lin...@inuus.com

[Dan Peterson]

Hey Kevin,

Thanks for the extremely detailed feedback here -- it seems like these are all issues that aren't "any worse" than the existing 0.7 spec, but I definitely agree that the specs can and should become more RFC-like in future iterations. Let's make that happen -- but off-cycle relative to 0.8.

Sound ok?

-Dan

[Kevin Brown]

On Fri, May 23, 2008 at 6:59 PM, Dan Peterson <dpet...@google.com> wrote:

Hey Kevin,

Thanks for the extremely detailed feedback here -- it seems like these are all issues that aren't "any worse" than the existing 0.7 spec, but I definitely agree that the specs can and should become more RFC-like in future iterations. Let's make that happen -- but off-cycle relative to 0.8.

Sound ok?

Works for me.