Extensions

[Lane LiaBraaten]

Extensions is a big topic, so to get us started I just dumped a bunch of questions and gave my (strawman) answers in this wiki page: http://wiki.opensocial.org/index.php?title=Extensions

Next steps?
 - read the wiki page and contribute additional questions/answers in that page
 - reply on list with what you like or don't like, or anything you'd like to discuss

Once we get a bit more clarity on direction we'll need to figure out how to represent these concepts in the spec itself and address and spec process changes that may occur as a result of our discussions.

-Lane

[Lev Epshteyn]

Looks like a good start.

Are we expecting extension features to have prefixed names prior to adoption into the spec? For example:

<Require feature="myspace-music"/>

This could address the possibility that two different containers want to have a slightly different music extension. Or is the idea to prevent things like that from occuring?

If not, it may be useful to allow for syntax to require one of many implementations a gadget supports (in order of preference):

<Require feature="myspace-music, orkut-music"/>

[Lane LiaBraaten]

I think we should do what we can to avoid this situation.  If two containers are interested in supporting a music API, they should collaborate on a single extension.  Again, if you're going to implement X, you MUST implement it like this...

-Lane

[ashish patel]

hello there..

i'm new to opensocial..

can u guide me in the right direction?

please help..
I am Neo, but my people call me The One.

[Mark W.]

Lane,

I made a few comments on the wiki page. I tried to put some precision
around the kinds of extensions would be possible to make to the spec.
One of the key differentiators is whether you need an API change. For
example, I might want to "standardize" a new set of fields for
profile, e.g. ProgrammingLanguages, and not have to change the way I
access/update them. Alternatively, something like pub/sub will
introduce new APIs. These are two very different ways of extending the
spec, both of which seem valid.

I agree with your assertion from the earlier post where container
implementers should be encouraged to collaborate transparently with
each other.

-Mark W.

On Sep 10, 4:45 pm, Lane LiaBraaten <api.lliab...@gmail.com> wrote:
> I think we should do what we can to avoid this situation.  If two containers
> are interested in supporting a music API, they should collaborate on a
> single extension.  Again, if you're going to implement X, you MUST implement
> it like this...
>
> -Lane
>
> On Thu, Sep 10, 2009 at 12:04 PM, Lev Epshteyn <le...@google.com> wrote:
> > Looks like a good start.
>
> > Are we expecting extension features to have prefixed names prior to
> > adoption into the spec? For example:
>
> > <Require feature="myspace-music"/>
>
> > This could address the possibility that two different containers want to
> > have a slightly different music extension. Or is the idea to prevent things
> > like that from occuring?
>
> > If not, it may be useful to allow for syntax to require one of many
> > implementations a gadget supports (in order of preference):
>
> > <Require feature="myspace-music, orkut-music"/>
>

[Mark W.]

Lane,

I made a few comments on the wiki page. I tried to put some precision
around the kinds of extensions would be possible to make to the spec.
One of the key differentiators is whether you need an API change. For
example, I might want to "standardize" a new set of fields for
profile, e.g. ProgrammingLanguages, and not have to change the way I
access/update them. Alternatively, something like pub/sub will
introduce new APIs. These are two very different ways of extending the
spec, both of which seem valid.

I agree with your assertion from the earlier post where container
implementers should be encouraged to collaborate transparently with
each other.

-Mark W.



On Sep 10, 4:45 pm, Lane LiaBraaten <api.lliab...@gmail.com> wrote:

> I think we should do what we can to avoid this situation.  If two containers
> are interested in supporting a music API, they should collaborate on a
> single extension.  Again, if you're going to implement X, you MUST implement
> it like this...
>
> -Lane
>
> On Thu, Sep 10, 2009 at 12:04 PM, Lev Epshteyn <le...@google.com> wrote:
> > Looks like a good start.
>
> > Are we expecting extension features to have prefixed names prior to
> > adoption into the spec? For example:
>
> > <Require feature="myspace-music"/>
>
> > This could address the possibility that two different containers want to
> > have a slightly different music extension. Or is the idea to prevent things
> > like that from occuring?
>
> > If not, it may be useful to allow for syntax to require one of many
> > implementations a gadget supports (in order of preference):
>
> > <Require feature="myspace-music, orkut-music"/>
>

[Lane LiaBraaten]

Thanks for the feedback, Mark.

Open Question:  "What is the difference between a MAY in the spec and an extension?"

