Editing

This page will be used to track current in-progress edits for draft 3.0

Questions (Please list the answers under each question)

1. PUBSUB2: In Core-gadget, there is a table of "Event Data Types" that are presented without ANY information about how or why they are to be used. A mention is made about OpenAjax Hub but looking through the OpenAjax Hub 2.0 specification I cannot find any mention of these "predefined data types". Can someone please provide an example of how and why these event data types are used and a link to their definition within the OpenAjax Hub specification?

2. EE: Is the ordering of elements within the XML Embedded Experience document significant? The existing text does not clarify this.

Are these equivalent and equally valid (I can make up my own answer, obviously, but it's always better to ask)

Ryan B. has answered that the ordering is insignificant and that the examples are equivalent. The draft language will be updated to reflect that.

3. EE: I notice that there's no XML Namespace defined for the XML Embedded Experience elements. Given that these things are intended to be included inside other XML vocabularies (e.g. Atom) it stands to reason that it would be an extremely good idea to have a namespace for these things or to show a valid example of an XML Embedded Experience embedded within some other XML document. However, adding an XML Namespace at this point would be a non-backwards compatible change. Therefore, at the very least, I need to show an example of one of these things included within another XML document. Does anyone have any examples at all of an XML EE within Atom, etc?

An issue to introduce an XML Namespace to the XML EE serialization in 3.0 has been opened. An example of the existing EE within Atom has been added to the draft.

4. PUBSUB2: Are topics case-sensitive? e.g. is "org.opensocial.*" equivalent to "org.openSocial.*"? the OpenAjax Hub specification is silent on whether topic names are case sensitive. If they are case sensitive, then currently the Core Gadget spec only reserves the "org.opensocial" variant and not things like "org.openSocial.*" which could potentially cause issues down the road.

5. PUBSUB2: It's not clear what the example in section C.12.6.3 is illustrating... the text says, "The Pub/Sub feature supports format for metadata that uses a string to represent the topic information. The format of this string is as follows:" but the example is...

There does not seem to be any connection between the text and what the example actually shows.

6. i18n: The BNF grammar that is "defined" in section C.13.3.2.1 of the Core Gadget spec makes absolutely no sense what so ever, is completely undefined, and does not parse in any BNF/EBNF/ABNF parser I can find. It was lifted verbatim from the Java NumberFormat documentation without attribution or additional documentation explaining it's purpose. The BNF syntax is different from anything else used in the spec and even uses rules it doesn't actually define. It needs to just be pulled out.

7. EE: The section on embedded experiences within email currently requires that MIME email messages that contain embedded experiences include a "text/html" part... the way it's currently worded, an email message that contains only text/plain and an embedded experience would be invalid according to the normative language in the spec. This seems silly at best and seems like the result of just sloppy spec text writing. Was it really the intention to limit the use of embedded experience emails to text/html email messages?

Update: Ryan answered: "Yes it was done on purpose. Displaying of text/plain emails usually is not done in a browser in a desktop application, where as text/html and embedded experiences are. In this case it is very difficult / impossible to deal with a fallback use case where if for some reason we cannot render the embedded experience, ie we cannot find the gadget, we cannot fallback to the text/plain portion of the email. Granted this was just our experience, but we decided to go with the lowest common denominator in this case. It still leaves open the user case you are talking about if the email client supports it."

Problem is, it doesn't leave the use case I asked about open, in fact it explicitly rules it out by requiring a text/html part. If that's what we want, then fine, but I need to know so I can make sure it's clear in the text (as a side note tho, I think such a restriction is pointless). I recommend that we change the MUST to a SHOULD and add language that explains the issue Ryan describes in his response.

8. EE: Since we're deprecating the XML format option in general, are we also going to deprecate the EE XML format option as well?

9. EE: Currently, the only thing the spec says with regards to the EE Security is:

    Embedded experiences allow content to be rendered on the page that
    user has not necessarily requested, therefore it needs to be secured.
    The container SHOULD only ever render content that the user has
    previously approved.  This specification does not dictate how
    secure rendering of embedded experiences is to be performed.

This is extremely inadequate for proper security considerations in a spec. Some discussion of the types of security risks involved should be included along with some explanation about what "The container SHOULD only ever render content that the user has previous approved" actually means. That is, how does a user approve content in this case? How does an implementor go about meeting that "SHOULD" requirement? etc.

10. EE: Can the XML serialization include xml:base and xml:lang attributes? These are not currently defined and are optional. It's perfectly fine leaving them out but it should at least be a conscious decision to do so.

11. Gadget Spec: Document structure...There are a number of pointless SHOULD's in the definition of the various attributes of ModulePrefs... for instance, on the @description attribute, containers are told that they SHOULD display that value in a directory... however, we don't ever define what that means. It's pointless to declare a SHOULD there. Recommend removing the pointless normative requirements on those attributes.

12. Gadget Spec: Document structure...What happens when an undefined @doctype attribute value is used? e.g. @doctype="strict" etc. What should the container do? Ignore it?

13. Gadget Spec: Document structure...What exactly does this mean? "Containers MUST honor the feature-specific rules for any Feature that they claim to support"

Pretty sure the reworked description of this in the current draft makes this a lot clearer.

14. Gadget Spec: Document structure...There was talk of deprecated makeRequest... currently the Preload mechanism in the gadget spec is defined in terms of the makeRequest method... if we deprecate makeRequest we need to redefine the semantics for Preload. (same thing for handling of Content/@href)

15. Gadget Spec: Document structure...The Link element rel attribute is currently defined as: "The relationship between this link and the document. Valid values are specified in Life Cycle Events (Section 4.1.1.5.2) and Icons (Section 4.1.1.5.1). Containers MAY support additional values, but they MUST be namespaced to avoid collisions." Unfortunately, the spec does not provide any information about how such namespacing should occur. For the standard definitions of a Link (RFC 5988), link rels are either simple tokens or fully qualified IRI's. Based on the documentation here, it's not clear if those same rules apply.

If they don't apply, they should. OS should NOT be redefining the basic and generally expected semantics of "rel". This needs to be clarified and potentially fixed.

16. Gadget Spec: Lifecycle events... Does anyone have any examples of what the Life cycle events look like on the wire? (Sidenote... is there any reason why an Activity can't be used for these?)

17. Gadget Spec: Document structure... Is there a limit to the cardinality of icon links? e.g. can I have two Link/@rel="icon" elements? And if so, are there are specific considerations or processing requirements that need to be documented?

18. Gadget Spec: Lifecycle events... the spec current states:

If the rel attribute matches "opensocialevent.TYPE", then events of TYPE are sent to that endpoint. An optional method attribute can be set to POST or GET to specify how the request should be sent. The default is GET.

Here are some examples:

<Link rel="event" href="http://www.example.com/pingme" method="POST/>
<Link rel="event.addapp" href="http://www.example.com/add" />
<Link rel="event.removeapp" href="http://www.example.com/remove" />

Is it supposed to be "opensocialevent.TYPE" or "event.TYPE"... the specification says one thing, the example says something else...

19. Gadget Spec: Document structure...I notice that the Locale element uses separate language and country codes to specify the locale... Unfortunately this is not completely adequate as there are additional bits of information that may be necessary for several locales (e.g. region, etc). It would be much better to define a new attribute here that accepts a Language Range as defined by RFC 4647. For instance, to specify a Locale for "en-US".. it would be...

<Locale for="en-US-*" messages="..." />

This would also provide quite a bit more flexibility than the existing model... Just a thought.

20. Gadget Spec: Document structure...If the "language_direction" attribute is not specified, is the default assumed to be "ltr" ?

21. Gadget Spec: Document structure...Is is possible for the Locale element to include both the messages attribute AND a collection of msg elements? If so, what is the order or precedence should keys be duplicated?

22. Gadget Spec: Document structure...@datatype="number" is currently undefined in the specification. Are there any constraints on the number value?

23. Gadget Spec: The External Services element in the gadget spec is extremely underdefined, to the point of being absolutely useless in the current specification. There is essentially no usable information provided.

An expanded discussion is provided in the new revised draft: Core-Gadget - Document Structure

24. Gadget Spec: For the Content element, the preferred_height attribute says, "If both the @height and @preferred_height are specified" ... the only problem is, there is no "height" attribute defined.

25. Gadget Spec: Is the authz attribute on the Content element only relevant to type=url content can it be used when type=html and href is specified?

This was specified later on in the spec. It's been made clearer in the current draft language: Core-Gadget - Document Structure

26. Gadget Spec: Just a general comment... the view construction rules within the gadget are extremely convoluted... Wouldn't it be best to require that view names have a one-to-one mapping with Content elements to avoid having to concat them and worry about href's, etc? Seems way too overcomplicated.

I've expanded the Content discussion significantly within the current draft language.

27. Gadget Spec: When concatenating content... the spec does not say it currently but I assume the Content elements are to be concatenated in the order they appear in the gadget spec? For instance... given

<Module>
 ...
 <Content views="a">A</Content>
 <Content views="b,a">B</Content>
 <Content views="c,a">C</Content>
 ...
</Module>

The proper rendering for view "a" would be "ABC"

28. Gadget Spec: When using signed fetch with Content/type=url, the example in the spec currently shows a number of undefined attributes being used (sign_owner, sign_viewer). These are not defined for the Content element. These need to be added but I don't know what all additional parameters to add.

This has been clarified in the current draft language.

29. Gadget Spec: Proxied content... using separate language and country query string parameters to specify locale information in the request is silly. We have standardized lang tags (RFC 4646)... we should be using those, or perhaps even use the Accept-Language request header rather than mucking around with the query string parameters at all... For instance, what if I wanted to do <Content href="http://example.org/country_data?country=fr" /> where the proxied content returns information about France rather than returning the content in French?

30. Gadget Spec: Proxied content... The last bit (italicized) of the following is completely nonsensical.. "Remote sites that expect proxied content requests SHOULD reject requests that do not have opensocial_proxied_content set to 1. If a remote site fails to implement this check, any content in the POST body may be spoofed by a malicious user or application." What POST body? This doesn't make any sense at all.

-- open hours review left off here --

31. Gadget Spec: Proxied content... It's currently not clear if the media type returned for proxied content MUST be HTML or not. The definition of the type="html" attribute would imply that it MUST be html but there are currently underspecified portions of the text that suggest that other content types are allowed. It's currently not clear at all what the kind of content can be expected. If it's anything other than HTML, how it the variable substitution supposed to work? Does it have to be text based content? What if a remote service returns binary data?

32. Gadget Spec: Redirected content... Currently, the lib parameter is defined as a relative URL... relative to what?? If the notion is that the URL should be relative to the container, then how does the remote resource know the url of the container to resolve those URL's against? What exactly is the remote resource supposed to do with those relative URLs? How does the remote resource know which libs are required? which are optional? How can one relative URL points to the JavaScript files (plural) necessary to support the gadget? Is there some defined syntax for that URL?

33. Gadget Spec: Proxied Content... In section 6.2.2, The last part of the following statement does not make a whole lot of sense by itself: "The container MUST resolve all URI attributes and values relative to the location of the gadget spec xml document. This DOES NOT include links inside of the body of the Content element at this point in time." ... particularly as it relates to "Processing XML"

34. Gadget Spec: Proxied Content Caching... This whole section makes extremely little sense.. Here's what it says:

 Containers SHOULD cache the results of the HTTP request following the recommendations 
of section 13 of RFC 2616 [RFC2616]. If a container does support caching of data, it MUST
also support overriding HTTP caching by using the value specified for refresh_interval.
Caches SHOULD be keyed using the following:
The URI of the proxied request.
The opensocial owner id, if sign_owner is set to true and requests are authenticated.
The opensocial viewer id, if sign_viewer is set to true and requests are authenticated.
The language and country passed in to the proxied URI.

There are several things about this that are problematic:

There is absolutely zero information given in the entire document about how "refresh_interval" is supposed to work to override the default caching characteristics as defined by RFC 2616.
The language and country query string parameters are already going to be included as part of the URI of the proxied request and so will automatically become part of the cache key without having to specify those separately...
If a GET request is sent using the sign_owner and sign_viewer query string parameters using Signed Fetch without any Authentication or Cache-Control elements in place (and generally without using SSL/TLS), responses to the request may still be cached by intermediaries sitting between the container and the remote service. This would appear to be a limitation of Signed Fetch in general... the request must either include appropriate Cache-Control directives and/or and authentication header, or the response from the remote service must include appropriate Cache-Controls in order to prevent the responses from being cached in appropriately. At best, what can happen is an intermediate cache that is overpopulated with useless cached entries. The specification should be promoting the proper use of Cache-Control directives whenever possible.
Use of the sign_owner and sign_viewer here as it relates to caching is completely underspecified.

35. Gadget Spec: Security policy... what is the difference between requesting a permission using Optional vs Require? For instance...

<ModulePrefs>
  <Optional feature="security-policy">
    <Param name="foo">bar</Param>
  </Optional>
</ModulePrefs>

vs.

<ModulePrefs>  <Require feature="security-policy">    <Param name="foo">bar</Param>  </Require></ModulePrefs>

Section 4.1.2 of the Core-Gadget spec is currently silent on it.

Also, is a gadget developer allowed to specify Optional AND Required security-policy items? e.g.

<ModulePrefs>
  <Optional feature="security-policy">
    <Param name="foo">bar</Param>
  </Optional>
  <Require feature="security-policy">
    <Param name="baz">xyz</Param>
  </Require>
</ModulePrefs>

What happens in this case? Should the gadget be rejected? Does the Require supersede Optional? What happens if the required "baz" permission is not supported? What happens if the optional "foo" permission is not required?

36. Gadget Spec: Security Policy... Given the following statement, "If an application requests a security policy that is not supported, the container MUST log an error to the gadgets.log." What is "gadgets.log"? It is currently competely undefined by the Core-Gadget spec.

37. Gadget Spec: Content Rewriting... The Content Rewriting feature is currently underdefined... specifically, it says things about what can be rewritten but it doesn't explain how or why or give any useful examples... for instance, in the examples section we see...

Rewrite only gif images

<Optional feature="content-rewrite">
    <Param name="include-url">.gif</Param>
</Optional>
Rewrite only gif images that do not contain "animated" or "cdn"

<Optional feature="content-rewrite">
    <Param name="include-url">.gif</Param>
    <Param name="exclude-url">animated</Param>
    <Param name="exclude-url">cdn</Param>
</Optional>

No further explanation is given. What does it mean to "Rewrite only gif images"? What content is being rewritten in these examples?

38. Gadget Spec: Content Rewriting... Why is there en expires param that impacts caching in the content rewriting feature? What does expires have to do with rewriting content? How does it impact normal cache control directives? How does it relate to refresh_interval?

39. Gadget Spec: Lifecycle Events... there are many references throughout the specification that talk about gadgets being "installed" and "uninstalled"... unfortunately, these terms are never actually defined. Since containers are expected to be able to support monitoring and notification of significant gadget lifecycle events, the basic lifecycle states for a gadget need to be defined. e.g. what is the difference between a gadget being "registered" with the container vs. "installed"... "uninstalled" vs. "unregistered"... how do lifecycle events relate to embedded experience gadgets? If a previously unknown gadget spec is included in an EE being processed by the container, what are the expected lifecycle events? Is an EE gadget ever "uninstalled"? Other life cycle events are mentioned in the spec (e.g. rate limiting, whitelisting, blacklisting, etc) but they're never defined. In order for there to be any hope for interop, at least a core basic set of lifecycle events need to be defined (even optional ones like "rate limiting").

40. Gadget Spec: Data Pipelining and Proxied Content... We need on-the-wire examples of what the POST format looks like when data pipelining is used with proxied content.

41. Gadget Spec: Variable Substitution... the deprecated syntax supports BIDI substitution values... e.g. _BIDI_DIR_ ... however, BIDI is not specified as a reserved key for the new syntax... e.g. ${BIDI.DIR} ... also... the whole treatment of BIDI stuff in the spec is underspecified. Need to know how BIDI is handled with the JSPEL-based substitutions.

42. Gadget Spec: Variable Substitution... currently the spec says that variable sub is to be applied to all elements and attributes in the gadget specification with the exception of Locale, msg and EnumValue... while for the most part this is fine, it causes a potential risk when using Data Pipelining... for instance, <os:Var key="mykey" value="${mykey}" /> ... this is nonsensical, obviously, but it's currently allowed by the specification, and an implementation that blindly attempts to apply variable sub to all elements and attributes as defined currently might not catch this immediately... or another example, two data pipeline tags that create a circular reference... <os:Var key="key1" value="${key2}" /> <os:Var key="key2" value="${key1}" /> ... something needs to be said about catching and dealing with these kinds of circular references.

43. Gadget Spec: Variable Substitution... In section 9.4, "Deprecated variable format"... other than the restriction against recursive substitution, the following statement is not clear... I'm not sure exactly what is being said... "Containers MUST perform MSG substitutions in the order listed above. Containers MUST substitute BIDI, MODULE, and UP tokens after substituting MSG values, but they MUST NOT recursively substitute any other tokens." Also... it's not clear if this ordering applies only to the use of the legacy TYPE_KEY syntax or ${el} statements also... the restriction is included within the legacy syntax section.

44. Gadget Spec: Data Pipelining... is the gadget required to have either <Require feature="opensocial.data" /> or <Optional feature="opensocial.data" /> for Data Pipeline elements within the <Data> block or Proxied Content to be processed? Or is the "opensocial.data" feature only required when Data Pipeline elements are embedded within the HTML content?

45. Gadget Spec: Data Pipelining... as a performance consideration... is it defined when the container has to process the Data Pipeline elements? For instance, suppose I have an <os:HttpRequest key="foo" href="..." /> that I don't actually ever reference in the content... is the container still required to process that Data Pipeline element and send the request? Is that request going to be sent and and results processed prior to any rendering of the view occurs or will it be on demand (the request is processed sequentially when the variable is first used from the DataContext)? Has any thought been given to allowing the container to process replacements for such variables asynchronously? e.g. if I do ${Async(foo.result.bar)}, rather than inserting the value immediately, the container could insert something like <span id="async.result.1234">${foo.result.bar}</span>, then continue processing the rest of the content. When the data for the requested key is available, some data handler somewhere will replace the value of <span id="async.result.1234">...</span> with the appropriate value.

46. Gadget Spec: Data Pipelining... question about processing order... relating also to question #45... Given the following example:

 <Content type="html"><![CDATA[
  <script>
    opensocial.data.putDataSet("foo",opensocial.data.getDataSet("id"));
  </script>
  <script xmlns:os="http://ns.opensocial.org/2008/markup" type="text/os-data">
    <os:DataRequest key="person" method="people.get" userId="${foo}" fields="name,birthday"/>
    <os:Var key="id" value="Joe" />
  </script>
  ... HTML content here ...
]]></Content>

What exactly is going to happen in this case? Yes, this is bad programming, obviously, but experience shows that if there are mistakes to be made, many developers will figure out how to make them, and in grand style. What is the order of processing for the Data Pipeline going to be? In this case, are the Data Pipeline elements going to be processed first? How can we guarantee that they are? Do we just say that behavior in such cases is unspecified and use at your own peril? What happens if <os:Var key="id" value="${person.id}" /> ... is the container going to report an error?

Also relating to processing order of data pipeline elements...

 <Data>
   <os:Var key="A" value="${B}${C}" />
   <os:Var key="B" value="${C}${A}" />
   <os:Var key="C" value="${A}${B}" />
 </Data>

What are the resolved values of "A", "B", and "C"?

 <Data>
   <os:Var key="A" value="${B}${C.result.val}" view="test" />
   <os:Var key="B" value="${C.result.val}${A}" view="test" />
 </Data>
 <Content type="html" view="test">
   <script xmlns:os="...">
     <os:HttpRequest key="C" href="foo" />
   </script>
 </Content>

What about now? What are the resolved values for A, B and C (assuming C returns {"val":"123"})

Note the use of view="test" on this example. The spec currently states that Data block data pipeline elements that contain the "view" attribute MUST be processed as if they were contained within the data pipeline script block... so the above example is equivalent to:

 <Content type="html" view="test">
   <script xmlns:os="...">
     <os:HttpRequest key="C" href="foo" />
     <os:Var key="A" value="${B}${C.result.val}" view="test" />
     <os:Var key="B" value="${C.result.val}${A}" view="test" />
   </script>
 </Content>

What happens if I did something like...

<Data>
  <os:Var key="A" value="$\{B\}$\{C.result.val\}" />
  <os:Var key="B" value="$\{C.result.val\}$\{A\}" view="test" />
</Data>
<Content type="html" view="test">
  <script xmlns:os="...">
    <os:HttpRequest key="C" href="foo" />
  </script>
</Content>

here "A" is defined for all views...

47. Gadget Spec: Data Pipelining... how many Data Pipeline <script> tags are allowed to appear within HTML Content? e.g. is the following allowed?

<Content type="html" view="test">
  <script xmlns:os="..." type="text/os-data">
    <os:HttpRequest key="C" href="foo" />
  </script>
  <script xmlns:os="..." type="text/os-data">
    <os:HttpRequest key="C" href="foo" />
  </script>
</Content>

I assume that when multiple HTML Content elements are concatenated together for a single view, and each contains it's own data pipeline block, each block is processed ONLY for it's containing Content element... correct? e.g.

<Module>
  ...
  <Content type="html" view="test">
    <script xmlns:os="..." type="text/os-data">
      <os:Var key="C" value="foo" />
    </script>
    ${C}
  </Content>
  <Content type="html" view="test">
    <script xmlns:os="..." type="text/os-data">
      <os:Var key="C" value="bar" />
    </script>
    ${C}
  </Content>
</Module>

When rendering for view="test", the concatenated output would be "foo bar"... correct?

If that's the case, we have a contradiction in the specification in that when multiple type html content elements exist for the same view, the specification states that their content is to be concatenated together BEFORE applying variable substitution. Therefore, if two type html content elements are to be concatenated together and each contains it's own data pipeline definition for variable "C", what happens?

50. Gadget Spec: Data Pipelining... Do Data Pipeline elements in the script block override view specific data pipeline elements in the datablock? e.g.

<Module>
  ...
  <Data>
    <os:Var key="C" value="foo" view="test" />
  </Data>
  <Content type="html" view="test">
    <script xmlns:os="..." type="text/os-data">
      <os:Var key="C" value="bar" />
    </script>
    ${C}
  </Content>
</Module>

ould output "bar" ... correct?

49. Gadget Spec: Data Pipelining... the "text/os-data" media type is unregistered... we should not be using unregistered media types.

50. Gadget Spec: Data Pipelining... when using data pipeline elements with proxied content, the spec says the following, "The results of the data pipelining requests will be sent to the href of the <Content> section as POSTed JSON data. The structure will be in JSON-RPC format." ... this is unclear... how exactly is the data supposed to be formatted?

For instance, if I had the following:

 <Content type="html" href="http://example.org">
   <os:Var key="id" value="abc123" />
 </Content>

I would think that the input POSTed to the server would be simply:

 POST / HTTP/1.1
 Host: example.org
 Content-Type: application/json


 {"id":"abc123"}

But it's not clear if that's correct given the statement "The structure will be in JSON-RPC format".

51. Gadget Spec: Data Pipeline: This paragraph does not make a lot of sense.. not quite sure what is being said... "Elements in a data pipeline with @userId referencing the viewer (via@viewer, @me) will return a 403 (Forbidden) error response if the container is unable to also send the opensocial_viewer URL parameter to the 3rd party server. The same holds true for @owner and opensocial_owner URL parameter."

52. Gadget Spec: Data Pipeline: The specification uses Data Pipeline elements (e.g. os:PeopleRequest) that are not defined anywhere.

53. Gadget Spec: Data Pipeline... what happens if os:HttpRequest returns binary content?

54. Gadget Spec: Data Pipeline... for os:HttpRequest... on the input parameters, the spec currently states, that the element "MUST support all of the fields in HTTP-Request-Params as attributes", however, the "headers" parameter in HTTP-Request-Params is an array that could potentially contain rather complex string values. There's nothing specifying exactly how that field is to be represented as an XML Attribute. This needs to be defined.

In general, for os:DataRequest and os:HttpRequest, I would generally recommend switching to the use of child <Param> elements rather than an arbitrary collection of undefined attributes... for instance,

Instead of

<os:HttpRequest key="..." method="get" href="..." headers="..." format="text" />

it would be...

<os:HttpRequest key="..." method="get" href="...">
  <os:Param name="format" value="text" />
  <os:Param name="headers">
    <os:Param name="X-Foo-Header" value="blah blah blah" />
    <os:Param name="Prefer" value="lenient" />
  </os:Param>
</os:HttpRequest>

for os:DataRequest.. instead of...

<os:DataRequest key="..." method="people.get" userId="@viewer" groupId="@friends" />

it would be...

<os:DataRequest key="..." method="people.get">
  <os:Param name="userId" value="@viewer" />
  <os:Param name="groupId" value="@friends" />
</os:DataRequest>

This is a much cleaner, and much more well-defined approach.

55. Gadget Spec: Signed Fetch... it currently states that the "opensocial_owner_id" is "The ID of the current owner" .... owner of what exactly? At the face to face, there was significant ambiguity as to who the "owner" referred to... we need to clarify...

56. Gadget Spec: OAuth 2.0 ... when using OAuth 2.0, how is the case OAUTH_USE_TOKEN=never actually implemented? Can it be implemented? The specification currently states that the consumer key will be validated, but when using OAuth 2.0, access tokens are sent using either the Mac or Bearer auth scheme, neither of which have a provision for sending the consumer key without the access token.

57. Gadget Spec: OAuth 1.0a... when using OAuth 1.0a, when OAUTH_USE_TOKEN=if_available, if an appropriate access_token is not known by the container, will the container:

- Send the request to the remote server without ANY OAuth information in the request, or

- Send the request to the remote server with all OAuth information except the access token as it would when OAUTH_USE_TOKEN=never

58. Gadget Spec: OAuth 2.0... same question as 57... when OAUTH_USE_TOKEN=if_available and the access_token is not known... I assume that the request is simply sent to the remote endpoint without any authentication info at all?

59. Gadget Spec: OAuth... when using proxied or redirected content and oauth is required but an access token is not provided, how does the container handle acquisition of authorization token? For instance...

 <Module>
  <ModulePrefs>
    <Link authz="oauth" rel="icon" href="..." />
    <OAuth>..</OAuth>
  </ModulePrefs>
  <Content type="html" href="foo" authz="oauth" />
</Module>

When using Preload and the JavaScript APIs, the gadget provides the UI for redirecting to the oauth server for authorization, etc... but that can't be done with proxied or redirect content... or even Link elements (e.g. "icon")

See: Fixing OAuth in Core Gadget Spec

60. Gadget Spec: Action Contributions... when using the "url" attribute on the action contributions... if a viewTarget is not specified, how is the action handled? will the container render the url within the gadget's view area like it would Redirected Content? Does it open a new window? Display it in a tab? e.g. how is the following case handled...

 <action id="foo" path="container/navigationLinks" label="link!" url="http://example.org/foo" />

61. Gadget Spec: Action Contributions... how are iconSize and iconOffset represented in the <action /> XML element?

62. Gadget Spec: View Target... Just a suggestion... View targets are currently defined statically.. i.e. a enum of TAB, DIALOG, MODALDIALOG, FLOAT or SIDEBAR... wouldn't it be better to define these similarly to how we define action contribution paths? for instance viewTarget="container/tab" would specify a new tab... viewTarget="container/dialog"... This would allow the viewTarget to be extensible in case a container needs to extend the available types of targets (e.g. there could be a "viewTarget"="container/footer", "viewTarget="="container/somethingElse"

63. Gadget Spec: Action Contributions... I assume that updateAction can only be used to modify actions contributed by THAT gadget... containers really should not allow one gadget to modify the actions contributed by another gadget.

64. Gadget Spec: Action Contributions... do getActionsByPath and getActionsByType returns ALL actions registered with the container or only the actions registered by the calling gadget? Is getActionsByPath hierarchical? That is, if I call getActionsByPath("container/menu") would I get all actions registered under "container/menu/*" like "container/menu/File/New" etc.

65. Gadget Spec: Action Contributions... in runAction, there is the statement, "The gadget should call this method whenever an action is triggered by the user." ... I assume this is meant to say "The container should..." as it is the container that actually invokes the callback function.

66. Gadget Spec: Action Contributions... when using gadgets.actions.registerShowActionsListener, will the container invoke the callback immediately after registration to let the gadget know about any actions contributed BEFORE the listener was registered or will the gadget only be notified of actions registered AFTER the listener is registered? Same question with regards to registerHideActionsListener. Is registerHideActionsListener called when the gadget is closed or uninstalled? It's not clear. The spec simply says when the container unloads the gadget. What does unload mean as far as lifecycle events are concerned?

67. Gadget spec: PubSub-2... Use of variable substitution in Topic element names really doesn't seem to make a lot of sense as defined currently. The text says that it's use to supposed to make interop easier but it actually doesn't appear to do that at all since gadgets would be leaving it entirely up to the container to figure out what the topic names are... the gadget would never really be able to know what it should expect to get.

68. Gadget Spec: Selection service.. per this issue... the add and remove Listener variants have an extra parameter that is not supported by the shindig code and that, apparently, should never have been there in the first place. However, now that they've been published as normative, I can't just remove them. We'll need to deprecate that version of the method and replace it.

69. Gadget Spec: Introduction... the concepts of a "view" are discussed many times throughout the document but never actually defined. Is there a formal definition of a "view" anywhere?

70. Gadget Spec: Introduction... the concepts of "viewer" and "owner" are discussed many times throughout the document but never actually defined. Is there a formal definition of a "viewer" and "owner" anywhere?

71. Gadget spec: gadgets.io.encodeValues ... The gadgets.io.encodeValues method... it says that it takes an input object and outputs a URL encoded string, but it doesn't define how that conversion happens. In quick testing, here's what I found:

Test Case:

      var data = {
        "a" : "foo",
        "b" : 123,
        "c" : [ "x", "y", "z"],
        "d" : {
          "a1":1,
          "b1":2
        }
      };
      var m = gadgets.io.encodeValues(data);
      document.write(m);

Shindig outputs:

  a=foo&b=123&c=x%2Cy%2Cz&d=%5Bobject%20Object%5D

Note the value for "d"... basically, the object value is rendered to a string as "[object Object]" which is obviously not what was intended. The current definition of the method does not define any limitations on the object values passed in to the method but does not define how complex object types are to be serialized.

What I need to know is whether:

a) Language needs to be added saying that only primitive and array values are supported (no object values), or

b) Language needs to be added defining how object values are to be handled.

