Re: Comments on Widgets 1.0: Requirements LCWD

Hi Krzysztof,

I've made most of the changes you recommended but I was not able to
resolve everything. Please see below. I would really appreciate if you
could take the time to help me resolve outstanding issues. However, if
you are happy with leaving things as they are, please let me know so I
can close this thread in the disposition of comments.

2008/7/26 Krzysztof Maczyński <1981km@gmail.com>:
>
> Dear WG,
>
> I have written my comments below.
>
> Please take into account the difference between IRI and IRI reference defined in RFC 3987.

I'll look that up. In the mean time, it would be really helpful if you
could tell me any place in particular where I've used the terms
incorrectly?

> Should there be a requirement (probably only may or should for the first version) to specify some way of exposing custom APIs on instances of a widget (like XBL bindings do)?

Hmm.... R30 was supposed to cover this (and from my reading, I think
it does). Can you recommend some additional text or a change to that
requirement that would satisfy what you mean?

>> email checkers
> s/email/E-mail

fixed (but kept E in lowercase, which, according to wikipedia, is ok).

>> This document does not address the requirements of "web widgets", such as iGoogle Gadgets or Windows Live Gadgets.
> Why not? Aren't they similar enough to be covered by one set of specs and one requirements document (perhaps with a bit of inline tailoring)?

No. Web widgets are just <iframe>s or <div>s: They are not packaged or
use widget-specific APIs. Hence, they are covered by HTML4 and HTML5.
Please see section 3.1 of the Widgets 1.0 Landscape  document [1] for
a detailed discussion on this issue.

We don't address embedding of W3C Widgets using <embed> or <object>.
We might leave that for version 2.0.

>> A conforming specification is one
> Not necessarily, since you plan to have 4. Should it be called conforming set of specifications?

Yeah, probably. But it's not so much that all the specs need to
address the one requirement (although it is true that some
requirements are addressed by the interplay of multiple specs, eg.
digital signatures). So even though I agree with you, and technically
you are correct, I think it's pretty clear what we mean here. Also,
the Widget specs are split into multiple specs for ergonomic reasons,
not technical reasons: we figured that having lots of little specs are
easier for people to read/review, then one monolithic one. Hopefully
you (and others) can live with "conforming specification".

>> a widget resource should be easy for authors to create without requiring special software
> This is why ZIP (or whatever ends up decided upon) compression should be optional (also see below).

Deflate is implemented in all common Zip implementations. However, it
might be good for me to document the use of Deflate in the Widgets
Landscape document. In the Landscape document, I have documented that
all widget user agents support Zip and Deflate, but not that all
operating systems support the creation of Zip files that make use of
deflate.

>Furthermore, I don't envision taking advantage of the Security design goal by a typical author when creating widgets without special software.

To be clear, are you saying that an author will need special tools to
make use of the the security features? If you are, then it is too
early to say that yet. For example, generation of digital signatures
*may* require specialized software, but we are working hard so this is
not the case.  There is open source software that can generate a (XML)
digital signatures from a bunch of files and folders.  See for
instance, http://www.aleksey.com/xmlsec/index.html.

>> R1. Packaging Format
> There are arguments for enabling compression, and ZIP is discussed on the list. I'm in favour of it as long as it's optional, i.e. there can also be uncompressed widget resources. R10 satisfies this, but uniformity between these two forms should be maximized. Is Store method of ZIP considered? It fails the previous quote. MIME features (Content-Transfer-Encoding comes to mind) then?

Agreed. You'll be happy to hear that support for Stored is specified
in the Widgets Packaging spec. I've altered R11. Data Compression to
read "A conforming specification SHOULD recommend a packaging format
that supports both uncompressed data and OPTIONAL data compression."

>> R2. File Extension
> It seems contrary to AWWW (see also "Cool URIs don't change" by Tim Berners-Lee).