I think the answer here will greatly affect a lot of the decisions w.r.t the spec.  In the other thread (Proposal for 1.0 [1]) there's an issue raised about "too many MAYs" in the spec that may be at odds with the current extensions proposal [2].

The current proposal basically says that once an extension gets to a certain point of maturity it is added (probably as a MAY) to the spec.  So if there's an issue with having MAYs in the spec then we need to tease it out.  I have a feeling that the issue is not so much with having MAYs in the spec but more related to two things:

• particular features being MAYs as opposed to MUSTs (e.g. RPC)
• the desire for Shindig, being the reference implementation, to implement all the MAYs
  

My current answer to the open question above is that an extension should be treated as an experimental feature (i.e. the APIs are subject to change, so if developer's use it, they should expect high maintenance costs).  On the other hand, a MAY in the spec means that the API is stable and developers can use it without worrying that they'll have to update their code.

-Lane


[1] http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/23729552aad553f0#

[2] http://wiki.opensocial.org/index.php?title=Extensions

[Arne Roomann-Kurrik]

I'm less excited about treating extensions as "experimental" features.  There very well may be very mature extension documents that are in production use but simply too specific to include in the core spec.  I would caution against associating instability with extensions for this reason.

Extension documents should probably have an agreed upon labeling system to indicate the level of maturity of the extension itself.  Off the top of my head, this could be something like: 

• draft - proposed feature without any implementors
• prototyped - working implementation available
• production - in production on at least one container

Of course, this doesn't answer the question of what the difference between a MAY in the spec and an extension is.  To me, an extension is an optional portion of the specification which iterates on its own timeline.  An extension may go from draft to production in a much shorter time than a spec MAY feature.  

Ultimately, there should be very little difference between a "production" extension and a spec MAY feature.  The separation is more of a clerical necessity to keep things clean and organized for implementors.

~Arne

[Mark W.]

I think one of the things we are trying to do is provide a framework
in which new capabilities for OpenSocial can evolve at different
rates. For example, we've already started working with the OpenAjax
guys to integrate the OA Hub technology into OpenSocial. What we'll
need to provide to the community is, ultimately, an official proposal
that can be reviewed and approved. This proposal will have with it
some modifications for the spec and some code that demonstrates its
feasibility. Since we are trying to scope 1.0 to have no new features,
this is already targeted at 1.1.

So right now, I think of pub/sub as incubating. We want to work on it
in the open, with as much help/support from the community that we can
get. When we are done, and comfortable with what we've got, and the
spec process for 1.1 officially opens, THEN we will submit a proposal
and prototype. Your idea of a draft life cycle may help here:
Something like:
* incubating: as it's being worked on, ideally, in an open manner
within the community.
* draft: submitted to the specification process for inclusion in
OpenSocial. Expected to have prototypes with spec changes et.
* provisional: approved and accepted by the community. APIs are stable
with expected level of support from the community.
* Final/Offical/: Officially part of the spec. APIs are stable. Fully
integrated into the spec's programming model et.

So the creation of the proposal for a new capability to be added to
OpenSocial can occur in the community outside of the specification
process. This allows new capabilities to evolve at their own rate.
This also allows the "prototype" stage to let the community focus on
validating the work versus developing the work.

So back to the question of what does "MAY" mean?
Going back to my pub/sub example, we're going to document the
semantics of the capability and the requirements of a developer who is
coding to the defined APIs. It is likely that there will be some
things the developer is required to do, i.e. MUST. Other things
regarding pub/sub they could choose to do, i.e. MAY. Going further,
there are things that perhaps they don't have to do, but it's highly
recommended, i.e. SHOULD. These are very specific words that we've
decided to use relative to how we describe the capability we're
proposing be added to OpenSocial.

Which brings us to the question of if a provider is required to offer
this new capability. Here, there seems to be a logical layering of
capability. For example, as we see the rise in importance of
integration, it seems perfectly reasonable for a provider to offer
only the REST APIs, e.g. no gadgets. It also seems reasonable that
some providers want to offer a capability like Micropayments while
others do not. I think we can define a set of capability that in order
to call yourself an OpenSocial provider, you have to provide. Whatever
this is, it should map to a set of specifications that have been
approved by the OpenSocial Foundation.

In addition, we should also be able to have community added
capability, e.g. micropayments, with a well defined set of semantics,
that might be used by providers. The OpenSocial community should
ensure, as part of the specification development process, that their
APIs and semantics are consistent with the fundamental programming
model defined the specifications that a container must provide. These
should be discoverable in a well defined manner. A provider could
choose to implement this capability. I don't think there is one main
document that says, as a provider, you MAY do micropayments. Rather, I
see a primer of some sort that says something like...
If you want to do integration based on OpenSocial, then you use this
set of specs (e.g. REST + OAuth). If you want to offer the ability to
host gadgets that use the OpenSocial APIs then use these specs
(OpenSocial, Gadgets, OSML, et). If you want to add micropayment
capability to your web site, use these specs (OpenSocial, Gadgets,
OSML, Micropayments). This is sort of like a set of OpenSocial
"application profiles".

OK. So this post turned out a bit longer than I initially expected. I
hope it all makes sense given that it's 6pm on the east coast--way
past Miller Time.

-Mark W.

On Sep 18, 1:40 pm, Arne Roomann-Kurrik <kur...@google.com> wrote:
> I'm less excited about treating extensions as "experimental" features.
>  There very well may be very mature extension documents that are in
> production use but simply too specific to include in the core spec.  I would
> caution against associating instability with extensions for this reason.
> Extension documents should probably have an agreed upon labeling system to
> indicate the level of maturity of the extension itself.  Off the top of my
> head, this could be something like:
>

>    - draft - proposed feature without any implementors
>    - prototyped - working implementation available
>    - production - in production on at least one container

>
> Of course, this doesn't answer the question of what the difference between a
> MAY in the spec and an extension is.  To me, an extension is an optional
> portion of the specification which iterates on its own timeline.  An
> extension may go from draft to production in a much shorter time than a spec
> MAY feature.
>
> Ultimately, there should be very little difference between a "production"
> extension and a spec MAY feature.  The separation is more of a clerical
> necessity to keep things clean and organized for implementors.
>
> ~Arne
>

> On Mon, Sep 14, 2009 at 10:55 AM, Lane LiaBraaten <api.lliab...@gmail.com>wrote:
>
> > Thanks for the feedback, Mark.
>
> > Open Question:  "What is the difference between a MAY in the spec and an
> > extension?"
>
> > I think the answer here will greatly affect a lot of the decisions w.r.t
> > the spec.  In the other thread (Proposal for 1.0 [1]) there's an issue
> > raised about "too many MAYs" in the spec that may be at odds with the
> > current extensions proposal [2].
>
> > The current proposal basically says that once an extension gets to a
> > certain point of maturity it is added (probably as a MAY) to the spec.  So
> > if there's an issue with having MAYs in the spec then we need to tease it
> > out.  I have a feeling that the issue is not so much with having MAYs in the
> > spec but more related to two things:
>

> >    - particular features being MAYs as opposed to MUSTs (e.g. RPC)
> >    - the desire for Shindig, being the reference implementation, to

> >    implement all the MAYs
>
> > My current answer to the open question above is that an extension should be
> > treated as an experimental feature (i.e. the APIs are subject to change, so
> > if developer's use it, they should expect high maintenance costs).  On the
> > other hand, a MAY in the spec means that the API is stable and developers
> > can use it without worrying that they'll have to update their code.
>
> > -Lane
>
> > [1]

> >http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thr...
>
> > [2]http://wiki.opensocial.org/index.php?title=Extensions

[Lane LiaBraaten]

I've incorporated Mark, et al.'s feedback into the Extensions page (including a sweet flow chart from Arne).  It's a pretty significant overhaul, with much more detail about the life cycle of an extension, so please take a look:
http://wiki.opensocial.org/index.php?title=Extensions

-Lane

[Lane LiaBraaten]

@Mark - can I list you as the owner for this proposal on http://wiki.opensocial.org/index.php?title=Spec_Changes?

[Mark W.]

Sure!


On Sep 23, 2:56 pm, Lane LiaBraaten <lliab...@google.com> wrote:
> @Mark - can I list you as the owner for this proposal onhttp://wiki.opensocial.org/index.php?title=Spec_Changes?

>
> On Wed, Sep 23, 2009 at 11:03 AM, Lane LiaBraaten <lliab...@google.com>wrote:
>
> > I've incorporated Mark, et al.'s feedback into the Extensions page
> > (including a sweet flow chart from Arne).  It's a pretty significant
> > overhaul, with much more detail about the life cycle of an extension, so
> > please take a look:
> >http://wiki.opensocial.org/index.php?title=Extensions
>
> > -Lane
>

> ...
>
> read more »

[Bess Ho]

Chart well done. Wish we can see more flow charts on the spec.
http://wiki.opensocial.org/images/2/2d/Life_of_an_extension.jpg

--
Bess Ho

[Chris Chabot]

I feel that the proposal doesn't quite cover yet what our position is on moving existing functionality to extensions.

I've heard people suggest (not voted for/accepted mind you, but still worth noting) that osapi, os templating and appdata would be good candidates for extensions, even though we have live deployments of all of these and if the extension would really iterate, are likely break compatibility with 0.9.

The process seems quite clear for new functionality (pubsub, activitystrea.ms, payments, etc) and how it could graduate and be considered to become part of the core spec, but do we have a consensus on what our suggested policy is to moving things out of the core into extensions?

[Lane LiaBraaten]

I think we can follow roughly the same process as we would with new extensions:

1. Draft an OpenSocial Enhancement (OE) doc for the feature
2. If it's in the spec there's already an implementation/prototype, so the extension would move from "draft" to "incubating" easily (by default?)
3. In the next spec iteration we'd ask the same two questions..
1. "Is the incubating extenstion "ready" to graduate?
1. If no, we'd pull it from the spec and it would become only an "incubating extension"
2. If yes, we'd ask the next question
   
2. "Is this OE appropriate for the core spec?"
• If yes, we don't move it out
• If no, it becomes an "accepted" OE
  

Does that sound reasonable?

The "Highly Recommended Features" [1] in the gadget spec seem like good candidates for being moved from the spec to extensions.  I think we could pilot this process on those features in this iteration.

-Lane

[1] http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/Gadgets-API-Specification.html#rfc.section.6

[Mark W.]

In re-reading this, one question came to mind.... Should we think
about using the incubation process as a way to get ahead of the IP?
That is, to go into incubation, you have to have the non-assert
signed? Does this help/hurt? Not sure, just thinking out loud...

-Mark W.

On Oct 1, 1:33 pm, Lane LiaBraaten <lliab...@google.com> wrote:
> I think we can follow roughly the same process as we would with new
> extensions:
>

>    1. Draft an OpenSocial Enhancement (OE) doc for the feature
>    2. If it's in the spec there's already an implementation/prototype, so

>    the extension would move from "draft" to "incubating" easily (by default?)

>    3. In the next spec iteration we'd ask the same two questions..
>       1. "Is the incubating extenstion "ready" to graduate?
>          1. If no, we'd pull it from the spec and it would become only an
>          "incubating extension"
>          2. If yes, we'd ask the next question
>          2. "Is this OE appropriate for the core spec?"
>    - If yes, we don't move it out
>          - If no, it becomes an "accepted" OE

>
> Does that sound reasonable?
>
> The "Highly Recommended Features" [1] in the gadget spec seem like good
> candidates for being moved from the spec to extensions.  I think we could
> pilot this process on those features in this iteration.
>
> -Lane
>

> [1]http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/Gad...

>
> On Sat, Sep 26, 2009 at 6:22 AM, Chris Chabot <chab...@google.com> wrote:
> > I feel that the proposal doesn't quite cover yet what our position is on
> > moving existing functionality to extensions.
>
> > I've heard people suggest (not voted for/accepted mind you, but still worth
> > noting) that osapi, os templating and appdata would be good candidates for
> > extensions, even though we have live deployments of all of these and if the
> > extension would really iterate, are likely break compatibility with 0.9.
>
> > The process seems quite clear for new functionality (pubsub,
> > activitystrea.ms, payments, etc) and how it could graduate and be
> > considered to become part of the core spec, but do we have a consensus on
> > what our suggested policy is to moving things out of the core into
> > extensions?
>

[Mark W.]

Lane,
In the current text on the wiki, we've got the section about versions
(http://wiki.opensocial.org/index.php?title=Extensions). Another
thread for 1.0 talks about adding versions to the core features. It
seems like we'd want a consistent scheme that we use across
OpenSocial. I'd like to take this section and align it with that
effort.

What do you think?

-Mark W.

On Oct 1, 1:33 pm, Lane LiaBraaten <lliab...@google.com> wrote:

> I think we can follow roughly the same process as we would with new
> extensions:
>

>    1. Draft an OpenSocial Enhancement (OE) doc for the feature
>    2. If it's in the spec there's already an implementation/prototype, so

>    the extension would move from "draft" to "incubating" easily (by default?)

>    3. In the next spec iteration we'd ask the same two questions..
>       1. "Is the incubating extenstion "ready" to graduate?
>          1. If no, we'd pull it from the spec and it would become only an
>          "incubating extension"
>          2. If yes, we'd ask the next question
>          2. "Is this OE appropriate for the core spec?"
>    - If yes, we don't move it out
>          - If no, it becomes an "accepted" OE

>
> Does that sound reasonable?
>
> The "Highly Recommended Features" [1] in the gadget spec seem like good
> candidates for being moved from the spec to extensions.  I think we could
> pilot this process on those features in this iteration.
>
> -Lane
>

> [1]http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/Gad...

>
> On Sat, Sep 26, 2009 at 6:22 AM, Chris Chabot <chab...@google.com> wrote:
> > I feel that the proposal doesn't quite cover yet what our position is on
> > moving existing functionality to extensions.
>
> > I've heard people suggest (not voted for/accepted mind you, but still worth
> > noting) that osapi, os templating and appdata would be good candidates for
> > extensions, even though we have live deployments of all of these and if the
> > extension would really iterate, are likely break compatibility with 0.9.
>
> > The process seems quite clear for new functionality (pubsub,
> > activitystrea.ms, payments, etc) and how it could graduate and be
> > considered to become part of the core spec, but do we have a consensus on
> > what our suggested policy is to moving things out of the core into
> > extensions?
>

[Lane LiaBraaten]

Sounds good to me.

-Lane

[Mark W.]

Lane, Chris C., Arne, et al

I was starting to draft of some text for the spec, and as I was
referencing back this thread, a question came to mind that I wanted to
get on the table for your input....

Are we dealing with two aspects of extensions in this thread:
1) the process of defining, collaborating on, proposing to the spec,
and ultimately, including in the spec, a new bit of functionality
2) the way in which the extension must be defined, conform to, declare
dependencies et...