Option (a) is obviously the easiest choice.

For Option (b) we would need to define exactly how arbitrarily complex object structures are to be represented within a URL encoded string. It's certainly non-obvious from the start.

That said, it's not impossible... one option is to flatten the data model such that each nested path (e.g. "data.a.a1", "data"a.b1") becomes a top level property...

e.g.

  a=foo&b=123&c=x,y,z&d.a1=1&d.a2=2

This works in simple cases like the example above, but what about the serialization of an array of objects, for instance:

      var data = {
        "a" : "foo",
        "b" : 123,
        "c" : [ {"a":1,"c":3},{"b":2,"d":4}]
      };
      var m = gadgets.io.encodeValues(data);
      document.write(m);

Shindig outputs:

  a=foo&b=123&c=%5Bobject%20Object%5D%2C%5Bobject%20Object%5D

Obviously what Shindig outputs is wrong and the flattened structure I suggest above doesn't help because of the array.

A reasonable alternative approach would be to recursively serialize nested objects in the output string, e.g.

  a=foo&b=123&c=a%3D1%26c%3D3,b%3D2%26d%3D4

Lastly, I would note that currently, in the example below:

    var data = {
      "a" : "1,2,3",
      "b" : [1,2,3]
    }

Shindig currently outputs:

  a=1%2C2%2C3&b=1%2C2%2C3

