Revise compliance section

[api.ll...@gmail.com]

Reviewers: opensocial-and-gadgets-spec_googlegroups.com,

Message:
This is a pretty simple patch that replaces the existing compliance
section with the text that defines several levels of compliance (Social
Gadget Container, Core Gadget container, social API Server, etc.)

You can preview the new text at
http://www.opensocial.org/Technical-Resources/draft/OpenSocial-Specification.xml#compliance

This proposal lives on the wiki at
http://wiki.opensocial.org/index.php?title=Revise_the_compliance_section

Please vote early and often :)

-Lane



Please review this at http://codereview.appspot.com/156043

Affected files:
M OpenSocial-Specification.xml

[Jon]

Looks good (for compliance) +1

On Nov 17, 9:24 am, api.lliab...@gmail.com wrote:
> Reviewers: opensocial-and-gadgets-spec_googlegroups.com,
>
> Message:
> This is a pretty simple patch that replaces the existing compliance
> section with the text that defines several levels of compliance (Social
> Gadget Container, Core Gadget container, social API Server, etc.)
>

> You can preview the new text athttp://www.opensocial.org/Technical-Resources/draft/OpenSocial-Specif...
>
> This proposal lives on the wiki athttp://wiki.opensocial.org/index.php?title=Revise_the_compliance_section

>
> Please vote early and often :)
>
> -Lane
>

> Please review this athttp://codereview.appspot.com/156043
>
> Affected files:
>    M     OpenSocial-Specification.xml

[Mark W.]

Lane,

A couple of questions....
It's a very small nit, but could we put the "Core" sections up front?

Also, what do we mean by:
"In all cases, a site MUST fulfill the requirements in Extensions
(Section 4)."
If we are extending the spec, then I don't think we want to make
extensions a MUST.

-Mark W.

[Lane LiaBraaten]

Sure - I can change the oordering.

For the extensions thing, the intent is 'if you extend the spec, you must do it this way'.  Things like not adding your own methods to the opensocial namespace.

-Lane

On Nov 23, 2009 8:57 AM, "Mark W." <weit...@us.ibm.com> wrote:


Lane,

A couple of questions....
It's a very small nit, but could we put the "Core" sections up front?

Also, what do we mean by:
"In all cases, a site MUST fulfill the requirements in Extensions
(Section 4)."
If we are extending the spec, then I don't think we want to make
extensions a MUST.

-Mark W.

On Nov 17, 8:09 pm, Jon <jon.weyga...@gmail.com> wrote: > Looks good (for compliance) +1 > > On N...

[Mark W.]

Re, extensions...
Can we say something like...
"If a container chooses to offer extensions that have been accepted as
part of the OpenSocial specification, then it MUST adhere to the
requirements specified in section 4 as well as any requirements
specified in the extension document."

The wording is a bit redundant, but the intent is that you have to do
not only what section 4 tells you, but also what the extension itself
requires.

Does this make sense?
-Mark W.

On Nov 23, 12:01 pm, Lane LiaBraaten <lliab...@google.com> wrote:
> Sure - I can change the oordering.
>
> For the extensions thing, the intent is 'if you extend the spec, you must do
> it this way'.  Things like not adding your own methods to the opensocial
> namespace.
>
> -Lane
>

[Tim Moore]

Why just extensions "that have been accepted as part of the OpenSocial
specification". I think it's fair to dictate that if you're going to
extend OpenSocial at all, it needs to be done within certain
constraints, or else you're not really OpenSocial-compliant.

[Lane LiaBraaten]

Okay, I've reorder the elements so they build upon each other (rather than forward declarations).

I didn't change the wording around extensions.  This text isn't meant to say "If you support an extension, you must fulfill it's requirements"

The intention is "If you support an extension, you must do so in a certain way"  Again, it doesn't matter if the extension is incubating, approved, or just something your container pushed out as a proof of concept.  In all cases there are things you should and shouldn't do.  I'm not sure what all the details are here, but we've started down this path in practice (e.g. prefixing new tags with osx:) and we should document it.

-Lane

--

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.

[Mark W.]

Tim,
I agree... maybe I'm splitting hairs here, and if I am, then I
apologize, but this is what I'm trying to communicate....

If I want to add something to the spec, then I MUST follow the
programming model. The OpenSocial community can't accept something
that breaks this.
There's nothing stopping me from making an extension available,
publishing it, building containers et... I just can't say that it's
part of OpenSocial. When someone tries to figure out what a container
supports, there should not be any confusion.

Re-reading your comment, would it be better to say something like....
"Containers that offer OpenSocial extensions MUST adhere to the

requirements specified in section 4 as well as any requirements
specified in the extension document."

The implication being that if you "roll your own" then you're not
really an OpenSocial Extension and will likely do things your own way
regardless....

Is this better?
-Mark W.

[Mark W.]

Lane,

I was wondering if we could add some more intro text to the compliance
section. I think it might help level set why we did the restructuring
and help people understand what they need to do in order to adopt OS.
I've also added a picture that shows this. It will help with the
extensions section as well.

"The OpenSocial specification consists of a set of documents, each of
which define an encapsulated set of capability. It has been structured
in such a way as to support a wider array of adoption use cases,
effectively allowing implementors to manage their rate and pace of
adoption, while still being able to be compliant with the
specification. For example, it is possible to simply be offer social
APIs via REST, and be considered a compliant OpenSocial Social API
Server. Likewise, some implementors may choose to leverage only the
gadget aspect of specification. In this case, they can be considered
to be a compliant OpenSocial Core Gadget Server. Figure zzz below is
an overview of the different levels of OpenSocial Compliance."

http://wiki.opensocial.org/index.php?title=Image:Os-spec-compliance.jpg

-Mark W.

On Nov 23, 12:01 pm, Lane LiaBraaten <lliab...@google.com> wrote:

> Sure - I can change the oordering.
>
> For the extensions thing, the intent is 'if you extend the spec, you must do
> it this way'.  Things like not adding your own methods to the opensocial
> namespace.
>
> -Lane
>

[Lane LiaBraaten]

Let's look at a concrete example...

Suppose a container wants to return a "numResults" element in their Collection object to specify the number of entries in the response.  That's fine, and they don't even need to write an 'extension document' to do this.  They just can't call this "totalResults" because that element is reserved by the spec.

Another example...Suppose a container want to return the "updatedDate" when isUpdated is true.  They could add this as a child element of <result>, but not as a child element or attribute of <isUpdated>.

So I'm thinking some text like this would end up in the extensions doc...

"Containers are free to add functionality to the API-Server, but they MUST adhere to the XSD provided in [Core-API-Server] and the semantics defined in [Core-Data].  The XSD provides the following extension points:

1) A container MAY return any object in the <entry> tag.

2) A container MAY return additional metadata about collections by defining new child elements of the <results> tag"

And we'd have similar language for the Gadget XML XSD.

-Lane

[Lane LiaBraaten]

I like this text, though I think we can do without the figure.

-Lane

[Mark W.]

I think what we are getting at is the idea of "protocol extensions".
This is the third pattern of how we expect the spec to grow
organically.
Maybe thinking about it this way: If you don't need to add schema
elements, then the additional fields or the gadget feature should work
with the programming model defined in the spec.

Specific to your text above, I'd like to avoid referencing into the
other specs from the overview. Could we say something like....

"Containers are free to add functionality to the API-Server, but they
MUST

adhere to the XSD provided in the specification document(s) to which
their extension applies, e.g. Core-API-Server, Core-Data/"

-Mark W.

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

[Lane LiaBraaten]

FYI - patch updated: http://codereview.appspot.com/156043

On Mon, Dec 7, 2009 at 1:09 PM, Lane LiaBraaten <llia...@google.com> wrote:

On Mon, Dec 7, 2009 at 11:59 AM, Mark W. <weit...@us.ibm.com> wrote:

I think what we are getting at is the idea of "protocol extensions".
This is the third pattern of how we expect the spec to grow
organically.
Maybe thinking about it this way: If you don't need to add schema
elements, then the additional fields or the gadget feature should work
with the programming model defined in the spec.

I don't understand what you're saying here.

 

Specific to your text above, I'd like to avoid referencing into the
other specs from the overview. Could we say something like....

"Containers are free to add functionality to the API-Server, but they
MUST

adhere to the XSD provided in the specification document(s) to which
their extension applies, e.g. Core-API-Server, Core-Data/"

Sure...I was going to say that we could just add prose around each XSD to call out the 'extension points', but it occurs to me that these apply to more than just the XML.

Maybe an Extensions section in each spec file?

-Lane

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

[Lane LiaBraaten]

On Mon, Dec 7, 2009 at 11:59 AM, Mark W. <weit...@us.ibm.com> wrote:

I think what we are getting at is the idea of "protocol extensions".
This is the third pattern of how we expect the spec to grow
organically.
Maybe thinking about it this way: If you don't need to add schema
elements, then the additional fields or the gadget feature should work
with the programming model defined in the spec.

I don't understand what you're saying here.

 

Specific to your text above, I'd like to avoid referencing into the
other specs from the overview. Could we say something like....

"Containers are free to add functionality to the API-Server, but they
MUST

adhere to the XSD provided in the specification document(s) to which
their extension applies, e.g. Core-API-Server, Core-Data/"

Sure...I was going to say that we could just add prose around each XSD to call out the 'extension points', but it occurs to me that these apply to more than just the XML.

Maybe an Extensions section in each spec file?

-Lane

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

[Mark W.]

<<I don't understand what you're saying here.>>

In the OpenSocial Specification patch that I submitted, I talk about
the three different ways that OpenSocial can be extended. This is
where we talked about "Protocol Extensions", which is probably not the
best term, so feel free to come up with something different.

In the first one, you simply add a new gadget feature. You don't have
to add any APIs or leverage any extension point in the schema. Pub/Sub
is probably a good example of this. It will be mostly javascript (new
APIs), but author's might want add some information to the gadget's
xml file as well to help the container and/or tooling out (extensions
to the gadget XML).

The second way is by adding new fields, e.g. I want to add a "shoe
size" to my profile. The way the spec is written, I don't have to
change any schemas (Core-Social-Data) to do this.(Caveat: I have not
seen the new Core-Data or Social-Data XSDs, so this may no longer be
accurate.)

The third case is where we are extending OpenSocial in such a way that
we add new data models and new APIs. There are probably lots of
examples we could think of, but the one we've kicked around before is
micro-payments. In this case, we'll need to add new APIs as well as
extensions to the schema (or some way to add a new schema).

<<Sure...I was going to say that we could just add prose around each
XSD to
call out the 'extension points', but it occurs to me that these apply
to
more than just the XML.
Maybe an Extensions section in each spec file? >>

The more we peel the onion layers back, the more I believe it's
important to have a consistent strategy for extensions across the
complete set of XSDs. We don't want to have xs:any in one, and then
nothing in another, et... Further, I think we need to understand how
we think the spec and schema will change going into 1.1. We know we
have at least pub/sub and activity streams on the plate. I'm hesitant
to just slap some xs:any tags at the end of the schema because that
can lead to issues as well.

Does this help clarify things or am I playing catch in left field with
Moisés Alou?


On Dec 7, 4:09 pm, Lane LiaBraaten <lliab...@google.com> wrote:

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

[Lane LiaBraaten]

Thanks for clarifying...makes sense now.

On Mon, Dec 7, 2009 at 3:07 PM, Mark W. <weit...@us.ibm.com> wrote:

<<I don't understand what you're saying here.>>

In the OpenSocial Specification patch that I submitted, I talk about
the three different ways that OpenSocial can be extended. This is
where we talked about "Protocol Extensions", which is probably not the
best term, so feel free to come up with something different.

In the first one, you simply add a new gadget feature. You don't have
to add any APIs or leverage any extension point in the schema. Pub/Sub
is probably a good example of this. It will be mostly javascript (new
APIs), but author's might want add some information to the gadget's
xml file as well to help the container and/or tooling out (extensions
to the gadget XML).

The second way is by adding new fields, e.g. I want to add a "shoe
size" to my profile. The way the spec is written, I don't have to
change any schemas (Core-Social-Data) to do this.(Caveat: I have not
seen the new Core-Data or Social-Data XSDs, so this may no longer be
accurate.)

I don't think that's accurate.  If a container started returning <shoeSize> tags in the <person> element, it would no longer conform to the XSD since showSize is not in the XSD.  Isn't this why we need to add <xs:anyType> to the person element?

Further, we really need to add text to Core-Data.xml#Person to say how the Person element can an can't be extended.  In this case:

"Containers MAY add fields to the Person object and the fields can be of any type. Containers MUST NOT change the type of any fields defined in this specification."

The existing spec say that new fields must have names that are prefixed by something (e.g. foo.shoeSize).  Unfortunately, it suggests using the container's name, which is not really the best idea.  

Is it possible to lift this prefixing requirement?  It's intended to avoid conflicts, but we have some in the opensocial namespace anyway and it doesn't seem to be a problem.  For example, Activity, Album, Message, Organization all have a 'title' field. 

The third case is where we are extending OpenSocial in such a way that
we add new data models and new APIs. There are probably lots of
examples we could think of, but the one we've kicked around before is
micro-payments. In this case, we'll need to add new APIs as well as
extensions to the schema (or some way to add a new schema).

<<Sure...I was going to say that we could just add prose around each
XSD to
call out the 'extension points', but it occurs to me that these apply
to
more than just the XML.
Maybe an Extensions section in each spec file? >>

The more we peel the onion layers back, the more I believe it's
important to have a consistent strategy for extensions across the
complete set of XSDs. We don't want to have xs:any in one, and then
nothing in another, et...

Big +1 here.  If people are using XSD validators on gadgets and XML responses,  then I think we need to make the XSDs include the <xs:anyType> tags so that the XML will validate as long as the container only adds stuff in specific extension points.

If the XSD is not being used in that way I would love to just drop it.  It's a time sink and there are better ways to express the data model in a way humans can understand.

-Lane

 

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

[Tim Moore]

On Dec 7, 10:19 am, "Mark W." <weitz...@us.ibm.com> wrote:
> Tim,
> I agree... maybe I'm splitting hairs here, and if I am, then I
> apologize, but this is what I'm trying to communicate....
>
> If I want to add something to the spec, then I MUST follow the
> programming model. The OpenSocial community can't accept something
> that breaks this.
> There's nothing stopping me from making an extension available,
> publishing it, building containers et... I just can't say that it's
> part of OpenSocial. When someone tries to figure out what a container
> supports, there should not be any confusion.

Makes sense. What I was suggesting was a little bit stronger: not only
is an extension unacceptable as an official OpenSocial extension if it
violates the extension rules, but any container incorporating
extensions that violate the extension rules cannot claim to be a
compliant OpenSocial implementation.

>
> Re-reading your comment, would it be better to say something like....
> "Containers that offer OpenSocial extensions MUST adhere to the
> requirements specified in section 4 as well as any requirements
> specified in the extension document."

That sounds good.

-- Tim

[Mark W.]

Tim,
+1. I'll try to work some wording like this into the extension
section.

[Mark W.]

<mdw>comments in line....</mdw>

On Dec 7, 9:06 pm, Lane LiaBraaten <lliab...@google.com> wrote:
> Thanks for clarifying...makes sense now.
>

