Proposal for 1.0 - Clarify Separation of Gadgets (opensocial namespace)

[Jon]

How to address the issues of "opensocial" name space where it is
really not specific to opensocial?

Some examples:
opensocial-i18n - feature name
opensocial_proxied_content - a needed flag for proxied content
opensocial_viewer_id, opensocial_owner_id - if we keep the generic
concepts of viewer and owner
xmlns:os="http://ns.opensocial.org/2008/markup" - pipelineing
namespace
type="text/os-data" - pipelining script type
opensocial-data - pipeline feature name
opensocial-templates - template feature name
type="text/os-template" - script type for templates

I don't think we want to break existing gadgets, so simply changing
the name is not a viable option.

Option 1: Grandfather in existing names
Simply keep them as is with a note, that these are for generic
functionality. Ugly, but perhaps for things that are rather difficult
to solve with the other methods (URL parameters:
opensocial_proxied_content, etc...)

Option 2: Deprecate current usage and rename
* This would be good for opensocial-i18n.
* Could work for opensocial_proxied_content, although not as clean
since each URL would need to carry both arguments.
* opensocial_viewer/owner_id - similar to above. One reason for
splitting that to the OpenSocial spec. (See Lane's comment on the
initial spec review)

Option 3: Detect application is OpenSocial, use "opensocial", else use
"gadget"
For the URL parameters opensocial_proxied_content and
opensocial_viewer/owner_id have some method for detecting if the
application is opensocial, if so use the opensocial qualified names,
else use the new gadget only names. I don't like this as much as I
like it, but it is an option.

Pipelining and Templating names are more interesting as they qualify a
group of operations that can be considered core gadget, as well as OS
extensions.

Option 4A: Complete separation
Have namespaces and types that either include gadget core, or OS.
gad:HttpRequest would be core, os:People would be OS. With the
requirement for the script blocks to include both core and OS, it
might be possible for pipelining, but what would we use as the type
for templating? Plus we would need to do some deprecation with this
method.

Option 4B: OpenSocial includes Gadget Core
There will be a namespace that is pure gadget core functionality.
There will be features gadget-data and gadget-templates that are also
pure gadget. Then there is the OpenSocial extensions that will
"include" all of the gadget core. Gadget authors will use the OS
namespace and script types, and will get all Gadget and OS
functionality. The opensocial-data and opensocial-templates features
will depend upon the gadget-* features. This is 100% backward
compatible, a "core only" gadget could be created and run cross-
container.

[Kevin Brown]

I don't really see what we'd actually gain by doing this, and it creates a whole host of compatibility problems. Is it really a problem for gadgets to be a subset of opensocial?

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

[Jon]

Should there be a clean separation of core gadget from OpenSocial?

The topic has come up several time, and there are people on both
sides. The purpose of the 1.0 release is to clarify the documents, so
perhaps the time to act is now.

I believe that separation of gadgets framework from OpenSocial can
make the gadgets framework a viable "widget" framework for other
applications. The competitors, Open Ajax and W3C Widgets seem to be
separate from applications, actually they don't seem to have
applications! The fact that we have a large deployed base with
applications is a plus, but it is also a disadvantage because it is
easy to blur the line between gadget framework and application.

Gadgets are a great technology. Gadgets, separate from OpenSocial
should encourage adoption in other areas, providing a wider audience
for the basic features. I don't have a crystal ball as to what the
future will be, but today, all the rewriting, escaping, caja, etc...
are really all part of core gadget technology. These are some hard
problems that can benefit by having a wide audience, and of course
OpenSocial will benefit from the solution.

Gadgets provide a great framework for API extensions such as
pipelining, templates, REST and RPC that provide protocols for smooth
interoperability between gadgets running in the browser and remote
server side applications providing complex data mashups as well as
batch job support. I believe in this case, gadgets go beyond what our
competitors do.

On the other hand, we could simply say that gadgets and OpenSocial are
inseparable, and blur the dividing line so much that groups that don't
want to do OpenSocial, but want to do web components will look
elsewhere. The "blur" exists today, the documents for advanced
features like pipelineing, templates, REST and RPC look very
OpenSocial, not very general. I still see a clear dividing line, but
the casual observer may not.

This is simply my opinion, the specification is a group effort. If
there is support for this, I'm willing to do the work to author the
documents.

Jon