Note that the serialization of "a" and "b" are identical an indistinguishable from one another. Is this intentional? It's fine if it is, it should just be acknowledged that the conversion to a URL-encoded String is Lossy and that there is no character-escape mechanism is provided.

The alternative approach is to separate arrays into repeat parameters.. which would make the output:

  a=1%2C2%2C3&b=1&b=2&b=3

This makes the output unambiguous but is not backwards compatible with the current implementation.

72. Gadget Spec: gadgets.io.encodeValues ... the specification says that the encoded string will include a trailing ampersand at the end of the string (e.g. "a=1&b=2&"), however the shindig implementation omits the trailing ampersand (e.g. "a=1&b=2"). Which is the correct behavior?

73. Gadget Spec: gadgets.io.getProxyUrl ... does the proxy URL only support GET? What happens if I POST/PUT/DELETE/PATCH to the Proxy URL from inside the gadget? Does the container forward all methods to the proxied resource?

74. Gadget Spec: gadgets.io.makeRequest... the HEADERS input parameter... current the value is defined as a Map<String,String>... just want to make sure it's clear that this design makes it impossible for multiple instances of a single header to be included in the request. This limitation is fine but it needs to be explicit and intentional.

75. Gadget Spec: gadgets.io.makeRequest... CONTENT_TYPE parameter and the Response object "data" property... what happens if the HTTP Request returns binary data that cannot be represented in a String?