IF we are really dealing with two distinct things, the process and the
"the content", then do they both belong in the spec.

More specifically, the life cycle that was defined for an extension
and how we encourage that seems better suited for the development
process.

What seems appropriate for the spec is language around what extensions
need to provide in order to be an extension. Something like (and these
are only examples)....
Extensions MUST declare the level of the core spec with which they are
compatible.
Extensions MUST declare other extensions that are required for their
proper operation
Extensions SHOULD integrate into the OpenSocial discovery mechansim

Netting this out, here's what's on the table:
1) Move the life cycle part of this work as an amendment to the
development process
2) Clearly define what is required of an extension as part of the
OpenSocial specification

What do you think...??

-Mark W.



On Oct 1, 1:33 pm, Lane LiaBraaten <lliab...@google.com> wrote:

> I think we can follow roughly the same process as we would with new
> extensions:
>

>    1. Draft an OpenSocial Enhancement (OE) doc for the feature
>    2. If it's in the spec there's already an implementation/prototype, so

>    the extension would move from "draft" to "incubating" easily (by default?)

>    3. In the next spec iteration we'd ask the same two questions..
>       1. "Is the incubating extenstion "ready" to graduate?
>          1. If no, we'd pull it from the spec and it would become only an
>          "incubating extension"
>          2. If yes, we'd ask the next question
>          2. "Is this OE appropriate for the core spec?"
>    - If yes, we don't move it out
>          - If no, it becomes an "accepted" OE