In what sense is this contrary to AWWW? locally, widget resources are
treated as files not as `representations of resources'. Eventually a
widget ends up on a server where it enters the URI space (and where
they can follow the URI rules/concepts and AWWW). If giving a file an
extension violates AWWW, then every .html, .css, .gif, .png, etc. file
also violates AWWW(?). However, I may be misunderstanding what you are
trying to say here about R2:)

>Also, how Device independence design goal is interpreted to support this? I
>see no hardship for supporting MIME types on various devices instead of sniffing
>(or mapping, if it's defined for a file system by design) them by file name extensions.

I don't see any hardship either, so I don't understand if you want me
to change the wording of this requirement. In reality, vendors will
probably sniff and they will have to sniff or use the extension any
time they get a widget from local storage or over bluetooth or other
non-MIME means or where MIME is not supported.

>> In addition, the packaging format should allow authors to add and remove resources of a widget resource without needing to recreate the widget resource.
> Leverage MIME multipart and Content-Location, please. Motivation: Compatibility with other standards.

I disagree. This would be going against the grain of what widget
engines currently support: Zip. Also, there is no tool support for
MIME in the widget space or included in operating systems. All Widget
user agents support Zip and developers are well accustomed to working
with Zip. Switching to MIME would require specialized tools to be
developed just for widgets. I don't see any advantage MIME has over
Zip.

>> The addressing scheme must not expose the underlying file system
> Please add "(if any)" after that.

Added.

>> must not be able to address resources outside the widget resource via the addressing scheme
> Such ability may be useful (in some future version or even in this one), although I can see the concerns. But it seems harmless, for example, to use URNs (with semantics handled by widget user agent, such as accessing the default instance (forms in older versions of VB have those) or some operating environment motives and artifacts - these are "outside the widget resource", right?). I presume there will be places where IRIs unconstrained by this addressing scheme can be used to allow such usage. Still, I think this must not cannot be enforced syntactically without disallowing relative IRI references (and I can see no reason for disallowing them). Another issue with this is that other instances of the same widget are themselves "resources outside the widget resource" (but not widget resources). Even though R5 currently only provides for addressing resources contained in the widget resource associated withj a given instance of the widget, I believe the goal is (or should be) to enable addressing the instances themselves as well. I would therefore suggest the wording given below for the entire paragraph. Also please clarify that "addressing scheme" means some recipe for minting URIs, not necessarily a URI scheme (which may or may not result from ongoing discussion as the best solution).
> --
> A conforming specification must specify an addressing scheme (a new URI scheme or some prescribed use of an existing one) which must or should be used to address at runtime the individual resources within the widget resource in association with the current or another instance of the widget, as well as these instances themselves. This does not preclude allowing use of arbitrary IRI references in some contexts defined by a conforming specification. When the addressing scheme is used, the widget user agent must be required not to expose any other resources to the widget instance. For this purpose a conforming specification may require that accessing resources identified by IRIs using the addressing scheme which leave the allowed space described above must fail. If addressing resources outside the allowed set described above is possible with the addressing scheme, determining that this is the case for a given IRI reference should be easy for the author, at least for absolute IRI references. The addressing scheme should be one that web authors would feel comfortable using or are already accustomed to.
> --

I'm moving this to a new thread so that TAG members can also participate here.

> Some specific caveats can be mentioned in the rationale extended thus:
> --
> To disable access by widget instances to the underlying file system (if any) or other resources which are not instances of the same widget or resources contained in the widget resource used to create the current set of widget instances.
> --

Added the text to the rationale.

>> how resources need be structured
> Insert "to".

Added.

>> R9. Device Independence
> Please rename to "Device independent delivery" or something. "Device andependence" is already a design goal.

Changed name to "Device independent delivery".

>> where by only widgets that meet a particular level of quality
> s/where by/whereby

fixed.

>> A conforming specification must recommend that a conforming widget resource be sent over HTTP with a formally registered  MIME Type.
> It must be assigned the right MIME type. HTTP has nothing to do with that. Please also consider that it's the MIME type that tells the user agent it's a widget. Changing the MIME type requires different semantics of processing the resource, even if the representation remains the same (see http://www.w3.org/2001/tag/doc/mime-respect). With text/plain it's not a widget anymore (so out of scope for this spec) but a body of plain text.

Correct. I've changed the text to "A conforming specification MUST
recommend that a conforming widget resource be sent over HTTP with a
formally registered MIME Type that is specific to the Widgets 1.0
Family of specifications. The Working Group MUST formally register the
MIME type with the Internet Assigned Numbers Authority (IANA). A
conforming specification MUST specify how to process a widget resource
that was not served with the appropriate MIME type."

>> A conforming specification must specify the structure and semantics of elements
> Are those XML elements?

Yes. I moved R22 and made it R13. That way, it is now more clear that
elements will be in XML. I changed the text so it now reads "semantics
of XML elements"

>> The metadata must be extractable, processable and reusable in other contexts
> Informative reference to GRDDL in the spec would satisfy this.

I've added the following text to the rationale: "An example of reuse
of metadata could include the ability to combine the widget metadata
with GRDDL to produce RDF metadata descriptions about a widget"....
(of course, I still think JSON output would be more useful;-))

>> To provide authors with a practical set of metadata elements
> I believe that metadata should be extensible, so a generic hook should be included in addition to some required items.

The only extensibility mechanism we provide is namespaces... but that
does not exactly address the problem you are describing. I have raise
this as an issue that will need to be discussed in the WG. I think we
will add this if there is more demand from developers for it. The
range of metadata elements currently covered by the spec represent the
intersection of all commonly appearing metadata elements in other
widget user agents (again see the Widget Landscape document).

>> R14. Authorship and Widget Metadata
> Almost all mentioned items seem optional.

Yes. They are all optional. In fact, the configuration document is optional.

>> an author's name, email, and organization
> s/email/E-mail address (Should it be mailbox (RFC 2822) or mailto IRI?)

Fixed typo. Probably IRI, but that's defined in the spec Packaging spec.

>> a unique identifier
> How to check for uniqueness? What if a widget user agent encounters a widget with a non-unique identifier?

I've added the following to R14 Widget Metadata: "A conforming
specification MUST specify graceful error handling procedures for all
metadata elements for when values are in error, or contradictory to
the system, or declared erroneously by an author."

>> as well as a model for how this data must be processed by a widget user agent
> What's the point of this? The user will in all realistic scenarios be able to edit the widget resource manually to prevent such processing, so if the intent is to enforce some obstacles, it's futile.

No, the intent is just to have clearly defined processing rules and
predictable behavior.

>> R16. Visual Rendering Dimensions
> This is privileging visual media. This is making an architectural assumption about widgets that a presentational aspect (intrinsic dimensions) is part of their nature (nothing wrong with this, SVG and MathML do the same, but just calling for awareness), so not deferring it to styling as the only option is acceptable. Please clarify however that if styling is applied, it takes precedence. The same with other means of redefining the dimensions a posteriori. And make them optional (ideally independently in each dimension) to allow widgets without intrinsic width or height.

I agree with you that there is no reason that a widget should be
intrinsically visual. In an attempt to capture what you are saying,
I've rewritten the requirement as follows. Please let me know if I
have captured everything correctly or feel free to suggest changes:

"For widgets that make use of a rendering context, a conforming
specification SHOULD specify an OPTIONAL means for an author to
declare the initial visual dimensions for an instantiated widget in a
way that is device independent (e.g. via CSS pixels). A conforming
specification MUST specify that styling by the author takes precedence
over dimensional values declared in the configuration document or any
dimensional values implicitly computed by the widget user agent.."

>> mechanism that addresses the start file
> A remnant of some old very file-centric
>  draft. Please change to resource.

For me personally, "start file" makes sense in this context as it is
the file (or, yes, "resource") that is first used when starting the
application. If it helps, in the packaging spec, a start file is
defined as "...the *resource* that is used when the widget is
instantiated." I know we are both being nit-picky here, but changing
"file" to "resource" here won't make too much of a difference.

>> it may be able to address a resource on the Web over HTTP
> Why not other protocols or schemes? To disable access to local resources? I believe this distinction should be defined in a more general way and probably ultimately defer to widget user agent policy.

Ok good point. I've removed the word HTTP. It now says  "However, the
bootstrapping mechanism MAY be able to address a resource on the
Internet...".

>> or resources that are of media types supported by a widget user agent
> If a bootstrap resource is of an unsupported media type, it's useless in this context. On the other hand, any can be supported by a given agent.

That's correct.

>> so long as they are compatible with the widget user agent
> This term will have to be defined in the spec. But I doubt the definition will be very meaningful and not a moot paragraph.

By "this term" I suppose you mean "compatible". I've changed it to:

"A conforming specification MAY also allow authors to declaratively
bootstrap proprietary resources within the widget resource, so long as
they are able to be processed or instantiated by the widget user
agent."

>> may specify an automated model
> Combined with the previous requirement this means that a spec just may define something that it must require the agent to do. Not that it couldn't possibly make sense, but if it does for some reason, please state it.

>> an automated model for finding the start file
> Again a file?

Yep:) The things to remember is that addressing inside a package does
not follow HTTP semantics (you are not going to get alternatives or
redirected, etc.). Inside the Zip file there is just (compressed)
bytes identified by a "filename field" (which is a path, eg.
i/am/a.file). I want to be careful we don't get into "architecture
astronautism".

>> For example, the conforming specification could specify a model that searches for a default file name (index.htm, index.html, index.svg, etc)
> Please don't rely on extensions.

Believe me, we don't want to but I cant see another solution for this.
I mean, we can't just go in an parse every XML file in the document to
derive it's type based on it's namespace. That would be very
inefficient. What do you recommend we do here?

>> the widget user agent could try finding files
> At this point I can see clearly that entirely avoiding talking about files seems unrealistic. Let's broaden the term then. I suggest replacing "(or similar logical containers)" in R3 with "(understood in this document > in a broader sense than in some popular file systems, namely as forms of generic logical containers)".

Ok, I've included the text you recommended verbatim.

>> A conforming specification must specify the default values for parameters
> I wrote about this above already. I'd like this to be changed so that for some predefined parameters the agent must supply the values (possibly obeying some rules set forth by the spec) if they are missing. And sometimes even overriding provided ones (like visual dimensions) should be allowed.

Ok, that seems fair. I've added a sentence at the end R20 in hope of
capturing what you are saying:

"A conforming specification SHOULD allow a widget user agent to
override author defined parameters in circumstances where it might be
beneficial for users or has the potential to improve performance or
stability of the widget user agent"

>> can be used independently of the widget resource that contains it
> This jeopardizes addressability when R5 is taken into account. Only an issue if running a widget with an externally associated configuration document is an issue. Or does it implicitly say that the ability to independently use other contained resources is not required?

This comment refers to "R23. Configuration Document Independence".

In version 1.0, it will not be possible to run a widget with an
externally defined configuration document. The intent of this
requirement is that developers or third party sites can extract the
configuration document and use it however they want (within licensing
terms, that is:)). Admittedly, this requirement is kinda dumb because
the fact that you can extract resources from the package is a side
effect of the packaging format. Anyway, I'm tempted to leave this as
is... but modified it so now "A conforming specification _MAY_ provide
guidelines for how the configuration document can be used separately
from a widget resource" (instead of SHOULD).

>> 4.3 Scripting Interfaces
> Possible styling issue in the spec.

fixed.

>> compatibility with other standards
> In R25 and R26 this is surprising but very interesting. Can you mention any W3C (or equivalent) standards which you intend to leverage?

No. Everything we have looked at is overly complicated. I guess the
closest thing in regards to r26 is HTML5's storage mechanism.

>> A conforming specification must define a set of states in the lifecycle of the instantiated widget that are able to be captured through script.
> I suggest: "A conforming specification must define a set of states and transitions in the lifecycle of the instantiated widget. The transitions must have associated events which can be consumed by event handlers, such as scripts. Additionally the API must expose the current state.".

That's much better. I've used your text but with some minor
modifications and removed the word transition as it is too ambiguous
(could be interpreted as visual transition, which I don't think is
what we want here thought it would probably be valid enough). The text
for the requirement is now:

"A conforming specification MUST define a set of states in the
lifecycle of the instantiated widget. Changes in states MUST have
associated events which can be consumed by event handlers, such as
scripts. Additionally the API MUST expose the current state. A
conforming specification MUST NOT require the widget user agent to
send events to the widget immediately, and SHOULD allow the widget
user agent to dispatch the events at its convenience."

Is that ok?

>> if the widget resource is connected to the network
> s/resource/instance

fixed.

>> (or any of its windows)
> s/windows/presentation contexts (Also add Accessibility to motivation here (and possibly in some other places, such as R37. It's the only unused design goal.)

fixed, and added accessibility to r37, r34., r20, r13, r14. I'll
probably add it to more before the next publish.

>> operating system services
> s/system/environment

Fixed.

>> For example, when a news widget receives a news item about a particular company, it could tell a stock widget stock quotes widget to display any changes in that company's share price.
> Now I'm really surprised. The use case is perfectly reasonable, but what about addressability? Isn't it assumed elsewhere that only instances of the same widget can be addressed with the special scheme?

Hmmm... I'm concerned that you are surprised. Have I have left some
conceptual gaps in the spec? Do I need to explain things a bit more
clearly in the introduction? Please let me know what you think I
should do.

I response to your question, it is not assumed that only instances of
the same widget can be addressed with the widget scheme. Having said
that, cross-widget communication is a bit gray ATM and I would
personally like to see it removed from version 1.0. Having said that,
I'm not sure how to proceed here.

>> A conforming specification SHOULD specify a means that allows authors to open URLs
> How about IRIs?

Changed it to IRIs.

>> The declared interface may also be accessible to screen readers
> At least should, I suggest. Also see the rationale.

Ok, changed it to "should".

>> persistently store user preferences for each instantiated widget.
> Instances are ephemeral by nature. Next run of the same widget resource yields another instantiated widget. Where's the persistence? Shouldn't the word "instantated" be omitted?

Ok, I see what you mean. I dropped the word instantiated.

Kind regards,
Marcos
[1] http://www.w3.org/TR/widgets-land/#differences
-- 
Marcos Caceres
http://datadriven.com.au

Received on Thursday, 7 August 2008 07:39:05 UTC