[0.8.1] Clarify & improve the OpenSocial Gadget Specification

[Chris Chabot]

Kevin Brown suggested that "some parts of the existing specification
are so vague that any person's interpretation might be viewed as a
change", and proposed a clearer & improved specification.

The original message:
http://groups.google.com/group/opensocial-and-gadgets-spec/msg/b61cc49ec9ecac59?hl=en

And his proposed OpenSocial Gadget Specification (the link in the
original message was google only, later he posted this public one):
http://docs.google.com/View?id=dgf9q4v4_2wkcbvn3z

It might be a bit much to digest in the 0.8.1 timeframe, but since we
are on a 'clarify and clean up' revision of the OpenSocial
specification, this might be a great time to include this too.

Comments? Votes?

[Cassie]

Kevin - if you could provide a diff between your text and the current
spec text it would be easier to vote on.

[John Hjelmstad]

It's essentially a complete rewrite, so the diff is basically:

< [old text]
> [new text]

Yet the semantics are equivalent, or where unspecified in the original spec, aim to reflect the grassroots consensus reflected largely in the Shindig implementation. The latter might be considered "new" by some, and fills in a few unspecified details in the 0.8 spec round. As such some might find it controversial or simply more substantial than desired for 0.8.1.

I feel the spec rewrite is a great, and necessary, step toward defining in useful terms what it really means to support gadgets. IMO it's an invaluable precursor to subsequent spec iterations, as it's far more complete, better organized, and written in standard terminology, all making it possible to achieve one major thing I want to see out of 0.9 - a *.patch for every proposal (and a spec version defined as the merger of same).

So while I'm strongly +1 on a rewritten spec (and feel it should be [based on] Kevin's), we need to:
1. Figure out how to manage the introduction of this spec. Ideally this will be a gadgets spec as truly defined by the community. I feel it's large enough that we won't - or shouldn't - make consensus on it within this one week.
2. Answer, foundationally: Should the gadgets and OpenSocial spec versions be tied together? This is the subject of an alternate thread, so I won't rat-hole (too much) on it here.

As it happens, I personally don't feel OS + gadgets should be versioned together (at least yet). In any case the explicit aim of the rewrite is to add nothing semantically new, so even if it were explicitly versioned, 0.8 === 0.8.1.

I favor managing this as an important separate topic, discussion to start ASAP (immediately, or at latest right after 0.8.1 to ensure everyone's focus). Goal: ratification before 0.9.

--John

[Chris Chabot]

Hi John, you bring up a very good point actually.

I guess my intend when i wrote the original thread was to reach consensus that we 'intend to aim for feature parity, implemented in a way that makes sense to the situation', which i can see is undefined enough :)

On the other hand i guess is more defined, is my hope that we can prevent a divergence between the functionality of the JS and REST specifications.

It makes more sense to fetch all the supported fields in a single http call through the RESTful interface when your a 3rd party server, but it also makes a lot of sense to inject the supported fields directly into the javascript scope when the gadget is being rendered, and thus saving having to a round trip to retrieve this information.

So i won't suggest reaching a situation where we have abandon what makes sense, however i would suggest having the intend that the both API's should provide the same functionality (but in a way that makes sense for the environment)

[Kevin Brown]

---- entire existing document
+++ new document

Done!

[Dan Peterson]

I agree with John -- Kevin's proposed spec re-write is a healthy direction, but I'd rather we not try and force it into the 0.81 timeline, so we can make sure it is a pristine spec and not rushed by this particular timeline.

I'm open to whether we try and do it "before" or "during" 0.9, but I see no reason for us not to start discussion now.

-Dan

[chabotc]

This proposal did not find support for making it to the 0.8.1
revision, and people felt it was best left for 0.9.

Voting for this thread ended, however discussion does not have to
be :)

On Jul 22, 11:30 am, Chris Chabot <chab...@xs4all.nl> wrote:
> Kevin Brown suggested that "some parts of the existing specification  
> are so vague that any person's interpretation might be viewed as a  
> change", and proposed a clearer & improved specification.
>

> The original message:http://groups.google.com/group/opensocial-and-gadgets-spec/msg/b61cc4...

[Kevin Brown]

I almost forgot this one, and given the rather large changes being proposed for 0.9 (pipelining, OSML, proxied rendering), I think it's essential that we have a better basis to go by. The current state of compatibility in this department across containers is fairly weak, and I think the only way we can address that weakness is by getting it write.

My document has grown a little long in the tooth (I wrote it in June), but it's probably not that far off since most of 0.8 and 0.8.1 dealt with RESTful API changes.

Thoughts?

[Kevin Brown]

s/write/right

Or maybe that wasn't a mistake... :)