Editing
This page will be used to track current in-progress edits for draft 3.0
- Core-Gadget - Embedded Experiences
- Core-Gadget - OpenSearch
- Core-Gadget - i18n
- Core-Gadget - PubSub
- Core-Gadget - Document Structure
- Core Gadget - Security Policy
- Core-Gadget - Content-Rewriting
- Core Gadget - Gadget Lifecycle Events
- Core Gadget - Variable Substitution and Localization
- Core-Gadget - Data Pipelining
- Core-Gadget - Action Contributions
- Core-Gadget - Flash Feature
- Core-Gadgets - MiniMessage
- Core-Gadget - OAuth Popup
- Core-Gadget - Versioning
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)
<embed>
<context><a>b</a></context>
<gadget>foo</gadget>
</embed>
<embed>
<gadget>foo</gadget>
<context><a>b</a></context>
</embed>
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...
<Require feature="pubsub-2">
<Param name="topics"><![CDATA[
<Topic title="string" name="string" description="string" type="string"
publish="boolean" subscribe="boolean" aboutUrl="string">
</Topic>
<!--- etc. for other topics —>
]]</Param>
</Require>
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 conte