> On Mon, Dec 7, 2009 at 3:07 PM, Mark W. <weitz...@us.ibm.com> wrote:
> > <<I don't understand what you're saying here.>>
> > In the OpenSocial Specification patch that I submitted, I talk about
> > the three different ways that OpenSocial can be extended. This is
> > where we talked about "Protocol Extensions", which is probably not the
> > best term, so feel free to come up with something different.
>
> > In the first one, you simply add a new gadget feature. You don't have
> > to add any APIs or leverage any extension point in the schema. Pub/Sub
> > is probably a good example of this. It will be mostly javascript (new
> > APIs), but author's might want add some information to the gadget's
> > xml file as well to help the container and/or tooling out (extensions
> > to the gadget XML).
> > The second way is by adding new fields, e.g. I want to add a "shoe
> > size" to my profile. The way the spec is written, I don't have to
> > change any schemas (Core-Social-Data) to do this.(Caveat: I have not
> > seen the new Core-Data or Social-Data XSDs, so this may no longer be
> > accurate.)


> I don't think that's accurate.  If a container started returning <shoeSize>
> tags in the <person> element, it would no longer conform to the XSD since
> showSize is not in the XSD.  Isn't this why we need to add <xs:anyType> to
> the person element?

<mdw>
I agree that this would not pass schema validation. However, this
scenario does work in JSON or if you choose not to not schema validate
the XML response. I'd like to also make sure we have a consistent
strategy across XML, JSON and ATOM.
</mdw>

> Further, we really need to add text to Core-Data.xml#Person to say how the
> Person element can an can't be extended.  In this case:
>
> "Containers MAY add fields to the Person object and the fields can be of any
> type. Containers MUST NOT change the type of any fields defined in this
> specification."

<mdw>+1. I'll add text to the overall extensions section that says
that Containers MUST NOT change the type of any fields defined in
approved OpenSocial specifications. Containers MAY extend the
specifications by adding fields leveraging the defined extensions
points in the XML schema.

Do we want to add something on JSON and ATOM?
</mdw>

> The existing spec say that new fields must have names that are prefixed by
> something (e.g. foo.shoeSize).  Unfortunately, it suggests using the
> container's name, which is not really the best idea.
>
> Is it possible to lift this prefixing requirement?  It's intended to avoid
> conflicts, but we have some in the opensocial namespace anyway and it
> doesn't seem to be a problem.  For example, Activity, Album, Message,
> Organization all have a 'title' field.
>

<mdw>
Do we know why this isn't a problem? Is it because nobody is doing
schema validation on response items?
</mdw>

>
> > The third case is where we are extending OpenSocial in such a way that
> > we add new data models and new APIs. There are probably lots of
> > examples we could think of, but the one we've kicked around before is
> > micro-payments. In this case, we'll need to add new APIs as well as
> > extensions to the schema (or some way to add a new schema).
>
> > <<Sure...I was going to say that we could just add prose around each
> > XSD to
> > call out the 'extension points', but it occurs to me that these apply
> > to
> > more than just the XML.
> > Maybe an Extensions section in each spec file? >>
>
> > The more we peel the onion layers back, the more I believe it's
> > important to have a consistent strategy for extensions across the
> > complete set of XSDs. We don't want to have xs:any in one, and then
> > nothing in another, et...
>
> Big +1 here.  If people are using XSD validators on gadgets and XML
> responses,  then I think we need to make the XSDs include the <xs:anyType>
> tags so that the XML will validate as long as the container only adds stuff
> in specific extension points.
>
> If the XSD is not being used in that way I would love to just drop it.  It's
> a time sink and there are better ways to express the data model in a way
> humans can understand.

<mdw>
+1 on both your points. I think this gets to the base of my concerns.
IF we use schema validation, then I'd like to make sure we do the
extensions right.
</mdw>

> ...
>
> read more »

[Lane LiaBraaten]

fyi - I've checked in the new text around compliance.

@Mark - I should be out of your way for the changes you're making to the extensions section.

-Lane