On Nov 2, 8:58 pm, Kevin Brown <e...@google.com> wrote:
> I don't really see what we'd actually gain by doing this, and it creates a
> whole host of compatibility problems. Is it really a problem for gadgets to
> be a subset of opensocial?
>

> > opensocial-and-gadg...@googlegroups.com<opensocial-and-gadgets-spec%2Bunsu...@googlegroups.com>
> > .

[Jon]

Any positive support and/or feedback?

Kevin expresses a valid point, there are some thorny issues which I
outlined and hoped to get some feedback as to what people preferred?

[Kevin Brown]

I think if gadgets are a *clearly defined* subset of opensocial, you get this. Sure, using "opensocial gadgets", but not dealing with social data may seem a little awkward at first, but plenty of projects are doing it today already.

That said, if enough people really think that there's a clean way to unwind the dependencies (particularly concepts like owner / viewer), I'm all for it.
 

To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

[Tim Moore]

I like the idea of keeping a boundary between the specifications, but
it doesn't seem to have broad consensus among the spec authors.
Without everybody on the same page, I fear that the wall will remain
leaky.

For features and template tags, I think option 4b is the most flexible
and backwards-compatible, though it is a little bit more complex.

For content types, I don't necessarily see any problems with leaving
them as they are. Presumably the gadgets spec would still fall under
the umbrella of OpenSocial, as "OpenSocial Gadgets" rather than being
pulled out into a separate body. I guess that's a little confusing,
but I think the confusion might be better resolved by renaming what's
now known as the OpenSocial spec to something like the "OpenSocial
Social Data APIs". So you end up with two "legs" --- OpenSocial
gadgets (with sub-specs for templates, proxied content, etc.) and
OpenSocial data APIs (with sub-specs for JavaScript, REST, & RPC).

For the query parameters, I think trying to change them would cause
too many problems, so they might have to remain as a wart. Why would
we want to have owner and viewer as part of the gadget spec and not
the social data spec? What would they mean in the absence of Person
APIs?

-- Tim

[Jon]

I'm worried about "broad consensus" as well, but I think it is the
right thing to do. I'll go ahead and finish the Gadget Specification,
and will take a stab at the pipelining and templating in pass 2.

For the URL parameters we cannot change, I'll adopt Option 1 -
Grandfathering

opensocial-i18n will be deprecated and replaced with i18n. Containers
will need to support both till some time, like 2.0?

Option 4b for the templating and pipelining.

[Tim Moore]

On Nov 4, 4:27 pm, Jon <jon.weyga...@gmail.com> wrote:
> opensocial-i18n will be deprecated and replaced with i18n. Containers
> will need to support both till some time, like 2.0?

I think backwards-compatibility considerations should be up to
individual implementations. It might be worth discussing briefly in
the spec, but I wouldn't make anything required.

Cheers,
-- Tim

[Jon]

After listening to feedback, I thought I would try a slightly
different approach. I realized that outside of our group we need a way
to refer to our "Gadget" technology. It has to be: "OpenSocial
Gadgets" - the name is out there already and "Google Gadgets" are
fading away. So we can spin this a bit differently, embrace
"OpenSocial" as the name for the entire technology stack, and then
discuss the "Social Application" built on top of the OpenSocial
framework. This allows the use of the namespace "opensocial"
everywhere without any issue, since it is the name for the technology.

I propose that we have a master document "OpenSocial-
Introduction.xml" (a preview is at: http://codereview.appspot.com/148051)
and the other documents will see a few small content changes as well
as some structural changes to better reflect the divisions.

Lane - I think this would be a good place to describe compliance, and
left a placeholder.

[Kevin Brown]

That was the approach that I was in favor of two years ago, so I'm definitely still in favor of it.

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.

To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

[Lane LiaBraaten]

Yep -- I like this top-level doc.  I was thinking we could use OpenSocial-Specification.xml, since once we move the JavaScript out it's basically just the Overview and Compliance section.

-Lane

[Jon]

Below is a list of titles and xml file names. If we want to alter the
titles, content and file names, let me know.

I was planning to add the introduction as a new file, and only
slightly change the OpenSocial-Specification.xml. But I could create a
new file OpenSocial-SocialJavaScript.xml, and replace the contents of
the old OpenSocial-Specification.xml with the introduction. The former
makes svn diffs easier, while the latter might make longer term sense.

