Re: Clarify Separation of Gadgets (Data Sections) (issue154120)

[llia...@google.com]

One last thing....

Can you move the two remaining sections of the "Background" section out
of the main OpenSocial-Specification and into the Social-Data section?
Then you can delete the background section entirely (yay!)

Thanks,
Lane


http://codereview.appspot.com/154120/diff/3013/2007
File draft/Social-Data.xml (right):

http://codereview.appspot.com/154120/diff/3013/2007#newcode248
draft/Social-Data.xml:248: <section title="AppData" anchor="AppData">
Move the text from the Background > Key Concepts > Persistence section
of the main OpenSocial spec to this section.

(http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/OpenSocial-Specification.html#rfc.section.4.1.5)

http://codereview.appspot.com/154120/diff/3013/2007#newcode321
draft/Social-Data.xml:321: <section title="Person"
Move the text from the Background > Key Concepts > People section of the
main OpenSocial spec to this section

(http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/OpenSocial-Specification.html#rfc.section.4.1.1)

http://codereview.appspot.com/154120

[jon.we...@gmail.com]

Moved the background info over to the Social-Data spec

http://codereview.appspot.com/154120

[jon.we...@gmail.com]

http://codereview.appspot.com/154120/diff/4001/3018
File draft/Social-Data.xml (right):

http://codereview.appspot.com/154120/diff/4001/3018#newcode424
draft/Social-Data.xml:424: value. This identifier MUST uniquely identify
the user in a
I choose "unique for the container" for this version. Discussion at:
http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/451fed78b86304f8#

http://codereview.appspot.com/154120

[Lane LiaBraaten]

+1 - thanks!

[Mark W.]

Jon,
Your text reads...
The user ID must only contain alphanumeric (A-Za-z0-9) characters,
underscore(_), dot(.) or dash(-). This standardization is intended to
allow for prefixing IDs with a domain name and separator to create
globally unique IDs (e.g. "orkut.com:34KJDCSKJN2HHF0DW20394").

The example you've provided contains a colon ":". Based on the text
above, this does not appear to be one of the valid characters. I can't
think of a reason that it should not be allowed, but if you don't want
it, we should change the example.

-Mark W.

On Nov 23, 6:25 pm, jon.weyga...@gmail.com wrote:
> http://codereview.appspot.com/154120/diff/4001/3018
> File draft/Social-Data.xml (right):
>
> http://codereview.appspot.com/154120/diff/4001/3018#newcode424
> draft/Social-Data.xml:424: value. This identifier MUST uniquely identify
> the user in a

> I choose "unique for the container" for this version. Discussion at:http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thr...
>
> http://codereview.appspot.com/154120

[Jon]

Interesting isn't it? Take a look at the original source:
http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/OpenSocial-Specification.html#rfc.section.4.1.1.1

If I had to guess what the original intent was: it is that containers
cannot use ":", but one day there may be some domain name prefixing
for a more truly globally unique name. Maybe one of the original
authors is around?

Options:
1) Drop the confusing sentence.
2) Clarify it, assuming we can come to some consensus about what it
means.

[Arne Roomann-Kurrik]

I believe the original intent was to reserve ":" as a separator between a site identifier and a user identifier, for the purposes of making a guid for developers to store in a database.

For this reason, user identifiers and possibly site identifiers should not contain ":", although myspace both returns and accepts "myspace.com:XXXXXXXX" style IDs, which I believe still fits in the spirit of this rule.  

We could probably just clarify the purpose of ":" and clean up the wording if people are in consensus.

~Arne

[Mark W.]

+1 on Arne's suggestion of cleanup and wording.

On Nov 23, 10:26 pm, Arne Roomann-Kurrik <api.kur...@google.com>
wrote:

[Lane LiaBraaten]

+1

On Nov 24, 2009 6:09 AM, "Mark W." <weit...@us.ibm.com> wrote:

+1 on Arne's suggestion of cleanup and wording.

On Nov 23, 10:26 pm, Arne Roomann-Kurrik <api.kur...@google.com>
wrote:

> I believe the original intent was to reserve ":" as a separator between a > site identifier and a ...

[jon.we...@gmail.com]

Removed "OpenSocial-" from Core-Data, create new types and revised
references to "id"s

http://codereview.appspot.com/154120

[jon.we...@gmail.com]

