A proposal for reporting OpenSocial capabilities (Feedback please :-)

[Lane LiaBraaten (Google)]

Hi Everyone,

A lot of developers have asked for some documentation that shows that
functions, fields, and features are supported for each container.
This sort of documentation is really useful, but can be hard to keep
up to date for one site, much less all of the containers out there.

A few colleagues and I put together a proposal to help solve this
issue. Basically each container would provide an XML file that
contains information about what features and functionality is
supported. I've drafted up a sample of this capabilities file and
posted it in the "Files" section of this group:
http://groups.google.com/group/opensocial-and-gadgets-spec/web/socialsight_support.xml

The highlights:
- The first section provides some information about the container
(name, various URLs, etc.)
- The next section ("core") contains info about what is supported by
default
- This is followed by multiple "feature" sections, each of which
outlines the JavaScript classed, functions, and fields that are
available when this fieature is included in an application.
- For each class, function, or field a status is reported that is one
of the following:
"complete" - Supported by the container. For classes, "complete"
status implies that all methods, fields, and subclasses are fully
supported.
"partial" - For classes, one or more methods, fields, or
subclasses is not supported. Can also be use to denote a method that
has a known issue.
"planned" - this container will support this class, method, or
field, but has not implemented the functionality yet.
"not available" - this class, method, or field will not be
implemented for this container.
"unknown" - equivalent to an empty element.

The intent is that each container can transform the structured data in
this file into some documentation for their site. However, if we all
use the same format for this data, we can also create a matrix of
functionality per each container. Then developers can reference this
matrix to help them create applications that will work across multiple
containers.

We'd love to heard your feedback on this approach to capabilities
reporting. Please respond to this thread with any questions or
comments on the high-level process or the XML format itself.

Thanks,
Lane

[Lane LiaBraaten (Google)]

I had another proposal out of band that I'd like to share with this
group.


The idea is to just use an @support tag in the .js files to demote the
level of support for each class, method and field. This has the huge
advantage of not needing to maintain a separate file. The only
possible downside I see is that each container would then need to
host .js files (like the ones in linked to in the spec [1]) instead of
a single XML file in order for us to generate a matrix that contains
information about multiple containers.

Container developers -- What do you think? Is this a better solution
than creating a separate XML file?

-Lane

On Mar 10, 4:51 pm, "Lane LiaBraaten (Google)"

<api.lliab...@google.com> wrote:
> Hi Everyone,
>
> A lot of developers have asked for some documentation that shows that
> functions, fields, and features are supported for each container.
> This sort of documentation is really useful, but can be hard to keep
> up to date for one site, much less all of the containers out there.
>
> A few colleagues and I put together a proposal to help solve this
> issue. Basically each container would provide an XML file that
> contains information about what features and functionality is
> supported. I've drafted up a sample of this capabilities file and

> posted it in the "Files" section of this group:http://groups.google.com/group/opensocial-and-gadgets-spec/web/social...

[Lane LiaBraaten (Google)]

and the link...
[1] http://code.google.com/apis/opensocial/docs/0.7/spec.html#compliance

On Mar 12, 8:34 pm, "Lane LiaBraaten (Google)"

[Kevin Brown]

Js files are usually minified in production for performance, so containers couldn't use the same files that they're using in production for this purpose. It's not really any better than hosting an xml file.

--
~Kevin

[Kathy Walrath]

I think hosting an xml file is still an option. We could provide a
jsdoc-toolkit template that produces the xml file from the .js files,
and leave it up to container implementers as to whether their master
copy is .js files or their .xml file.

It just seems like it might be easier to keep the information correct
if it's maintained in doc comments in .js files. When we add to the
API, it'll be much easier to make sure that each new
class/method/field has an entry, and it'll be easier to test whether
the entry is accurate. In theory, at least.

-k-

[Dan Peterson]

Lane,

Thanks for this proposal. I think providing a dashboard view of what container provide is an important thing to provide for developers. I like the XML approach as that separates the data from the presentation layer, so it can be used in a variety of ways.

What do other folks think? Any comments about the detailed proposal?

-Dan

[Kevin Marks]

How about making a gadget like Cassie's spec-conformance tester to introspect the container and report back to a hosting service?
That would directly verify the API support, rather than requiring each container to maintain a parallel xml file alongside the actual API.

[John Panzer]

This would be cool -- like feedvalidator.org but just informational reporting... if it were a standard Shindig-developed gadget it could be something of a standard test case for container developers too. 

[Kevin Brown]

On Wed, Mar 19, 2008 at 3:57 PM, John Panzer <jpa...@google.com> wrote:

This would be cool -- like feedvalidator.org but just informational reporting... if it were a standard Shindig-developed gadget it could be something of a standard test case for container developers too. 

There's no reason for Shindig to be responsible for that gadget -- it's a spec compliance test,  and like any compliance test I think it belongs with the specs, not the reference implementation.

--
~Kevin

[Lane LiaBraaten (Google)]

On Wed, Mar 19, 2008 at 4:29 PM, Kevin Brown <et...@google.com> wrote:

On Wed, Mar 19, 2008 at 3:57 PM, John Panzer <jpa...@google.com> wrote:

This would be cool -- like feedvalidator.org but just informational reporting... if it were a standard Shindig-developed gadget it could be something of a standard test case for container developers too. 

There's no reason for Shindig to be responsible for that gadget -- it's a spec compliance test,  and like any compliance test I think it belongs with the specs, not the reference implementation.

Agreed.  I think this capabilities gadget is a good idea (and doesn't belong in Shindig). 

The thing a gadget doesn't provide is a single source of capabilities information for multiple containers.  That is, if all containers fill out an XML file (which they could generate using the capabilities gadget), then the XML files can be aggregated into a single matrix of data that covers multiple containers.

-Lane

--
~Kevin

[Kevin Brown]

On Wed, Mar 19, 2008 at 4:35 PM, Lane LiaBraaten (Google) <api.ll...@google.com> wrote:

On Wed, Mar 19, 2008 at 4:29 PM, Kevin Brown <et...@google.com> wrote:

On Wed, Mar 19, 2008 at 3:57 PM, John Panzer <jpa...@google.com> wrote:

This would be cool -- like feedvalidator.org but just informational reporting... if it were a standard Shindig-developed gadget it could be something of a standard test case for container developers too. 

There's no reason for Shindig to be responsible for that gadget -- it's a spec compliance test,  and like any compliance test I think it belongs with the specs, not the reference implementation.

Agreed.  I think this capabilities gadget is a good idea (and doesn't belong in Shindig). 

The thing a gadget doesn't provide is a single source of capabilities information for multiple containers.  That is, if all containers fill out an XML file (which they could generate using the capabilities gadget), then the XML files can be aggregated into a single matrix of data that covers multiple containers.

We could also treat the test results as the inputs into something that outputs the xml, making it a fairly automated process for containers to generate the XML file, with the only manual step being copying the output xml to the well-known location.

--
~Kevin

[John Panzer]

On Wed, Mar 19, 2008 at 4:35 PM, Lane LiaBraaten (Google) <api.ll...@google.com> wrote:

On Wed, Mar 19, 2008 at 4:29 PM, Kevin Brown <et...@google.com> wrote:

On Wed, Mar 19, 2008 at 3:57 PM, John Panzer <jpa...@google.com> wrote:

This would be cool -- like feedvalidator.org but just informational reporting... if it were a standard Shindig-developed gadget it could be something of a standard test case for container developers too. 

There's no reason for Shindig to be responsible for that gadget -- it's a spec compliance test,  and like any compliance test I think it belongs with the specs, not the reference implementation.

Agreed.  I think this capabilities gadget is a good idea (and doesn't belong in Shindig). 

There's no code project for the specs; there could be one of course.  Note that Shindig GGS is itself in effect a compliance test for gadgets...
 

[Kevin Marks]

On Wed, Mar 19, 2008 at 4:42 PM, Kevin Brown <et...@google.com> wrote:
> On Wed, Mar 19, 2008 at 4:35 PM, Lane LiaBraaten (Google)
> <api.ll...@google.com> wrote:
>
> >
> >
> >
> >
> > On Wed, Mar 19, 2008 at 4:29 PM, Kevin Brown <et...@google.com> wrote:
> >
> > >
> > >
> > > On Wed, Mar 19, 2008 at 3:57 PM, John Panzer <jpa...@google.com> wrote:
> > >
> > >
> > >
> > >
> > > > This would be cool -- like feedvalidator.org but just informational
> reporting... if it were a standard Shindig-developed gadget it could be
> something of a standard test case for container developers too.
> > >
> > >
> > >
> > >
> > > There's no reason for Shindig to be responsible for that gadget -- it's
> a spec compliance test, and like any compliance test I think it belongs
> with the specs, not the reference implementation.
> >
> >
> > Agreed. I think this capabilities gadget is a good idea (and doesn't
> belong in Shindig).
> >
> > The thing a gadget doesn't provide is a single source of capabilities
> information for multiple containers. That is, if all containers fill out an
> XML file (which they could generate using the capabilities gadget), then the
> XML files can be aggregated into a single matrix of data that covers
> multiple containers.
>
> We could also treat the test results as the inputs into something that
> outputs the xml, making it a fairly automated process for containers to
> generate the XML file, with the only manual step being copying the output
> xml to the well-known location.
>

Well, the gadget could POST the results to the aggregation site using
io.makeRequest, removing the need to put it at a well-known location.
Also, it would be signed by the container, so we would know which one
it came from...

[Brian Eaton]

On Wed, Mar 19, 2008 at 5:13 PM, Kevin Marks <kevin...@gmail.com> wrote:
> Well, the gadget could POST the results to the aggregation site using
> io.makeRequest, removing the need to put it at a well-known location.
> Also, it would be signed by the container, so we would know which one
> it came from...

Not really; we'd just have a POST that had been signed by a container
we'd never heard of, whose certificate we don't have.