I was also planning to go easy on the REST spec, trying to clean it
up. But as you know all the Social data is documented inside that
document. We could pull it out into a document of it's own - Or add it
to the OpenSocial-SocialJavaScript.xml (which maybe we should then
call OpenSocial-SocialApplication.xml). This could be the best option,
but it is also the most extensive change.

OpenSocial Introduction (OpenSocial-Introduction.xml)
Basic intro, TOC to all docs and Compliance
This is the new doc

Gadgets API Specification v1.0 (Gadgets-API-Specification.xml)
The gadgets spec
Simple changes for this

OpenSocial JavaScript Specification v1.0 (OpenSocial-
Specification.xml)
aka: OpenSocial Specification v1.0
This is the original OpenSocial Specification, with a name change
since it is mainly JS documentation
Changes would be to enhance the osapi section with a discussion on
the pattern as a general method for accessing OpenSocial server side
data.

Alternative Proposals: We could completely restructure it with osapi
separate from opensocial.*. Problem is some of opensocial.* is still
needed, even with osapi.
OR
We could remove more non-JS and put it in the introduction.

OpenSocial Data Pipelining Specification v1.0 (OpenSocial-Data-
Pipelining.xml)
Try to be clear on the separation of DataRequest and HttpRequest,
protocols, error handling and data structures from the Social specific
People, etc...

OpenSocial Templating Specification v1.0 (OpenSocial-Templating.xml)
Not much to change here

OpenSocial Markup Language Tags Specification v1.0 (OpenSocial-Markup-
Language-Tags.xml)
Don't think there is much to change here either

OpenSocial RESTful Protocol Specification v1.0 (REST-API.xml)
Similar to pipelining, to discuss the protocol separate from
content, although it may be more difficult.

Radical proposal: Split out the Social data schema. This text is
really should belong in a standalone document that can be referenced
by JS, Pipelining, Templating, RPC and REST. That's a big structural
change, but if people are interested I'm open to it.

OpenSocial RPC Protocol Specification v1.0 (RPC-Protocol.xml)
Similar to pipelining.

[Kevin Brown]

I think we definitely need this. All too often we see questions about how pipelining or REST or osapi should behave, only to spend a lot of time digging through documents because it's not clear where the canonical reference is. I'd strongly prefer that the data schema be a distinct document, and any protocol-specific details be addressed in the JS/REST/RPC/pipelining docs.
 

OpenSocial RPC Protocol Specification v1.0 (RPC-Protocol.xml)
 Similar to pipelining.

[Lane LiaBraaten]

Hi Jon,

I've been thinking about the doc structure this morning, too.  I think we're on the same page here, and I like some of your more radical ideas :)

I keep coming back to how we define compliance.  More than just gadgets vs opensocial, we actually have two axes at play here: core vs social, and client vs server.  This leads us to four components we should identify in the compliance section:

1. Core Gadget Container
   
2. Core API Server
3. Social Gadget Container
4. Social API Server

It's also important to note that in both client and server share a data model, so that will need to be defined as well.

So how does this translate to a doc structure?  Maybe something like this (again, we can alter filenames etc.):

OpenSocial Introduction (OpenSocial-Introduction.xml)
 - Basic intro, TOC to all docs and Compliance

Core Gadget Specification (Gadgets-API-Specification.xml --> Core-Gadget.xml)
 - Rendering, content rewriting, XML schema
 - JS (gadgets.*)
 - Data Pipelining (HttpRequest, DataRequest)
 - Containers MUST implement OpenSocial-Templating.xml

Core API Server Specification (Core-API-Server.xml)
 - XRDS, OAuth
 - REST/RPC request/response
 - Services (caching?, system?)

Core Data Specification (Core-Data.xml)
 - Collections, Views, UserIds, etc.

Social Gadget Specification (Social-Gadget.xml)
 - Additional JS (osapi.*, opensocial.*)
 - Additional Data Pipelining (PeopleRequest, Activity Request)
 - Additional Templating Tags (OSML)

Social API Server Spec (Social-API-Server.xml)
 - Additional services (people, activities, etc)

Social Data Spec (Social-Data.xml)
 - Person, Activity, etc.

Note that the core vs social axis could be extended to include things like commerce.  In which case we'd define three more files:
 1) additional client side stuff: JS and data pipelining tags
 2) additional server side stuff: new services and their methods.
 3) additional data objects shared between client and server side.

What do you think?

-Lane

FWIW - I agree that we need to stick with 'OpenSocial' as the umbrella name for the technology stack for now, but I think defining these 'core' components makes it apparent that we're dealing with something much more general.

