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

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

Hi Jon and Lane,

How's the progress? I'll try to split the xml schema part out and put
them into these 2 files.

Thanks,
Jacky


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
According to the document here:
http://spreadsheets.google.com/ccc?key=rUzMVUM2azeJAW3EouN1dCQ

Both PHP Shindig and Java one is using "userid", and both Poco and
OpenSocial spec will use "userid".

However, personally I'm fine to use userId instead - please let me know
about the decision, thus I could ping Joseph Smarr to modify Poco's
definition, and I'll modify Shindig implementation as well.

On 2009/12/01 16:50:45, Lane LiaBraaten wrote:
> 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

[shachar shaty]

i dont understand what this email is about ? i sent a different question.

--

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.

[Lane LiaBraaten]

On Mon, Dec 7, 2009 at 12:45 AM, <Jacky.C...@gmail.com> wrote:

Hi Jon and Lane,

How's the progress?  I'll try to split the xml schema part out and put
them into these 2 files.

Please review the XSD I've drafted for the Core-API-Server.xml.  The thread is here:

https://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/855b262ef4475720

Thanks,

Lane

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

The following shall be included in the next patch set.


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

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:

> in the "entry" field?

OK

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
OK, and added reference

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

http://codereview.appspot.com/154120/diff/4016/3034#newcode288
draft/Core-Data.xml:288: <section title="Rules for mapping JSON to XML"

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:

> Moving the samples mapping from application/json representation to XML
> representation and application/atom+xml representation in
> "REST-API.xml#dataRepresentations" to here?
Not done yet.

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>

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:

> "OpenSocial Social Data Spec" - counterpart towards "OpenSocial Core
Data Spec"
> for Core-Data.xml

OK

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

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:

> sort the attributes? :)

Done for all types.

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

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:

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

Ok

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

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:

> hasApp:
> Boolean value indicating whether the user has application installed.

Since this table has the types, I have typically left out the phrase
"Boolean value" for all the descriptions.

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

I went ahead and did the lower case, since that is the way it is in the
current documents. If we need to go back, let me know.

http://codereview.appspot.com/154120/diff/4016/3033#newcode748
draft/Social-Data.xml:748: <c>type</c>

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:

> remove "type" since it has been defined in Core-Data.xml.

OK, and done on other typically plural field types.

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

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:

> organization "." :)

OK

http://codereview.appspot.com/154120/diff/4016/3033#newcode955
draft/Social-Data.xml:955: <c>type</c>

On 2009/12/01 10:37:35, Jacky.Chao.Wang wrote:

> remove "type" since it has been defined in Core-Data.xml.

OK

http://codereview.appspot.com/154120

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

Changes due to comments from #8, also rebased to latest version

http://codereview.appspot.com/154120

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

Notes for patchset 9:

All the changes in patchset 8 have been checked into svn. Patchset 9 is
simply the delta from 8 to 9.

http://codereview.appspot.com/154120

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

On 2009/11/24 18:27:48, Jon Weygandt wrote:
> 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.

We still need to define some special cases:

User-ID = "@me" / Object-ID
Group-ID = "@self" / "@friends" / "@all" / Object-ID
Message-Collection-ID = "@inbox" / "@outbox" / Object-ID

In each section we should describe what each of he special values means.


http://codereview.appspot.com/154120

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

On 2009/12/09 22:19:00, Lane wrote:
> On 2009/11/24 18:27:48, Jon Weygandt wrote:
> > 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.

> We still need to define some special cases:

> User-ID = "@me" / Object-ID
> Group-ID = "@self" / "@friends" / "@all" / Object-ID

Oops...we already have Group-ID

We need to standardize on -ID or -Id. I don't feel strongly for either,
but right now we have Object-Id and Group-ID.

We should also define Array in Core-Data. We have a Collection object
for responses rom the container, but there are lots of places where
request accept lists of IDs or Objects. Having one place where we way
what an Array is and how it maps between JSON, Atom, and XML would be
good.

-Lane

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

On 2009/12/09 18:00:17, Jon Weygandt wrote:
> Notes for patchset 9:

> All the changes in patchset 8 have been checked into svn. Patchset 9
is simply
> the delta from 8 to 9.

Thanks for your great job, Jon!

