Specifying passed and return types

This mail is about ideas for Deliverable D timeless suggested in [1].

As a general rubric, I think the API spec should satisfy these constraints:

1. The "action" and "type" fields of an intent should be opaque strings as
regards the API.

2. What a service (Partner) can expect in the "data" field of the intent is
governed as a function of the "type" exclusively.

3. What data the client should expect in return from a particular intent is a
more complex function, but a function strictly of inputs. However, it is not
strictly a function of the "type" field, but is instead a function of
the "action,"
"type," and possibly of parts of the "data" field as well.

Reasoning:

For forward compatibility, the API shouldn't define any constraints on the
descriptor "action" and "type" fields. They should be left to be defined at
the application layer. This is to ensure that as practice develops, existing
implementations don't stall it by being too restrictive of these fields.

This is not to say that the user agent must not inspect these fields. We've
discussed elsewhere on the list how a user agent might intelligently perform
defaulting and/or add UI features specific to known intents. What I think we
want to make sure of is that user agents will also perform dispatch for
unknown intent types so that practice can evolve.

Specifically, on webintents.org we've suggested using the url namespace
for actions. This allows well-known intents (which we hope to enumerate in
deliverable E of [1] to co-exist with future use of the API. It's worth some
discussion as to whether the best way to ensure that is to request that user
agents also treat the action string as opaque, and whether that limitation
would be a help or hindrance.

The reason for keeping the "type" field completely independent of the action
is to stress that the action is something that translates to user
intent, and the
"type" field specifies the mechanics of what appears in the "data" payload of
the intent. That is, the semantics of the "action" field is such that
there cannot
be only one possible data type. This allows for new type specifiers to emerge
as versioned entities, for instance.

We expect the evolution of commonly-used "action" specifiers to be virtually
none, as compared to the evolution of type specifiers. That is, as services
adopt new formats of data types they accept for a "share" action, for instance,
they can still support legacy types, and the "action" specifier need not change
at all for this. The independence of "action" and "type" fields
ensures that this
can be decoupled.

It makes sense for the client to be able to predict the returned data type
exclusively from inputs: since the client has no way to know what service
handled the intent, it needs to be independent of the service. On the other
hand, we need to make sure that the returned data type is a function of input
"action," "type," and "data." Consider this hypothetical example:

{
action: "http://webintents.org/convert",
type: "application/json;type=http://webintents.org/conversion",
data: { input: "some unformatted text",
           input-type: "text/plain",
           output-type: "text/html" }
}

The output type could be specified in the "data" field for some type-conversion
intents. The "type" field tells the service what to find in the "data"
field, which
means the output has to be a function of all three kinds of intent input data.

For the type field, most of the examples on webintents.org use MIME types.
These types are nice in that they are well-known, used by the clipboard, and
easily verified if need be. MIME types may not be rich enough for some
use cases, however. That set may be smaller than you'd think, because
of the ability to include MIME type parameters (i.e. "text/xml;schema=____",
or "application/json;type=____")

We want to encourage this kind of usage to provide maximum flexibility in
how the user agent deals with the intent data (MIME types are compatible with
host system execution options). But I think we want to write the spec such
that it will support practice evolution around type namespaces other than
MIME. It is a point worthy of discussion whether this ought to be formalized
in the spec. (i.e. non-http-namespace "type" fields must be MIME, or something
like that).


[1] http://lists.w3.org/Archives/Public/public-web-intents/2011Nov/0010.html

Received on Friday, 16 December 2011 19:27:37 UTC