On Fri, Nov 6, 2009 at 9:12 AM, Jon <jon.we...@gmail.com> wrote:

[Jon]

After writing the introduction, I realized the same 2 axes for
compliance. I know of companies that want to do only a server, no
gadgets. It makes sense, they want to enable their data into the
network, but don't want to support a gadget container. But does it
make sense to have a "Gadget Container" w/o a server side?

Maybe people would want to do that, it could be easier, but the
issues:

1) Only simple applications could be created. Applications that have a
batch component, or want to do complex server side mashups. Or even
URL gadgets, would be excluded.

2) Part of the standard is to have an "open" network of servers
running similar applications (e.g. all Social, or all eCommerce), that
can interact somehow.

So if an installation wants to do only Container and no server, should
it be considered compliant?

[Kevin Brown]

Assuming that there's a separation here (data vs. gadgets), I absolutely think it makes sense, as long as it's clear to users what subset is available.

One such case where this makes a lot of sense would be on high-end mobile platforms (e.g. iphone, android). There's not a lot of value in gadgets on a mobile device, but the standard data APIs would be very useful.

The opposite is also reasonable -- that's basically what igoogle was before opensocial came around.
 

[Jon]

The document structure follows a nice easy pattern: Core-XXX-Spec ->
Social-XXX-Spec, which is clear.

If we go with the compliance comments from an earlier posting. We
should plan the flow with the Server docs, then Data, then Gadget. And
Core, then Social.

As we split it up the precise content will become clearer.

On Nov 6, 10:54 am, Lane LiaBraaten <lliab...@google.com> wrote:
> Hi Jon,
>
> I've been thinking about the doc structure this morning, too.  I think we're
> on the same page here, and I like some of your more radical ideas :)
>
> I keep coming back to how we define compliance.  More than just gadgets vs
> opensocial, we actually have two axes at play here: core vs social, and
> client vs server.  This leads us to four components we should identify in
> the compliance section:
>

>    1. Core Gadget Container
>    2. Core API Server
>    3. Social Gadget Container
>    4. Social API Server

> > opensocial-and-gadg...@googlegroups.com<opensocial-and-gadgets-spec%2Bunsu...@googlegroups.com>
> > .

[Jon]

> One such case where this makes a lot of sense would be on high-end mobile
> platforms (e.g. iphone, android). There's not a lot of value in gadgets on a
> mobile device, but the standard data APIs would be very useful.

Is this an example of mostly a Server-only implementation?

>
> The opposite is also reasonable -- that's basically what igoogle was before
> opensocial came around.

This would be an example of Cotainer-only, right?

There is a small "out" for implementations that have no server side
data storage. No people, no ecommerce products, etc.. Then they have a
server side that does "almost" nothing. And why I say "almost", there
is some words about a cache invalidation endpoint, which is required
for proxied content, and that could be worded as a MAY. So with no
data, you don't need a server side to be compliant. But once you start
having data you need a server side implementation.

Plus, I'm thinking that isolated installations really don't need to be
labeled as "OpenSocial Compliant". They can still use the spec,
Shindig and everything else, just can't be called compliant.

[Lane LiaBraaten]

On Fri, Nov 6, 2009 at 11:34 AM, Jon <jon.we...@gmail.com> wrote:

> One such case where this makes a lot of sense would be on high-end mobile
> platforms (e.g. iphone, android). There's not a lot of value in gadgets on a
> mobile device, but the standard data APIs would be very useful.

Is this an example of mostly a Server-only implementation?

Right

>
> The opposite is also reasonable -- that's basically what igoogle was before
> opensocial came around.

This would be an example of Cotainer-only, right?

Right

There is a small "out" for implementations that have no server side
data storage. No people, no ecommerce products, etc.. Then they have a
server side that does "almost" nothing. And why I say "almost", there
is some words about a cache invalidation endpoint, which is required
for proxied content, and that could be worded as a MAY.

Yeah - I think that's right.
 

So with no data, you don't need a server side to be compliant.  But once you start

having data you need a server side implementation.

 
I don't think you "need" a server side implementation -  a compliant Social Gadget Container would let you include people/friend data to enhance your gadgets, but you don't necessarily need a server side.  Think of the "social nuts" app we use for the tutorial...no server side necessary.

Regardless, I think it helps to keep the client and server side specs/reqs separate.

 