Since the concept of "id"s are used many places I went ahead and
formalized the notion of Local-Id and Global-Id and made the appropriate
changes. I made Global-Id optional, but if a container chooses to
support it, it should be supported in all APIs, including JavaScript,
since one day we may have pubsub.


http://codereview.appspot.com/154120/diff/3021/3023
File draft/Core-Data.xml (right):

http://codereview.appspot.com/154120/diff/3021/3023#newcode49
draft/Core-Data.xml:49: described in <xref
target="RFC2234">RFC2234</xref> (Augmented Backus-Naur
This typo is common across our documents, Lane could you fix these in
the ones you are editing?

http://codereview.appspot.com/154120/diff/3021/3023#newcode166
draft/Core-Data.xml:166: Domain-Name = *( ALPHA / DIGIT / "_" / "." /
"-" )
We could attempt to reference the RFC for domain names, but I understand
they are starting to allow international characters for them, so I'm not
sure how that would work out here. For now I have kept to what I think
the original intent was.

http://codereview.appspot.com/154120

[Lane LiaBraaten]

So userId, activityId, etc. are all "Object-Id" (defined as Local-Id / Global-Id) - sounds good to me.

I'll fix those ABNF typos...nice catch.

-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.

[llia...@google.com]

Can you add Album to the Social-Data.xml file?

On 2009/11/24 17:31:49, Lane LiaBraaten wrote:
> So userId, activityId, etc. are all "Object-Id" (defined as Local-Id /
> Global-Id) - sounds good to me.

> I'll fix those ABNF typos...nice catch.

> -Lane

> On Tue, Nov 24, 2009 at 9:16 AM, <mailto:jon.we...@gmail.com>

> > mailto:opensocial-an...@googlegroups.com.

> > To unsubscribe from this group, send email to
> >

mailto: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=en.
> >
> >
> >

http://codereview.appspot.com/154120

[jon.we...@gmail.com]

Merged appropriate changes from 152119 into this patch.

http://codereview.appspot.com/154120

[jon.we...@gmail.com]

On 2009/11/24 17:31:49, Lane LiaBraaten wrote:
> So userId, activityId, etc. are all "Object-Id" (defined as Local-Id /
> Global-Id) - sounds good to me.

I hope so! it sounds reasonable from reading various descriptions of the
fields.

http://codereview.appspot.com/154120

[jon.we...@gmail.com]

Added Album.

http://codereview.appspot.com/154120

[llia...@google.com]

On 2009/11/24 18:28:41, Jon Weygandt wrote:
> Added Album.

Whoops...look like there are a few more. Can you also add:

Body-Type
Email (n.b. the emails field on Person should be updated from
"Plural-Field <string>")
Phone (the Person.phoneNumbers field should be updated from Plural-Field
<string>)
Response (e.g.
https://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal?pli=1#response-procedure-return)
Url - with fields for link text, type (e.g. blog, profile, etc), etc.

Thanks,
Lane


http://codereview.appspot.com/154120

[Jon]

I thought about these a bit, but the current spec is somewhat
ambiguous in areas, I didn't want to make it more restrictive and have
conflicts with existing implementations. But if the community likes I
can go ahead and try to add more specifics, the proposal (and a
question):

HTML-Body-Type - something like: "Bodies may only have the following
HTML tags: <b> <i>, <a>, <span> ..."

Email - simply reference rfc2822

Phone - should we do anything other than a string? Quick Google search
leads to things like E.164 and maybe more standards, out of my area of
expertise.

Response - didn't follow your comment?

For URL - some seem to have restrictions, some don't, so introduce 2
concepts

HTTP-URL - absolute http or https URL per rfc3986 (apply to things
that our server is likely to try to dereference)

Relative-HTTP-URL - don't know if we have any, but if we do, I'll
introduce this concept

URI - anything per rfc3986 (apply to all others) (notice I took the
liberty of using URI vs. URL)

I'll also try to fill in Message data types

On Nov 24, 6:22 pm, lliab...@google.com wrote:
> On 2009/11/24 18:28:41, Jon Weygandt wrote:
>
> > Added Album.
>
> Whoops...look like there are a few more.  Can you also add:
>
> Body-Type
> Email (n.b.  the emails field on Person should be updated from
> "Plural-Field <string>")
> Phone (the Person.phoneNumbers field should be updated from Plural-Field
> <string>)

> Response (e.g.https://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal?pl...)

[Lane LiaBraaten]

These fields are really more related to profile fields on a person.  For example, BodyType refers to fat/skinny, eye color, not HTML docs. 

(http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/OpenSocial-Specification.html#opensocial.BodyType)

Email only has "address" and "type" field, which is redundant to the Plural-Field object, so it's probably okay to leave as Plural-Field<String>

same is almost true for URL, except that it has a "LINK_TEXT" field which we need to keep.  The type can be dropped since it is redundant to the Plural-Field's type property.  So you can say that the "address" property follows rfc3986, but the Person.Urls fields is of type Plural-Field<Url>, where Url has 'address' and 'linkText" properties.

For the responseItem...it should be defined as the response object that REST/RPC calls return.   e.g. The RPC version contains and id property and either a 'data', or 'error' property.  

-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.

[Jon]

As to BodyType - I see now, there are a lot of enums which I had
handled as "one of: xxx, yyy..." in the description field. We could
pull these out and make special types for them.

I'm still a bit lost on responseItem, shouldn't that be part of the
REST/RPC specifications?

OK for others.

On Nov 25, 9:15 am, Lane LiaBraaten <lliab...@google.com> wrote:
> These fields are really more related to profile fields on a person.  For
> example, BodyType refers to fat/skinny, eye color, not HTML docs.

> (http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/Ope...
> )

>
> Email only has "address" and "type" field, which is redundant to the
> Plural-Field object, so it's probably okay to leave as Plural-Field<String>
>
> same is almost true for URL, except that it has a "LINK_TEXT" field which we
> need to keep.  The type can be dropped since it is redundant to the
> Plural-Field's type property.  So you can say that the "address" property
> follows rfc3986, but the Person.Urls fields is of type Plural-Field<Url>,
> where Url has 'address' and 'linkText" properties.
>
> For the responseItem...it should be defined as the response object that
> REST/RPC calls return.   e.g. The RPC version contains and id property and
> either a 'data', or 'error' property.
>
> -Lane
>

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

[Lane LiaBraaten]

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

As to BodyType - I see now, there are a lot of enums which I had
handled as "one of: xxx, yyy..." in the description field. We could
pull these out and make special types for them.

Yes...we need to do that.  BodyType is currently shown as type String, but it's really a type of it's own with properties like eyeColor, height, weight, etc (which are all type string).

 

I'm still a bit lost on responseItem, shouldn't that be part of the
REST/RPC specifications?

It could go in either.  I just figure since it's an object with known properties it would fit in the Core-Data spec, but I don't feel to strongly.  The inconsistency between the REST and RPC response is enough to convince me to leave it alone for now. 

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

[Jon]

I'll try to get a revised version of this after the holidays.

Jon

On Nov 25, 9:50 am, Lane LiaBraaten <lliab...@google.com> wrote:

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

[Jacky.C...@gmail.com]

Wow! Thanks for the TREMENDOUS efforts on composing this!!!

2 thoughts:

1) Would it be possible to move the REST-API.xml#XML_format_XSD into
Social-Data.xml as well? It looks binding tighter with the data
structure, rather than RESTful protocol.

2) Shall we remove the data part from REST-API.xml, after this patch is
stable?

Thanks,
- Jacky


http://codereview.appspot.com/154120/diff/4016/3034
File draft/Core-Data.xml (right):

http://codereview.appspot.com/154120/diff/4016/3034#newcode130
draft/Core-Data.xml:130: always returned in the "list" field of the
result. Lists can either be the
in the "entry" field?

http://codereview.appspot.com/154120/diff/4016/3034#newcode134
draft/Core-Data.xml:134: returned. The paging mechanisms described here
are based on the OpenSearch
OpenSearch:<xref target="OpenSearch" />

<reference anchor='OpenSearch'

target='http://www.opensearch.org/Specifications/OpenSearch/1.1'>
<front>
<title>OpenSearch 1.1, Draft 4</title>
<author initials='D.'
surname='Clinton'
fullname='DeWitt Clinton'>
<organization>OpenSearch.org</organization>
</author>
</front>
</reference>

http://codereview.appspot.com/154120/diff/4016/3034#newcode139
draft/Core-Data.xml:139: "result : {"
Considering strip out the "result" part? IMHO, "collection" is a
concept that contains a list of objects; and {result:collection} is the
response of a request, which could be described in the REST-API.xml and
RPC-protocol.xml.
Therefore it might be easy for readers that the APIs are categorized
into 2 types:
1. return collection: {result: collection}
2. return single object: {result: object}
The above 2 types will be covered in REST-API.xml

http://codereview.appspot.com/154120/diff/4016/3034#newcode288
draft/Core-Data.xml:288: <section title="Rules for mapping JSON to XML"
Moving the samples mapping from application/json representation to XML
representation and application/atom+xml representation in
"REST-API.xml#dataRepresentations" to here?

http://codereview.appspot.com/154120/diff/4016/3033
File draft/Social-Data.xml (right):

http://codereview.appspot.com/154120/diff/4016/3033#newcode11
draft/Social-Data.xml:11: <title>OpenSocial Data Specification
(draft)</title>
"OpenSocial Social Data Spec" - counterpart towards "OpenSocial Core
Data Spec" for Core-Data.xml

http://codereview.appspot.com/154120/diff/4016/3033#newcode376
draft/Social-Data.xml:376: <ttcol align="left">Description</ttcol>
sort the attributes? :)

http://codereview.appspot.com/154120/diff/4016/3033#newcode376
draft/Social-Data.xml:376: <ttcol align="left">Description</ttcol>
currentLocation:
The field currentLocation is deprecated in 1.0 in favor of the standard
location field, but is included for backwards compatibility.
currentLocation will be fully removed in a future version of the spec.

http://codereview.appspot.com/154120/diff/4016/3033#newcode376
draft/Social-Data.xml:376: <ttcol align="left">Description</ttcol>
hasApp:
Boolean value indicating whether the user has application installed.

http://codereview.appspot.com/154120/diff/4016/3033#newcode549
draft/Social-Data.xml:549: <c>location</c>
see currentLocation field.

http://codereview.appspot.com/154120/diff/4016/3033#newcode683
draft/Social-Data.xml:683: non-empty value for either username or
userId, and MAY contain both, in
userId -> userid

http://codereview.appspot.com/154120/diff/4016/3033#newcode703
draft/Social-Data.xml:703: <c>userId</c>
userId -> userid

http://codereview.appspot.com/154120/diff/4016/3033#newcode748
draft/Social-Data.xml:748: <c>type</c>
remove "type" since it has been defined in Core-Data.xml.

http://codereview.appspot.com/154120/diff/4016/3033#newcode944
draft/Social-Data.xml:944: <c>The salary the person receieves from the
organization</c>
organization "." :)