76. Gadget Spec: gadgets.io.makeRequest .... "errors" property on the Response object ... what is the format of the error information contained in the array? Does the array contain strings? objects?

77. Gadget Spec: gadgets.io.makeRequest ... "headers" property return a JavaScript object whose property names are the header names and whose values provide the value of the header in the response. However, the spec does not currently define how multiple header values are represented. For instance, what if the response contains multiple Set-Cookie headers? or multiple Link headers?

78. Gadget Spec: gadgets.util.sanitizeHtml ... what exactly does this method do? What does it means to sanitize HTML? What predictable changes will it make to the input string?

79. Gadget Spec: osapi.http ... when the osapi feature is provided to the gadget, is the osapi.http service object REQUIRED?

80. Gadget Spec: osapi.http ... what are the specific properties for the callback object handed to osapi.http callback functions? e.g.

When I call...

osapi.http.get(params).execute(function(response) { ... })

What are the specific properties I can expect to be provided on the response object?

81. Gadget Spec: gadgets.views ... why are the "views" and "open-views" features separate? Why aren't those just a single feature?

82. Gadget Spec: URL Template support needs to be updated to the finalized RFC version.

83. Gadget Spec: The gadgets.views.View.getUrlTemplate and bind methods are defined without any real explanation about why they exist or how they relate to the current view.