Plus, I'm thinking that isolated installations really don't need to be
labeled as "OpenSocial Compliant". They can still use the spec,
Shindig and everything else, just can't be called compliant.

They can be compliant as a Gadget Container, or a Social Gadget Container.

-Lane

[goosemanjack]

+1 on splitting the data into an independent spec to be referenced by
others. We've internally been talking about this. I also think this
corresponds to Lane's "Option A" proposal in for re-organizing the
content.

http://wiki.opensocial.org/index.php?title=Reorganize_the_content_in_the_spec

At this stage it's somewhat unclear if the Javascript API extensions
for data pipelining and templating would migrate to the larger
Javascript API doc or remain in their feature area. Also, the Data
Pipelining and Templating specs have some shared items:

(examples of shared/cross-cutting items)
* EL
* os:Var

I see multiple options for handling this scenario:

1. Mixed definition of cross-cutting feature (current setup, but hard
to read).
2. Cross-referencing pointers between specs and item is entirely
defined in one spec or the other
3. Merge DP and Templating spec into one
4. Create a new spec document for cross-cutting features.
--
clc

[Jon]

Take a look at Lane's proposal (later in the thread), pipelining and
templating are part of the "Core Gadget", so we could refactor EL to
its own section.

On Nov 6, 3:44 pm, goosemanjack <cc...@myspace.com> wrote:
> +1 on splitting the data into an independent spec to be referenced by
> others.  We've internally been talking about this.  I also think this
> corresponds to Lane's "Option A" proposal in for re-organizing the
> content.
>

> http://wiki.opensocial.org/index.php?title=Reorganize_the_content_in_...

[Jon]

Sounds like we are all on the same page with this. Because this alters
the document structure, it will conflict with all the outstanding
patches. These patches won't be committed till after the 14th. What
should be done?

I propose that we wait till most of the patches get committed, any
leftover issues could still be worked on and voted on against the
"old" documents. The "new" documents are prepared, voted on and
committed. Then the leftover issues would be redone against the "new"
documents with a quick review and vote.

[Lane LiaBraaten]

There are a lot of changes required here, so I don't want to put it off.  I think we should approach this change as a bunch of smaller patches, and commit them on a first come first serve basis. 

For example, say we have two patches:
1. move data model stuff from REST-API.xml into a new file (Social-Data.xml)
2. change some of the Person fields.

If the owner of 1 gets their patch in first, then 2 can modify the Social-Data.xml file
If the owner of 2 gets their patch in first, then they'll modify the REST-API.xml file (and 1 will move the updated text into Social-Data.xml when they get to their patch.

-Lane

[Jon]

Dividing it up into smaller pieces would be good.

I'm still apprehensive about creating merge conflicts, it's a lot of
extra work for the one who commits second.

Yet another proposal:
80% of the changes are really block moves, creation of new documents,
with some changes in the overview paragraphs, and occasionally needing
to duplicate/split content. We edit the documents in place with some
predefined editing markups: identifying blocks to be moved and their
destination; create the new documents; making changes to the overviews
in place; and some basic file rearrangement. Then most of the patches
that hit the low level details will go in w/o merge conflicts. We
could even take a preliminary vote on the marked up documents, let the
other patches get merged, then do the final document rearrangement per
the markups.

[Evan Gilbert]

+1 on on the approach we're looking at on this thread.

We should probably agree on a top level organization before spending too much work on the details the details - Lane has a fairly complete proposal above with sevens sections:
- OpenSocial Introduction (OpenSocial-Introduction.xml)
- Core Gadget Specification (Gadgets-API-Specification.xml --> Core-Gadget.xml)
- Core API Server Specification (Core-API-Server.xml)
- Core Data Specification (Core-Data.xml)
- Social Gadget Specification (Social-Gadget.xml)
- Social API Server Spec (Social-API-Server.xml)
- Social Data Spec (Social-Data.xml)

I'm +1 on this breakdown but also open for other high-level splitting of the data.

re: Jon's proposal to edit in place. Seems like a good option, also will make it much more accessible for the larger group to review the moves.

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=.

[Lane LiaBraaten]

On Tue, Nov 10, 2009 at 12:51 PM, Evan Gilbert <uid...@google.com> wrote:

+1 on on the approach we're looking at on this thread.

We should probably agree on a top level organization before spending too much work on the details the details - Lane has a fairly complete proposal above with sevens sections:
- OpenSocial Introduction (OpenSocial-Introduction.xml)

