Hi Robin,
Here is a pre-publication review of Widgets 1.0: Widget URIs 08
September 2009.
My main beef is that this spec does not clearly tell me how to construct
a WURI UA... all the bits are there, however, just need a few editorial
changes, IMHO.
Widgets 1.0: Widget URIs
W3C Working Draft 08 September 2009
>
Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C
liability, trademark and document use rules apply.
Abstract
Many specifications in the Web stack depend on a context being defined
that includes a current IRI. This is easily provided for documents
retrieved over HTTP, or from the local file system, but is currently
undefined for documents extracted from within a widget package.
I don't like the above. Why are you starting this as an argument?
Such a
limitation has a number of implications which this document intends to
address.
Just say what the tech is, IMO. Requirements section covers this better.
Besides, once the spec is out, then the above is not a problem any more,
so it's a tautology to have this line of reasoning here.
Status of This Document
This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of
current W3C publications and the latest revision of this technical
report can be found in the W3C technical reports index at
http://www.w3.org/TR/.
This document was published by the Web Applications WG as a Last Call
Working Draft. This document is intended to become a W3C Recommendation.
If you wish to make comments regarding this document, please send them
to [email protected] (subscribe, archives). The Last Call period
ends 10 November 2009. All feedback is welcome.
This LC period is too long. Make it 10th of October or mid October. This
is to facilitate two LCs.
<snip>
1. Introduction
This section is non-normative.
This specification defines the widget URI scheme that is used to address
resources inside a widget [WIDGETS].
change to "inside a widget package"
2. Conformance
As well as sections marked as non-normative, all authoring guidelines,
diagrams, examples, and notes in this specification are non-normative.
Everything else in this specification is normative.
The key words must, must not, required, should, should not, recommended,
may, and optional in this specification are to be interpreted as
described in [RFC2119].
3. Not in this specification
This section is non-normative.
There are many different efforts that have specified URI schemes to
access the content of Zip archives, or endeavour to do so. While these
endeavour > endeavor
efforts have merit, and while W3C Widgets rely on Zip as a packaging
format, the use cases that this specification addresses are radically
different.
"radically" is unnecessary. You make grand statements, but then don't
back them. What is so radical about what we are doing? Don't tell me (I
know how awesome we are!), put in the spec :)
In fact, it is possible that both this scheme and another
defined to access Zip archive content would be used jointly, with little
or no overlap in functionality.
The scheme defined in this specification could be used to implement
inter-widget communication, but that is outside the scope of this
current document.
This is not proven. I would just say that cross-widget is out of scope
and, may be future work, but not that it could be used for that.
4. Requirements
All this should be moved to the widgets requirements doc.
This section is non-normative.
Must allow addressing resources inside a widget
The scheme must be able to address Zip relative paths as defined in the
Widgets: Packaging and Configuration [WIDGETS] specification.
yep
Must allow resolving relative URL references inside a widget
It must be possible for a document inside a widget to use a relative
reference to another without any specific knowledge of the scheme being
used. For instance, if a document located at dahuts/dextrogyrous.html
features a link to levrogyrous.html that link must resolve to
dahuts/levrogyrous.html.
yep
Must not allow addressing resources outside a widget
There is no requirement on how widgets are stored and potentially
unpacked within a given user agent, but irrespective of how that is
performed, including for instance by storing the unpacked widget on the
local file system, it must be impossible to address resources outside of
the widget using this scheme.
yep
Must provide an origin IRI for widget-contained documents
Many mechanisms in widgets (e.g. cookies, local storage, XMLHttpRequest)
key off the IRI or part thereof from which they are used. Since widgets
are for all intents and purposes local applications that do not have an
origin, this scheme must provide integration with these mechanisms.
double yep!
Must be independent of any file system
Addressing based on this scheme must only map onto Zip relative paths
and remain independent of any file system on which the widget may be
stored.
Must not conflict with existing IRI usage in web runtimes
This scheme must enable maximal reuse of existing web runtimes, and
therefore not conflict with the architecture of existing IRI usage.
yep
Must not require widget developers to be aware of it for basic tasks
Using this scheme as the IRI of resources inside a widget must not force
widget developers to be aware of its existence for simple tasks such as
linking between widget resources, and would ideally not require such
knowledge for advanced tasks either.
Yep... but I would qualify this as "the whole scheme" or "must not need
to know about every component part of the scheme", as you need to at
least know about the path component.
Must be compatible with the Widgets 1.0: Packaging and Configuration
localisation model
Widgets 1.0: Packaging and Configuration [WIDGETS] defines a runtime
localisation model that allows IRI references to be resolved to
different resources depending on the user agent's locale settings, this
IRI scheme must enable such resolution.
Yep
A careful review of existing schemes has found that none matches the
needs above.
"existing schemes" needs references to all the ones we looked at.
"careful review" > "review" and link it to the wiki or my presentation
on the wiki. You might also link to the landscape doc, though I can't
remember if I covered that in there or not.
5. Widget URIs
Widget URIs are primarily IRIs that are synthesised by the user agent as
it absolutises IRI references found in documents contained in widgets or
defines base IRIs for them.
Note that using widget URIs directly when authoring content is
discouraged, and authors should stick to using schemeless relative IRI
references.
>
As a widget is initialised the user agent may generate an identifier
initialised > initialized.
"may" > will (statement of fact)
that will be used as the authority part of the widget absolute IRI.
the widget > the widget's
I'm wondering if we should use the word "origin" here.
As
of this specification that identifier has no semantics and must be
ignored while resolving the IRI reference to a representation.
The above is confusing. Ignored by who? When?
If
present, the authority will be said to be opaque.
"will be said to be" > is
"opaque" needs to be defined.
Future versions of
this specification may define more precise syntax and semantics for this
opaque authority.
5.1 The widget URI scheme
The URI scheme for widget URIs must be widget.
must be widget > is a string that matches the production of
<code>widget-URI</code>.
You can't use "must" here, is just is.
Also, that is not a valid URI.
Its ABNF syntax [ABNF] is
therefore:
widget-scheme = "widget"
Please merge the above and the Syntax section below. It's all the same
thing.
5.2 Syntax
The ABNF syntax [ABNF] for widget IRIs is as follows, a widget URI must
adhere to this syntax:
widget-URI = widget-scheme "://" [ iauthority ] "/" zip-rel-path [ "?"
iquery ] [ "#" ifragment ]
add: widget-scheme = "widget"
Where the zip-rel-path non-terminal is defined in the Widgets 1.0:
Packaging and Configuration specification [WIDGETS] and the others
reference RFC 3987 [RFC3987].
Change:
Widgets 1.0: Packaging and Configuration specification [WIDGETS]
to just:
[WIDGETS] specification.
Example widget IRIs could thus be:
widget://beefdead/dahuts/sightings/alpes-françaises.svg (assuming the
generated opaque authority is beefdead) or
widget:///secret-identities/marcoscàceres/batman.foaf
Nananana! Batman! :D
5.3 Base IRI and Relative IRI Reference Resolution
The base IRI for a resource contained in a widget must be constructed by
concatenating widget://, optionally the opaque authority, and the Zip
relative path to the resource.
Base IRI needs a reference to something or needs to be defined.
Resolution of relative IRI references is performed using the mechanism
appropriate for the language in the context of which the reference
appears, typically following chapter 5 of [URI] or possibly [HTML5].
I would put "(or, for instance, [HTML5])".
We just don't want to risk a normative dependency. Another option is you
make the last sentence a note.
5.4 Usage as Origin
Mapping from a widget IRI to an origin is depends on the rules defined
for this purpose by the document type being referenced.
"origin is depends" > "origin depends"
I don't understand the sentence above.
Within an HTML 5 context [HTML5], the origin of a resource inside a
widget is defined by an extension to the HTML5 origin algorithm.
Oh $...@$! seriously? Should this section be an Appendix or something? Are
we really going to start screwing with HTML5? This section is currently
normative.
If the
<scheme> component obtained after step 5 is widget, then the tuple that
is returned must be "widget", optionally the opaque authority part, and
nothing for the <port> component. Furthermore, the ASCII and Unicode
serialisations for widget origins are as defined in HTML 5 for other
schemes, except that the port must always be the default one for the
given protocol.
Again, "must" doesn't make sense to me in this context. Apply it to a
user agent.
5.5 Mapping widget IRIs to Widget Resources
Terminology is wrong in this heading:
Change:
Mapping widget IRIs to Widget Resources
To:
Mapping Widget IRIs to files within a widget package
Also, consistently switching between URI and IRI is giving me
reader-sickness (a form of metaphorical motion sickness). I think we
should just use IRI throughout and be done.
The process of resolving a widget IRI to a resource within a given
widget is must operate as follows (or in a manner that guarantees the
same result):
"is must" ? Please convert the above to something that applies to a
product. Also, this spec lacks a conformance section that lists the
products.
1. Let uri be the IRI reference to resolve. If uri is a relative IRI
reference, make it absolute as defined in [URI].
Mkay.
2. Let path be the path component of uri. Remove the leading U+002F
SOLIDUS ("/") from path.
You don't need 2, the rule for finding a file within a widget package
already does this for you.
3. Run the algorithm defined in Rule for finding a file within a widget
package using path as its parameter. What it returns is the file entry
being sought.
It return a "file". A file entry is a different thing (sorry about the
confusion).
Or may return an error, which needs to be handled.
Note that neither the query nor the fragment parts of the widget IRI are
used in the resolution process. They must nevertheless be kept as part
of the IRI and processed according the rules defined by the content type
being referenced.
Ok, we have a problem here: the P&C's rule for finding a file within a
widget package can't cope with fragments and queries, so in 3, make is
super clear that the UA needs to chop off the query and fragment parts.
That's kinda clear already, but, it does not hurt to be a little bit
more clear.
Again, nice work Robin! :)
Kind regards,
Marcos