The whole doc looks nice to me. Just 2 things: a) JSON->XML->Atom; b)
put split XML schemas into Social-Data.xml. I will probably work on
item #b, however since I'm not quite familiar with XML, it may take some
time + make some bugs....

Thanks!
- Jacky

http://codereview.appspot.com/154120

[Jon]

1) Will do Lane's comments, will attempt to standardize on "Id" as the
spelling

2) I'll take a pass at the JSON->XML->ATOM

Jon

[Lane LiaBraaten]

On Thu, Dec 10, 2009 at 8:27 AM, Jon <jon.we...@gmail.com> wrote:

1) Will do Lane's comments, will attempt to standardize on "Id" as the
spelling

Cool - a couple more suggestions while you're at it:

Core-Data.xml

 App-Id = "@app" / Object-Id

 String (Not sure if this is necessary.  Are there any special characters that aren't allowed?  Anything we should say about escaping?)

Social-Data.xml

 escapeType = "htmlEscape" / "none" (used for specifying if appdata values should be escaped or not (htmlEscape is the default)

 Message-Collection-Id = "@inbox" / "@outbox" / "@all" / Object-Id

 <t>The value '@inbox' indicates the collection of all messages sent to the user.  The value '@outbox' indicates the collection of all messages sent by the user and is used as a special endpoint for posting outbound messages. The value "@all" indicates that the operation should be applied to all message collections (such as deleting a message).</t> 

2) I'll take a pass at the JSON->XML->ATOM

Jon

--

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]

Thoughts on standardizing the type names, today we have:

Style 1) AppData, BodyType, MediaItem
Style 2) Group-Id, Global-Id, Local-Id, Object-Id, Plural-Field,
Domain-Name, Date-UTC-Offset

2 different styles - not good.

Option 1) camel case, with acronyms treated as lower case (e.g. id,
utc). So we get:
GroupId, GlobalId, LocalId, ObjectId, PluralField, DomainName,
DateUtcOffset

Option 2) Use "-", capitalize first letter of each word, acronyms
remain upper case, So we get:
App-Data, Body-Type, Media-Item, Group-ID, Global-ID, Local-ID, Object-
ID

I propose Option 1.

I see "option 1 camel case" used throughout Social-API, REST, RPC.

The only non-option-1 are Type names (all caps with "_") and file
names (Style 2)

Jon

[Jon]

Should it be "UserId" or "PersonId"?
Since there is no "User" object.

[Lane LiaBraaten]

I'd actually prefer to stick with Option 2.  I think it's more common when working with ABNF (e.g. http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5), and I think it's a smaller delta to change AppData, BodyType, and MediaItem than all the ABNF definitions and most of the Type names.

-Lane

[Lane LiaBraaten]

Person works for me.

-Lane

On Thu, Dec 10, 2009 at 8:56 AM, Jon <jon.we...@gmail.com> wrote:

Should it be "UserId" or "PersonId"?
Since there is no "User" object.

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

Added new types and applied them. Defined field types for Message.

http://codereview.appspot.com/154120

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

Per the discussion going on, I have the special types for Person, App,
Group and Message Collection. Since most of those definitions did not
exist in previous document, I created them. I welcome review of the
definitions.

Message was without specific types, as it was in V0.9 documents. I used
my judgment in applying types, once again I welcome a review.

There were a few other places where strings went to a type "URL" and
other small changes.

If you just want to see the type changes, look at the diff relative to
patchset 9.

http://codereview.appspot.com/154120

[llia...@google.com]

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

http://codereview.appspot.com/154120/diff/12001/12003#newcode135
draft/Core-Data.xml:135: <c>@appId represents the application specified
in the
remove "@appId"

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

http://codereview.appspot.com/154120/diff/12001/12002#newcode295
draft/Social-Data.xml:295: <c>Array &lt;<eref
target="./Core-Data.xml#Object-Id">Object-Id</eref>&gt;</c>
should be of type Message-Collection-ID

http://codereview.appspot.com/154120/diff/12001/12002#newcode695
draft/Social-Data.xml:695: <c>string</c>
should be of type User-Id (or Person-Id)

http://codereview.appspot.com/154120

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

LGTM +1. Thank you Jon!

http://codereview.appspot.com/154120