>
> Does that sound reasonable?
>
> The "Highly Recommended Features" [1] in the gadget spec seem like good
> candidates for being moved from the spec to extensions.  I think we could
> pilot this process on those features in this iteration.
>
> -Lane
>

> [1]http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/Gad...

>
>
>
> On Sat, Sep 26, 2009 at 6:22 AM, Chris Chabot <chab...@google.com> wrote:
> > I feel that the proposal doesn't quite cover yet what our position is on
> > moving existing functionality to extensions.
>
> > I've heard people suggest (not voted for/accepted mind you, but still worth
> > noting) that osapi, os templating and appdata would be good candidates for
> > extensions, even though we have live deployments of all of these and if the
> > extension would really iterate, are likely break compatibility with 0.9.
>
> > The process seems quite clear for new functionality (pubsub,
> > activitystrea.ms, payments, etc) and how it could graduate and be
> > considered to become part of the core spec, but do we have a consensus on
> > what our suggested policy is to moving things out of the core into
> > extensions?
>

[Lane LiaBraaten]

yep - that sounds right to me.  I think we'll end up with a change to the spec and the spec process.  Since the two are closely tied I think we should draft them up together.

-Lane

[Mark W.]

OK... On the wiki page I'll start crafting the language. I'll make
sure to delineate what is spec process and what is spec.

-Mark W.