File Upload

W3C Working Draft 18 October 2006

This version:
Latest version:
Previous version:
Robin Berjon (Expway) <robin.berjon@expway.fr>


This specification provides an API used to prompt the user with a file selection dialogue and obtain the data contained in files on the user's file system.

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 is a First Public Working Draft. The authors of this document are the members of the W3C Web API Working Group.

This document is produced by the Web API WG, part of the Rich Web Clients Activity in the W3C Interaction Domain.

Web content and browser developers are encouraged to review this draft. Please send comments to public-webapi@w3.org, the W3C's public email list for issues related to Web API. Archives of the list are available.

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.

Publication as a Working Draft does not imply endorsement by 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.

Table of Contents

1. Introduction

It is desirable for Web applications to have the ability to manipulate as wide as possible a range of user input, including files that a user may wish to upload to a remote server or manipulate inside a rich application. This specification provides application writers with the means to trigger a file selection prompt with which the user can select one or more files. Unlike the file upload forms control available to HTML, this API can be used for more than simply inserting a file into the content of a form being submitted but also allows client-side manipulation of the content, for instance to display an image or parse an XML document from disk.

Important Note: this is a very rough first public working draft. Its purpose is in exposing a first pass on the design of this API, in order to gather feedback from the community.

2. The FileException exception

This needs to be described, check existing stuff

The FileException exception

exception FileException {
  unsigned short   code;
// FileExceptionCode
const unsigned short      NOT_FOUND_ERR         = 0;
const unsigned short      NOT_READABLE_ERR      = 1;

Definition Group FileExceptionCode

The file that is trying to be read does not exist. This may be due to it having been moved or deleted after a pointer to it was acquired.
The file cannot be read. This may be due to permission problems.

3. The FileDialog interface

The purpose of the FileDialog interface is to control the display of a file dialogue, and to register the event listeners that will handle the selection of files. The FileDialog object inherits from EventTarget and it is this possible to attach event listeners to it using the addEventListener method.

It is possible that some platforms will only allow for one file to be selected at a time, however when possible a user-agent SHOULD provide the option to select multiple files in one pass.

The FileDialog interface

interface FileDialog : events::EventTarget {
  void open();



When called, this method MUST prompt the user with a means to select one or more files. The exact manner in which the user is prompted is implementation dependent. On devices that have no file system, the user-agent MAY still open a dialogue for data acquisition, for instance one providing access to a built-in camera and a microphone.

This method operates in an asynchronous manner such that the files which are selected will be communicated to handlers registered on the FileDialog object instance to listen to the 'files-selected' event. An example follows in which when file selection is performed, the listener object will be called with a FilesSelectionEvent object.

Example: Basic FileDialog usage
var fd = new FileDialog();
fd.addEventListenerNS("http://www.w3.org/ns/fs-event#", "files-selected", listener, false);
No Parameters
No Return Value
No Exceptions

4. The FileList interface

This interface exposes the list of files that has been selected through the file dialogue. When no file has been selected, its length is zero.

The FileList interface

interface FileList {
  readonly attribute unsigned long  length;
  File               item(in unsigned long index);
  File               removeItem(in unsigned long index);


length of type unsigned long, readonly

The number of files in the list. The range of valid file indices is 0 to length-1 inclusive.



Returns the indexth item in the collection. If index is greater than or equal to the number of files in the list, this returns null.

index of type unsigned long
Index into the collection.
Return Value
The file at the indexth position in the FileList, or null if that is not a valid index.
No Exceptions

Removes the indexth item in the collection. If index is greater than or equal to the number of files in the list, this does nothing. This can be used to filter out files that do not match certain criteria (media type, file extension, etc.).

index of type unsigned long
Index into the collection.
Return Value
The file that was removed from the FileList, or null if that is not a valid index.
No Exceptions

5. The File interface

This interface describes a single file in a FileList, exposes its name and media type, and provides access its content.

Please note that in order to be memory-efficient, implementations are not required to load the content of files into memory as soon as they have been selected, but only when their content is required by the application. When passing a File object to network API such as XMLHttpRequest an implementation may stream the content of a file to a socket and never need to hold more than a few of its bytes in memory. Therefore one needs to be aware that the content of the file may change or cease to be available between the moment the file is selected and the moment it is accessed.

The File interface

interface File {

  readonly attribute DOMString      fileName;
  readonly attribute DOMString      mediaType;
  readonly attribute unsigned long  fileSize;
  DOMString          getDataAsString()
  DOMString          getDataAsBase64()
  DOMString          getDataAsHexBinary()


fileName of type DOMString, readonly

The name of the file, exclusive of its path.

fileSize of type unsigned long, readonly

The size of the file, in bytes. Users should keep in mind that in certain cases this information may not be available, and that it also may vary as a file is being read.

mediaType of type DOMString, readonly

The media type of the file, if known to the user-agent.

How does this handle null and ""? May parameters be included?



Returns the file's content encoded using Base64. An empty file returns an empty string.

Need ref
No Parameters
Return Value
The content of the file encoded in Base64.

All codes apply.


Returns the file's content encoded using hex-binary. An empty file returns an empty string.

Need ref
No Parameters
Return Value
The content of the file encoded in hex-binary.

All codes apply.


Returns the file's content as a string. An empty file returns an empty string.

This has any number of issues with encoding, binary data, etc.

No Parameters
Return Value
The content of the file.

All codes apply.

6. The 'files-selected' Event

Make full description of event as well as the interface.

6.1. The FilesSelectionEvent interface


The FilesSelectionEvent interface

interface FilesSelectionEvent : events::Event {
  readonly attribute FileList  fileList;


fileList of type FileList, readonly

The list of files that were selected. If the dialogue was cancelled or no file was selected, the list MUST be empty.

7. Integration with XMLHttpRequest

The intent here is to add a method to XHR that would allow passing a File object straight for upload, without needing to transfer it through memory first.

8. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].

Unless otherwise specified immediately following the header, all sections in this document — to the exclusion of examples which are all informative — are normative.

9. Acknowledgements

This specification was originally developed by the SVG Working Group. Many thanks to Mark Baker and Anne van Kesteren for their feedback.

A. References

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner.