Please review this XSD for Core-API-Server

[Lane LiaBraaten]

With the split of Core and Social API server, we need a XSD that applies to just the core server.  I've taken a stab at one, but need some more eyes on it.

The English version:

A Core API Server will always return a <response> element, which will have one of three things in it:

1) an <entry> element, which could contain anything

2) a collection, which has a group of elements like <startIndex> and <isSorted>, followed by a number of <entry> elements for the items in the collection (or no <entry> elements if the collection is empty)

3) a <invalidationKeys> element, which contains at least one <invalidationKey> element.

If the English version sounds right, then does this XSD accurately reflect that?

Thanks,

Lane

<?xml version="1.0" encoding="utf-8"?>

<xs:schema xmlns:tns="http://ns.opensocial.org/2008/opensocial"

  elementFormDefault="qualified"

  targetNamespace="http://ns.opensocial.org/2008/opensocial"

  xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="response">

    <xs:complexType>

      <xs:choice>      

        <xs:element name="entry" type="xs:anyType" />

        <xs:group ref="collection" />

        <xs:element name="invalidationKeys" type="tns:InvalidationKeys" />

      </xs:choice>

    </xs:complexType>

  </xs:element>    

  <xs:group>        

    <xs:complexType>

      <xs:sequence>

        <xs:complexType>

          <xs:all>

            <xs:element name="itemsPerPage" type="xs:int" />

            <xs:element name="startIndex" type="xs:long" />

            <xs:element name="totalResults" type="xs:long" />

            <xs:element name="isFiltered" type="xs:boolean" />

            <xs:element name="isSorted" type="xs:boolean" />

            <xs:element name="isUpdatedSince" type="xs:boolean" />

          </xs:all>

        </xs:complexType> 

        <xs:element name="entry" type="xs:anyType" minOccurs=0 maxOccurs="unbounded" />

      </xs:sequence>

    </xs:complexType>

  </xs:group>        

  <xs:complexType name="InvalidationKeys">

    <xs:all>

      <xs:element name="invalidationKey" type="xs:string" maxOccurs="unbounded" />

    </xs:all>

  </xs:complexType>

</xs:schema>

[Mark W.]

A couple of quick questions....

In the case of option 1, the any type:
My concern around having something wide open is interop and
portability. If I can essentially throw anything in there, I'm
expecting something, somewhere outside of the specification to be able
to consume it and understand the semantics. What are the use cases
supporting this? Do we really want to introduce a vanilla "envelope"?
It may be necessary, especially in the case of extensions, where you
have to pass something else along with the result. But should this be
an any? Regardless, we should have language that says what gets passed
should be part of an incubating/approved extension with a publicly
available definition of semantics etc....

In the case of option 2, the collection...
Are we sure these are the complete set of metadata about the response
that would come back? Similar situation as above... What if I'd like
to add a "willExpireOn" field? This could be optional, and for clients
that understand it, they can choose to use leverage it, for others,
it's safe to ignore. To do this now, I'm forced into using Option1,
and then somehow telling everyone that "hey, this is really option 2
but ignore the extra fields if you want..."

So recognizing that XML schema can be a pain, I'm not one for trying
to over engineer anything.... That said, if we think the concerns
above are valid, perhaps we can think of some way to address them.

-Mark W.

[Jon]

I think it looks good, but I agree with Mark. Everything in the xs:all
is optional anyway, so could we put an xs:any in there? Seems like a
good point for extensions.

Jon

[Lane LiaBraaten]

Thanks for the review guys.  Comments inline...

On Fri, Dec 4, 2009 at 8:39 AM, Jon <jon.we...@gmail.com> wrote:

I think it looks good, but I agree with Mark. Everything in the xs:all
is optional anyway, so could we put an xs:any in there? Seems like a
good point for extensions.

I'm guessing you're referring to the xs:all in the 'collection' group (which I forgot to name in the <group> tag).  I agree we should add a xs:any there, but it will need a minOccurs=0, since everything in he xs:all is _required_  (i.e. the default for minOccurs and maxOccurs is 1)

Jon

On Dec 4, 6:14 am, "Mark W." <weitz...@us.ibm.com> wrote:
> A couple of quick questions....
>
> In the case of option 1, the any type:
> My concern around having something wide open is interop and
> portability. If I can essentially throw anything in there, I'm
> expecting something, somewhere outside of the specification to be able
> to consume it and understand the semantics. What are the use cases
> supporting this? Do we really want to introduce a vanilla "envelope"?
> It may be necessary, especially in the case of extensions, where you
> have to pass something else along with the result. But should this be
> an any? Regardless, we should have language that says what gets passed
> should be part of an incubating/approved extension with a publicly
> available definition of semantics etc....

We need to allow containers to return their own custom responses, regardless of incubating/accepted status. Clients should ignore what they don't recognize, rather than causing a XML-parsing error because the XSD is too strict.

All we can define in the XSD are the things that are laid out in the spec. For example, if you return a collection, it better be a <response> element, with some specific children and a list of <entry> elements.  We can't define what is or isn't allowed in the <entry> elements.

 

>
> In the case of option 2, the collection...
> Are we sure these are the complete set of metadata about the response
> that would come back? Similar situation as above... What if I'd like
> to add a "willExpireOn" field? This could be optional, and for clients
> that understand it, they can choose to use leverage it, for others,
> it's safe to ignore. To do this now, I'm forced into using Option1,
> and then somehow telling everyone that "hey, this is really option 2
> but ignore the extra fields if you want..."

+1 good point. 

--

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.