I'd like to call this file OpenSocial Specification (OpenSocial-Specification.xml) since it contains the high-level definitions for compliance.

-Lane 

[Jon]

I'm +1 on this organization.

Although we do have the project to deprecate redundant opensocial
APIs: http://codereview.appspot.com/144082/show. That would yield a
7th document. Also OK with that. To be consistent, the name should
probably be "Social Deprecated API Server" (Social-Deprecated-API-
Server.xml). Current title: "OpenSocial Deprecated JavaScript
API" (OpenSocial-Deprecated-JavaScript-API.xml).

On Nov 10, 5:13 pm, Lane LiaBraaten <lliab...@google.com> wrote:
> On Tue, Nov 10, 2009 at 12:51 PM, Evan Gilbert <uid...@google.com> wrote:
> > +1 on on the approach we're looking at on this thread.
>
> > We should probably agree on a top level organization before spending too
> > much work on the details the details - Lane has a fairly complete proposal
> > above with sevens sections:
> > - OpenSocial Introduction (OpenSocial-Introduction.xml)
>
> I'd like to call this file OpenSocial Specification
> (OpenSocial-Specification.xml) since it contains the high-level definitions
> for compliance.
>
> -Lane
>
> > - Core Gadget Specification (Gadgets-API-Specification.xml -->
> > Core-Gadget.xml)
> > - Core API Server Specification (Core-API-Server.xml)
> > - Core Data Specification (Core-Data.xml)
> > - Social Gadget Specification (Social-Gadget.xml)
> > - Social API Server Spec (Social-API-Server.xml)
> > - Social Data Spec (Social-Data.xml)
>
> > I'm +1 on this breakdown but also open for other high-level splitting of
> > the data.
>
> > re: Jon's proposal to edit in place. Seems like a good option, also will
> > make it much more accessible for the larger group to review the moves.
>

> > On Mon, Nov 9, 2009 at 2:24 PM, Jon <jon.weyga...@gmail.com> wrote:
>
> >> Dividing it up into smaller pieces would be good.
>
> >> I'm still apprehensive about creating merge conflicts, it's a lot of
> >> extra work for the one who commits second.
>
> >> Yet another proposal:
> >> 80% of the changes are really block moves, creation of new documents,
> >> with some changes in the overview paragraphs, and occasionally needing
> >> to duplicate/split content. We edit the documents in place with some
> >> predefined editing markups: identifying blocks to be moved and their
> >> destination; create the new documents; making changes to the overviews
> >> in place; and some basic file rearrangement. Then most of the patches
> >> that hit the low level details will go in w/o merge conflicts. We
> >> could even take a preliminary vote on the marked up documents, let the
> >> other patches get merged, then do the final document rearrangement per
> >> the markups.
>
> >> --
>
> >> You received this message because you are subscribed to the Google Groups
> >> "OpenSocial and Gadgets Specification Discussion" group.
> >> To post to this group, send email to
> >> opensocial-an...@googlegroups.com.
> >> To unsubscribe from this group, send email to

> >> opensocial-and-gadg...@googlegroups.com<opensocial-and-gadgets-spec%2Bunsu...@googlegroups.com>
> >> .

> >> For more options, visit this group at
> >>http://groups.google.com/group/opensocial-and-gadgets-spec?hl=.
>
> >  --
> > You received this message because you are subscribed to the Google Groups
> > "OpenSocial and Gadgets Specification Discussion" group.
> > To post to this group, send email to
> > opensocial-an...@googlegroups.com.
> > To unsubscribe from this group, send email to

> > opensocial-and-gadg...@googlegroups.com<opensocial-and-gadgets-spec%2Bunsu...@googlegroups.com>
> > .

[Lane LiaBraaten]

These would actually go in the Social-Gadget.xml file (Social-API-Server is for REST/RPC services).

Instead of introducing a new doc, let's just put them in an appendix of Social-Gadget.xml.  

Sound good?

-Lane

To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

[Lane LiaBraaten]

BTW - I'll go ahead and create these files with some boilerplate so we can start adding stuff when it's appropriate.

-Lane

[Jon]

+1 on both

[Lane LiaBraaten]

FYI - I've updated several proposals in the Spec Changes page [1] to map to this better:

"Add gadgets XML reference to the spec" --> "Create Core-Gadget.xml"

"Condense protocol and data definitions" --> "Create Core-API-Server.xml" and "Create Social-API-Server.xml

