Copyright © 2007 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
Developing content for delivery to a mobile context extends the range of form factors, browser capabilities and network characteristics which should be taken into account when compared with developing content with desktop delivery in mind. Having access to information describing the various relevant properties assists the content developer with developing such content. This document describes a standard API for access to repositories of such information (Device Description Repositories).
The following was the text for the previous version
Developing Web content for mobile devices is more challenging than developing for the desktop Web. Compared with desktop Web clients, Mobile Web devices come in a much wider range of shapes, sizes and capabilities. The Mobile Web developer relies upon accurate device descriptions in order to dynamically adapt content to suit the client. This document defines platform and language neutral programing interfaces that provide access to those device descriptions.
This document is an editors' copy that has no official standing.
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 is an Editorial Draft of a possible future W3C Recommendation.
Publication as an Editorial Draft does not imply endorsement by the Device Description Working Group or the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document is published as part of the W3C Mobile Web Initiative (MWI) by the Device Description Working Group. It is a deliverable as defined in the Charter of that group.
Please send comments to public-ddwg@w3.org. This list is archived at http://lists.w3.org/Archives/Public/public-ddwg/.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This revision contains a tidy-up of the earlier version with a reordering of sections, revision of certain introductory text, insertion of certain suggested text under 7 DDR-API Abstract Data Model and 8 Abstract API Definition and removal of IDL - with a view to reinserting it once the abstract data model and abstract API definition are closer to agreement.
It reflects discussions and resolutions from the July F2F.
1 Introduction
1.1 Uses for the DDR-API
1.2 Scope
1.3 Reading the Specification
1.3.1 Conformance Information
1.3.1.1 Normative and Informative Parts
1.3.1.2 Normative Language for Conformance Requirements
2 Relationship with other specifications
2.1 CC/PP
2.2 DCCI
2.3 DPE
2.4 Delivery Context Ontology
3 Terminology
4 Conventions
4.1 Documentation Conventions
4.1.1 Bindings
4.2 Naming Conventions
4.3 Examples
5 Use Cases
6 Design Principles
7 DDR-API Abstract Data Model
7.1 Introduction
7.2 The Context Key
7.3 Components
7.4 Properties
7.4.1 Property Names
7.4.1.1 Namespaces for Property Names
7.4.1.2 The Core Vocabulary
7.4.1.3 Relationship between Vocabularies and the Delivery Context Ontology
7.4.2 Property Values
7.4.3 Property Collections
7.5 Status Codes
7.6 Common Datatypes
7.7 Additional Types
7.8 Metadata
8 Abstract API Definition
8.1 All the functions jumbled together for now
8.1.1 IdentifyByUAString
8.1.2 IdentifyByHTTPHeaders
8.1.3 GetPropertyValues
8.1.4 GetAllPropertyValues
8.1.5 ListProperties
8.1.6 ListComponents
8.1.7 IdentifyByPropertyValues
8.1.8 MapContextKey
8.1.9 ListComponentTypes
8.1.10 AddComponent
8.1.11 EditComponent
9 DDR Extensions
9.1 Extending Device Descriptions and Properties
10 Conformance
10.1 Conformance Requirements for DDR-API Implementations
11 WSDL Language Binding
11.1 DDR-API Exception Interface
11.1.1 Properties of DDR-APIException:
12 Binding rules for mapping APIs to any programming language
A IDL Definitions for DDR-API
B Normative References
C Informative References (Non-Normative)
D Java API (Non-Normative)
E Informative Use Case: To Be defined (Non-Normative)
F Changes Since the Previous Version (Non-Normative)
F.1 Normative Changes
F.2 Informative Changes
G Acknowledgements (Non-Normative)
This section is informative.
JR: This preamble would benefit from a write-through to make it more specific to the purpose of this document
Mobile Web development it is not as easy as conventional web development. Programmers must deal with a wide variety of device capabilities, an heterogeneous mix of software versions and different adherence to standards. For instance, there are different handsets (mobile phones, smart phones, PDAs) with different screen resolutions, input modes, memory, CPU constraints, etc.
Besides, although there is a convergence towards a unique markup language (XHTML), the reality nowadays is that different browsers support different versions of HTML-based and XML-based languages. Moreover, mobile web browsers that in theory support the same markup language often behave in different and unexpected manners. More generally speaking, the browser and the device are part of the delivery context, a set of attributes that characterizes the capabilities of the access mechanism, the preferences of the user and other aspects of the context into which a web page is to be delivered [DIGlossary].
The final page delivered to the user might depend on the delivery context. Top-quality mobile sites differentiate from less-quality sites because they take into account the delivery context when they are rendering a page. As a consequence, top-quality mobile sites provide the best user experience and usability, which is a critical point in the mobile space.
Device and browser descriptions are the two fundamental components of the delivery context. There are some properties of the device and browser that are immutable and typically are stored in repositories of information maintained by content adaptation solutions, mobile telco operators or open source projects. One example of such a property is the color resolution of the display on a mobile device.
Programmers demand standard application programming interfaces (APIs) that simplify and provide a unified way of accessing the device and browser properties stored in Device Description Repositories ([Definition: DDR]s). This document defines those interfaces - the [Definition: ].
Various use cases for the DDR-API are detailed in [Requirements]
In summary, the DDR-API can be used in any scenario that would benefit from accessing device descriptions. The DDR-API is not bound to any particular kind of device description or property.
However, it is noteworthy to point that one of the key uses for DDR-API are related to content adaptation for device independence. Content to be used on a particular device may benefit from being tailored to take account of that device's capabilities. Layout, styling and the media associated with a web page may all benefit from being tailored to take advantage of (or avoid limitations of) features of the delivery context to achieve a functional user experience.
The W3C DDR-API offers various levels of functionality to satisfy differing Use Cases. The classification of the various levels relates to conformance claims. The DDR Basic Interface provides read-only functionality to allow an adapting application to identify the Delivery Context (DC) and to query the DDR for attribute values for components of the DC.
In addition, it provides access to basic catalog information that allows it to find out about which attributes are supported and what devices and models are supported.
Advanced functions allow the addition of information to the DDR and provide more elaborate access to the Cataloguing functions.
Many aspects of the operation of a real world DDR are not standardised by this recommendation, for example, user management, user identification and authentication, management of the data within the DDR. The recommendation makes no assumptions about the internals of the DDR, the physical storage mechanism, the distribution across actual servers and so on. In addition, the details of the operation of the API are not specified - e.g. how to instantiate and close the library, concurrency and threading and whether the calls are blocking or non-blocking.
The normative and informative parts of this specification are identified by use of labels within various sections. Generally, everything in the specification is considered to be normative, apart from the examples.
Individual conformance requirements or testable statements are identified in the DDR-API specification by the use of specific key words. In particular, the key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [IETF RFC 2119] .
Need to review this section, not sure that the following is in the right place, nor that CC/PP has a relationship with this spec. DCCI and DPE should no doubt appear, but what do we think the relationship is, exactly? Also, since the Core Vocabulary has a relationship with the Delivery Context Ontology, there is a relationship of some kind, which presumably should be spelled out there. We do have the idea of being able to explore the Ontological properties relating to a particular vocabulary entry, so the reference is needed here too.
The DDR-API provides mechanisms for:
Identifying a component of a delivery context
Need a definition of Delivery Context in the intro (plus should it be Capitalized?)
Retrieving properties of a previously identified component of the delivery context
DCCI insert refs etcis the standard API that allow to retrieve delivery context properties from the client side. The capabilities made accessible through DCCI are very dynamic in nature.
This section is informative.
Need to review this after we have written a bit more, plus it really needs to be normative?
An application that makes use of the DDR services to perform some functionality.
A description of an element of the delivery context.
A device property that can have different values (default, maximum, actual ...).
A key that identifies a delivery context in a DDR under the scope of a client session.
An abstract identifier that points to a context key in an specific DDR regarding a client session.
Need a discussion in here of the use cases per the discussion at the F2F day 2 - i.e. simple recognition and property look up "the adaptation use case" (run time) vs the (design time) use case where you look for classes of devices, how many devices support x etc.
It would be useful to refer to the diagram we drew at the f2f, has anyone a copy of it?
This needs elaboration etc.
Complexity, it should not be an onerous API.
Methods must be useful. If there is a method for an obscure property, and it's not useful, we shouldn't have created it. Academically interesting properties shouldn't get specific methods.
Easy to learn - limit number of functions
Allow for efficient implementation
Common use cases easy to do ... other uses harder but only in proportion to their inherent complexity
Need a discussion of object instantiation, who is responsible for it, and who is resposible for object disposal. Also need a discussion of thread safety etc.
The languages that will guide the design of the IDL are: Java, Ecmascript, Ruby, PHP, Python, Perl and the .net family (resolution at F2F)
This section is normative.
The Delivery Context (DC) models the environment into which content is delivered. For Web Browsing, it includes, but is not limited to, network connections, gateways, proxies and a device running a browser (possibly with additional helper applications). The device may have additional hardware attached, such as an external keyboard, display monitor, speech generation and assistive technologies such as a screen reader. Each identifiable item is called a "component of the Delivery Context", or [Definition: Component], for short.
Each component of an actual delivery context has a type. The DDR API does not prescribe which components any given DDR implementation may choose to recognise, nor does it prescribe the precise definition of any particular component type. For example, any DDR implementation may choose to model the DC in any way - a conforming DDR must, however, implement components that support the attributes identified by the [version of the] Core Vocabulary insert refin some components. Typically, it is understood that most DDRs will share a similar view of the Component Types of "Device Hardware" and "Browser".
This could usefully be reworked into a discussion of "evidence" ...
The context key provides a handle to aspects of the delivery context that are of significance to the DDR, such as the components that have been determined to be present. From discussion at F2F plus further suggestion on list (ACTION-58):It is an opaque reference to a structure the details of which are determined on a per "instance type" basis. It is used in some API calls to provide part of the query information.
Since the structure of the Context Key is opaque it cannot be examined in a standardized way. Standard functions, are probably not in this revision though, however, provided to query the context key to yield
the property list of a component of a particular type
a set of property lists of components of a particular type (where more than one component of a particular type matches the criteria specified when generating the context key)
a collection of property lists and sets of property lists, where each member of the collection identifies a component of the delivery context
A list of the component types that are in this delivery context
... probably more will emerge ...
each of the items in the list above needs its own section, if agreed
To allow for flexibility in implementations, the Context Key is modelled as an opaque type in the DDR-API IDL. The mapping between this and language data types depends on the capabilities of the language in question. but should we give examples of how we expect it to be realised e.g. as an Object in Java and as an untyped pointer or reference in languages that support it?
Note:
Depending on the implementation type, the context key may opaquely hold session information. Whether or not it does so is a local matter to the implementation, however, users of the API should handle responses from API calls containing a status of CONTEXT_KEY_NO_LONGER_VALID. To continue to use the API a new context key should be generated, implying that applications should maintain a copy of the original information with which the context
key was generated to deal with this eventuality.
Not sure if the Core Vocab contains the components or if this is a separate vocabulary, either way we need to identify browser and device.
Property names exist as entries in controlled vocabularies do we wish to define a normative format for defining such vocabularies. The controlled vocabularies are distinguished using namespaces. Vocabularies may also be versioned - per F2F discussion it is recommended that they not be distinguished by namespace, but the discussion did not reveal how it is suggested that they be distinguished.
Namespaces for property names follow the XML pattern of being a URI need ref http://www.w3.org/TR/REC-xml-names/. Mechanisms are provided for establishing a default namespace and for binding namespace prefixes to URIs. If no default namespace is established by a DDR-CLIENT then the default namespace refers to the Core Vocabulary.
The Core Vocabulary is a set of properties that the DDWG has determined provide the minimal amount of information for useful adaptation in the Web context. It is defined in ref tbd.
Vocabularies can exist in any form and refer to any subject matter. It is anticipated that vocabularies will bear a relationship to a particular component type or to a number of component types. Vocabularies may simply consist of an enumeration of property names together with an explanation of what the property describes.
Vocabularies that describe the Web Delivery Context are anticipated to bear some kind of relationship with the Delivery Context Ontology, which is a detailed and fine-grained description of the Web Delivery Context. It may be that items in the vocabulary map directly to leaf nodes in the ontology. Vocabularies designed for general tasks, however are more likely to refer to non-terminal nodes in the ontology and hence represent some kind of "roll-up" of the various detailed properties concerned.
When accessing values of such properties, DDRs may choose to refer to additional properties from the Delivery Context Ontology that are of relevance or indeed any other ontology or vocabulary I suppose. In any case this implies that there is some additional structure returned in the call (a PropertyList), or that can be retrieved by some as-yet unspecified call, that enumerates related properties [and their relationship?] for the property in question - e.g. if "cv" is bound to the core vocab then there might be a call getRelatedProperties("cv:screenWidth", relatedPropertyStructure)
Property values are a tuple consisting of a value and where appropriate a unit together with a status code providing information about the value. Values may be integer, float, string or boolean.
DDRs may allow the specification of the unit required for a particular value. which would change the definition of Property List / Collection below.
Are we going to allow enumerations, lists, ranges, do we wish to allow specification of confidence and attribution? Can you get multiple values (e.g. John says 4 but Mary says 5). Do we need to think about structured values (e.g. screen dimensions)?
There are two types of property collection. As an input parameter, a list can be supplied of the property names whose value is sought for a particular context. As an output parameter, a similar list of property names together with appropriate property values.
should we also consider named sets of properties - e.g. if we said "usual-suspects" meant "get me the width, height and color depth"?
The DDR-API defines the following statuses for property values. More than one status can apply to a particular value.
There is no further information about the value returned for this property.
The property name is unknown to this DDR
This DDR has no information about the value of the property in question for the requested component
For the component in question, the value of this property can change and cannot be determined (e.g. screen orientation for devices that offer landscape and portrait)
The value is a default value
The value is a composite value. More detailed information can be determined about various aspects of the property value.
Use of this property is deprecated in favor of?.
The DDR does not support the requested unit (for DDRs that support requesting property values in specific units)
The unit requested for this property value is not supported for this property
other things we could worry about are - do we want to be able to flag Computed Value ?? Inherited Value ??
This section is normative
Before defining this as IDL I think it better to write a description of the functions, hence I have removed the IDL, for now
In this revision I am not going to distinguish between "core" and "additional"
In this revision I am not going to classify the functions either, though clearly it would be useful to classify them into things like get delivery context, find out about properties supported, get property values etc.
There was a discussion at the F2F about how one might use a context key plus additional explicit properties to refine values. It would be useful to try to weave in that aprt of the discussion that referred to "evidence"
placeholder for text classifying the functions in this section
Takes an HTTP User Agent Header and returns a Context Key
A string containing the UA to be matched
Match the Exact UA String or do a Loose match
Return only the best match if true, otherwise return a set of matches
Values: Exact Match Found, Found, Not Found
A Context Key opaquely referencing various component types and their alternatives
tbd
Takes HTTP Headers and returns a Context Key
Should there be a way of prioritizing certain headers?
A strings containing the HTTP Headers to be matched - each header is on a new line as described in HTTP 1.1
Return only the best match for each component identified
Values: Found, Not Found
A Context Key
tbd
Takes a Context Key and a Property Set and returns a Property Set
This doesn't deal with the ase where there is a choice of components of the same type to choose from, either because of doubt in the matching process or because there is actually more than one component of the same type in the context (e.g. if you're lucky enough to have two transcoding proxies in series)
The context in which properties are sought
Identify which component of the context we are interested in
A list of properties whose values are sought
Found, not found ...
A list of properties and their values
Actually this could be an in/out parameter?
tbd
Takes a Context Key and a Component Type and returns a Property List representing all properties for this component worried about the implication that this means the DDR is allocating memory rather than the client
The context in which properties are sought
Identify which component of the context we are interested in
Found, not found ...
A list of properties with values
Actually this could be an in/out parameter?
(should this be all properties the DD knows about or just those properties that it has values for, for this component?
Lists the properties that this DDR knows about
none
A list of properties
tbd
Lists the components that this DDR knows about
(none)
A context key containing all the components that the DDR knows about, e.g. a list of all the devices as alternatives and all the browsers as alternatives
tbd
Takes a list of properties and their values returns a Context Key
There is a good case for actually having two different versions, one which supports simple lists of properties with particular values and another of which is much more expressive e.g. screen-width < 200 and screen-width > 120- or more generally to make proper expressions, e.g. combine property values with ANDs or ORs, specify partial string matches and so on
This includes identify by brand and model and identify by IMEI - which has implications on the Core vocabulary, I guess
A list of properties and values to be matched
Return only the best match if true, otherwise return a set of matches
Values: Exact Match Found, Found, Not Found
A Context Key opaquely referencing various component types and their alternatives
tbd
Map from one DDR's Context Keys to Another
need a way of identifying DDR types, or instances. In fact, though this was strongly advocated as an answer to the problem of limited interoperability between DDRs we have now gone completely the opposite way with folks advocating that a context key is only valid within the context of a session. Anyway, I have left it in for now, though I think the guillotine will fall on it in short order.
Some kind of identifier for DDR1
Some kind of identifier for DDR2
A context key from DDR1
Values: DDR1/DDR2 not known, DDR1 Context Key not recognised, DDR2 Context Key not found, Partial Match, OK
The context key for DDR2
tbd
Find out what component types the DDR supports, e.g. browser, device, transcoding proxy ...
none
A list of component types
(not clear what this means really, i.e. what properties do component types have? Is it just a name/description?
tbd
Add a component
We decided at the F2F that editing functions were out of scope so this one is history. But here as a historical curiosity
What type of component it is
A list of properties and values of the component
this implies that whatever string identification the component has is part of the propertylist, i.e. Name must be a property of all components? Core Vocab implications
Bad component type, Duplicate, Property not found, Component not found, Wrong Property for Component, Invalid Property Value for component, bad units for property value, OK
A Context Key which opaquely references this component.
tbd
Change/Add Property Values associated with a Component
We decided at the F2F that editing functions were out of scope so this one is history. But here as a historical curiosity
A Context Key containing a reference to this component
A list of properties and values for this component. Existing properties of the same name are replaced and new properties added.
Property not found, Component not found, Wrong Property for Component, Invalid Property Value for component, bad units for property value, OK
tbd
This section is normative. It gathers together the conformance requirements for implementations of DDR-API defined in this specification.
This section is normative. It describes a WSDL [WSDL] language binding for DDR-API.
DDR-APIException:
DDR-APIException.ACCESS_VIOLATION_ERR
The value of the constant ACCESS_VIOLATION_ERR is 1
DDR-APIException.NOT_SUPPORTED_ERR
The value of the constant NOT_SUPPORTED_ERR is 2
DDR-APIException.PROPERTY_FILTER_ERROR
The value of the constant PROPERTY_FILTER_ERROR is 3
This appendix contains the complete OMG IDL [IDL] definitions for DDR-API
Consolidated IDL
This section is informative
Editorial Note: The WG has not agreed yet if the Java Binding has to be normative or informative
This section is informative. It provides an illustration of how the DDR-API could operate.