84. Gadget Spec: When calling gadget.views.openEmbeddedExperience and passing in both an EE dataModel AND opt_params... and both specify view and viewTarget parameters, which take precedence?

85. Gadget Spec: For ModulePrefs/@screenshot... why do we need to specify a specific size or format for the image? Why not simply let the container figure this out?

86. Gadget Spec: Why aren't thumbnail and screenshot links done using Link elements like icons are? e.g.

<Module>
  <ModulePrefs>
    <Link rel="thumbnail" href="http://.../foo.png" />
    <Link rel="screenshot" href="http://.../bar.png" />
  </ModulePrefs>
</Module>

87. Gadget spec: The Core-Gadget specification currently calls out the common view names using upper-case letter, e.g. "HOME", "CANVAS", etc... shindig, however, looks for these as lower case (e.g. "home") and treats all view names as being case sensitive. e.g. "Home", "home" and "HOME" are not equivalent. The spec is silent on whether view names are case sensitive. It needs to be clear.

88. Gadget Spec: Are the reserved variable key names used for variable substitution case sensitive? e.g. are ${MSG.foo} and ${Msg.foo} equivalent?

89: Social Gadget (SG): Is there still a need for Social Gadget Document?

90. SG - AppData: Should AppData be defined in Core Gadget rather than Social Gadget?

91. SocialData (SD) - Activities: OK to remove for 3.0?

92. SD - ActionLink : Supporting anything other than GET & DELETE: There is no body defined for other methods...

93. SD - Group-Id: With the move to Aspects do we need to define Group Id in Social-API? Can't the ABNF just be added to Core-API?