"Deprecate redundant opensocial.* methods" --> "Create Social-Gadget.xml"

Any volunteers for creating the Core-Data.xml and Social-Data.xml files?

-Lane

BTW - I'll still create the boilerplate for these files.

[1] http://wiki.opensocial.org/index.php?title=Spec_Changes#Current_Status_At_a_Glance

On Wed, Nov 11, 2009 at 9:40 AM, Jon <jon.we...@gmail.com> wrote:

+1 on both

[Mark W.]

Jon,
I apologize for the delay in posting on this thread. I was tricked
into crossing the event horizon of internal process and planning here
and just now got shot out the back end of the worm hole...

There's one thing that I'd like to make sure we don't get confused on
up front regarding OpenAjax. I don't believe OpenAjax to be a
competitor of OpenSocial. In fact, OpenSocial and OpenAjax are working
together to bring in technology like the OpenAjax Hub into OpenSocial
for the pub/sub work. There are other areas where we can leverage/
learn from the OA community. I'd like to see these two groups come
closer together because I think there's great work in both and
everyone benefits if we can bring them together.

-Mark W.

> > > --
>
> > > You received this message because you are subscribed to the Google Groups
> > > "OpenSocial and Gadgets Specification Discussion" group.
> > > To post to this group, send email to
> > > opensocial-an...@googlegroups.com.
> > > To unsubscribe from this group, send email to

> > > opensocial-and-gadg...@googlegroups.com<opensocial-and-gad gets-spec%2Bunsu...@googlegroups.com>
> > > .

> > > For more options, visit this group at

> > >http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

[Jon]

I was trying to justify the need to have platform separate from
application :-)

BTW - looking forward to the pubsub work.

[Jon]

I'll take a pass at the *-Data.xml files.

On Nov 11, 10:29 am, Lane LiaBraaten <lliab...@google.com> wrote:
> FYI - I've updated several proposals in the Spec Changes page [1] to map to
> this better:
>
> "Add gadgets XML reference to the spec" --> "Create Core-Gadget.xml"
> "Condense protocol and data definitions" --> "Create Core-API-Server.xml"
> and "Create Social-API-Server.xml
> "Deprecate redundant opensocial.* methods" --> "Create Social-Gadget.xml"
>
> Any volunteers for creating the Core-Data.xml and Social-Data.xml files?
>
> -Lane
>
> BTW - I'll still create the boilerplate for these files.
>

> [1]http://wiki.opensocial.org/index.php?title=Spec_Changes#Current_Statu...

>
> On Wed, Nov 11, 2009 at 9:40 AM, Jon <jon.weyga...@gmail.com> wrote:
> > +1 on both
>
> > --
>
> > You received this message because you are subscribed to the Google Groups
> > "OpenSocial and Gadgets Specification Discussion" group.
> > To post to this group, send email to
> > opensocial-an...@googlegroups.com.
> > To unsubscribe from this group, send email to

> > opensocial-and-gadg...@googlegroups.com<opensocial-and-gadgets-spec%2Bunsu...@googlegroups.com>
> > .

[Lane LiaBraaten]

Cool - I've checked in a set of starter files: http://code.google.com/p/opensocial-resources/source/detail?r=1203

Arne and I had started a few files in this direction, so I've removed them and split their contents into the new files as appropriate.  

-Lane

To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

[Jon]

I have obtained these, there also do not appear to be too many
projects affecting this content.

On Nov 11, 5:50 pm, Lane LiaBraaten <lliab...@google.com> wrote:
> Cool - I've checked in a set of starter files:http://code.google.com/p/opensocial-resources/source/detail?r=1203
>
> Arne and I had started a few files in this direction, so I've removed them
> and split their contents into the new files as appropriate.
>
> -Lane
>

> > <opensocial-and-gadgets-spec%2Bunsu...@googlegroups.com<opensocial-and-gadgets-spec%252Buns...@googlegroups.com>

[Jon]

I put up the next iteration for Gadget-Data and Social-Data - it still
needs lots of work, but wanted to get some feedback on the Social-Data
section. It may be best to do a checkout and apply the patch, as
looking at a diff of the xml is close to useless.

First, notice the division of Social data into objects that are
directly addressable (e.g. people, activities) and other data. Some
may have thoughts as to the names, I used "Primary Social Data" and
"Additional Social Data".