http://codereview.appspot.com/154120/diff/4016/3033#newcode955
draft/Social-Data.xml:955: <c>type</c>
remove "type" since it has been defined in Core-Data.xml.

http://codereview.appspot.com/154120

[llia...@google.com]

@Jacky - note that the current REST and RPC specs will be migrated into
Core-API-Server and Social-API-Server. The former describes the
protocols and the latter describes the services related to social data
(e.g. people, activities, etc).

Where the XSD goes is still a good question. It's related to the server
response/requests, but it also defines the XML representation of our
data objects.

Do you think it's possible to break the XSD into smaller parts that just
define things like:
* a request/response
* a person
* an activity
* etc.

These would be easier to place among the docs. I.e. the request/resonse
XSD goes in the Core-API-Server, the XSD for objects goes in the
Social-Data spec where the object is defined.

http://codereview.appspot.com/154120/diff/4016/3034
File draft/Core-Data.xml (right):

http://codereview.appspot.com/154120/diff/4016/3034#newcode139
draft/Core-Data.xml:139: "result : {"

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:
> Considering strip out the "result" part? IMHO, "collection" is a
concept that
> contains a list of objects; and {result:collection} is the response of
a
> request, which could be described in the REST-API.xml and
RPC-protocol.xml.
> Therefore it might be easy for readers that the APIs are categorized
into 2
> types:
> 1. return collection: {result: collection}
> 2. return single object: {result: object}
> The above 2 types will be covered in REST-API.xml

+1 - though this will be covered in the Core-API-Server.xml doc, not
REST-API.xml

http://codereview.appspot.com/154120/diff/4016/3033
File draft/Social-Data.xml (right):

http://codereview.appspot.com/154120/diff/4016/3033#newcode683
draft/Social-Data.xml:683: non-empty value for either username or
userId, and MAY contain both, in

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:
> userId -> userid

I thought we explicitly changed to camelcase userId. Why do you suggest
all lowercase userid?

http://codereview.appspot.com/154120