Also since the REST and RPC guides may not have all the details for
the Social calls, I filled out the Person section rather completely.
Should we put the REST, RPC and Pipelining info in this document? Or
is it better suited for other documents?

[Lane LiaBraaten]

Looking good, Jon.  I think we only need to define the fields in this doc.  The osapi and pipelining fields will go in the Social-Gadget.xml file, and they'll reference People service definition in the Social-API-Service which will define the Query Keys, RPC, and REST sections.

Thinking out loud...

[Social-Gadget.xml]

JavaScript API Reference

 - osapi.people

   - Description: a JavaScript API for the <eref target="Social-API-Server.xml#People-Service">People Service</eref>.

   - Parameters: a single JavaScript object with properties corresponding to the parameters defined by the <eref target="Social-API-Server.xml#People-Service.get">People Service's get method</eref>.

   - Returns: a <eref target="Social-Data.xml#Person">Person</eref> object or array of <eref target="Social-Data.xml#Person">Person</eref> objects.

<snip>

Data Pipelining Reference

 - <os:PeopleRequest>

   - Description: a declarative API for the <eref target="Social-API-Server.xml#People-Service">People Service</eref>.

   - Attributes: attributes correspond to the parameters defined by the <eref target="Social-API-Server.xml#People-Service.get">People Service's get method</eref>.

   - Returns:  a <eref target="Social-Data.xml#Person">Person</eref> object or array of <eref target="Social-Data.xml#Person">Person</eref> objects.

[Social-API-Server.xml]

People Service

   - get

     - Parameters:

       - userId (<eref target="Core-Data.xml#UserId">UserId</eref>) - the user ID(s) to fetch

       - groupId (<eref target="Social-Data.xml#GroupId">GroupId</eref>) the group to fetch

       - count (int) the maximum number of Person objects to return

       - etc.

     - Returns: a <eref target="Social-Data.xml#Person">Person</eref> object or array of <eref target="Social-Data.xml#Person">Person</eref> objects.

   - create

   - update

   - delete

[Social-Data.xml]

Person

 - Fields

   - id (<eref target="Core-Data.xml#UserId">UserId</eref>) - the person's user ID

   - displayName (string) - the person's name

   - etc

Does this example work?  It should allow us to define things once...Person fields go in the Social-Data file; methods for requesting people (and the request parameters)  go in the Social-API-Service.xml file.  Our client side APIs (i.e. Social-Gadget.xml) can just point to these definitions.  

I was also thinking we may as well drop the "OpenSocial-" prefix on everything (e.g. Person instead of OpenSocial-Person).  Agree?

-Lane

FYI - the code review is at http://codereview.appspot.com/154120/

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.

To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

[Jon]

OK, we'll focus on data.
And drop the "OpenSocial-" since everything is OS

> FYI - the code review is athttp://codereview.appspot.com/154120/

>
> On Fri, Nov 13, 2009 at 12:46 PM, Jon <jon.weyga...@gmail.com> wrote:
> > I put up the next iteration for Gadget-Data and Social-Data - it still
> > needs lots of work, but wanted to get some feedback on the Social-Data
> > section. It may be best to do a checkout and apply the patch, as
> > looking at a diff of the xml is close to useless.
>
> > First, notice the division of Social data into objects that are
> > directly addressable (e.g. people, activities) and other data. Some
> > may have thoughts as to the names, I used "Primary Social Data" and
> > "Additional Social Data".
>
> > Also since the REST and RPC guides may not have all the details for
> > the Social calls, I filled out the Person section rather completely.
> > Should we put the REST, RPC and Pipelining info in this document? Or
> > is it better suited for other documents?
>
> > --
>
> > You received this message because you are subscribed to the Google Groups
> > "OpenSocial and Gadgets Specification Discussion" group.
> > To post to this group, send email to
> > opensocial-an...@googlegroups.com.
> > To unsubscribe from this group, send email to

> > opensocial-and-gadg...@googlegroups.com<opensocial-and-gadgets-spec%2Bunsu...@googlegroups.com>
> > .

[Jon]

I have completed the first draft of the data documents:

- Core Data Specification (Core-Data.xml)

- Social Data Spec (Social-Data.xml)
at: http://codereview.appspot.com/154120

When copying text from other sections, I have tried not to add any
content that might change the specification. E.g. if it was vague as
to what a field did in the original documents, hopefully it is still
vague in these documents. Fixing these would be yet another task, this
is to simply reorganize.