DERI, NUI Galway

IDA Business Park Galway Ireland +353-91-495730 michael.hausenblas@deri.org http://sw-app.org/about.html

EMC Corporation

6801 Koll Center Parkway Pleasanton, CA 94566 U.S.A. +1-925-6006244 erik.wilde@emc.com http://dret.net/netdret/

Open Data Institute

65 Clifton Street London EC2A 4JE U.K. +44-797-4420482 jeni@jenitennison.com http://www.jenitennison.com/blog/

This memo defines URI fragment identifiers for text/csv MIME entities. These fragment identifiers make it possible to refer to parts of a text/csv MIME entity, identified by row, column, or cell. Fragment identification can use single items, or ranges. This draft should be discussed on the apps-discuss mailing list. Online access to all versions and files is available on github.

This memo updates the text/csv media type defined in RFC 4180 by defining URI fragment identifiers for text/csv MIME entities. The change to the text/csv media type registration required IESG approval, as the IESG is the change controller for that registration. The IESG has, after consultation with the IETF community, approved the change, which is specified in of this document. This section gives an introduction to the general concepts of text/csv MIME entities and URI fragment identifiers, and discusses the need for fragment identifiers for text/csv and deployment issues. discusses the principles and methods on which this memo is based. defines the syntax, and discusses processing of text/csv fragment identifiers.

Internet Media Types (often referred to as "MIME types") as defined in RFC 2045 and RFC 2046 are used to identify different types and sub-types of media. The text/csv media type is defined in RFC 4180 , using US-ASCII as the default character encoding (other character encodings can be used as well). Apart from a media type parameter for specifying the character encoding ("charset"), there is a second media type parameter ("header") that indicates whether there is a header row in the CSV document or not.

URIs are the identification mechanism for resources on the Web. The URI syntax specified in RFC 3986 optionally includes a so-called "fragment identifier", separated by a number sign ("#"). The fragment identifier consists of additional reference information to be interpreted by the client after the retrieval action has been successfully completed. The semantics of a fragment identifier is a property of the media type resulting from a retrieval action, regardless of the URI scheme used in the URI reference. Therefore, the format and interpretation of fragment identifiers is dependent on the media type of the retrieval result.

Similar to the motivation in RFC 5147 , which defines fragment identifiers for plain text files, referring to specific parts of a resource can be very useful, because it enables users and applications to create more specific references. Users can create references to the part they really are interested in or want to talk about, rather than always pointing to a complete resource. Even though it is suggested that fragment identification methods are specified in a media type's registration (see ), many media types do not have fragment identification methods associated with them. Fragment identifiers are only useful if supported by the client, because they are only interpreted by the client. Therefore, a new fragment identification method will require some time to be adopted by clients, and older clients will not support it. However, because the URI still works even if the fragment identifier is not supported (the resource is retrieved, but the fragment identifier is not interpreted), rapid adoption is not highly critical to ensure the success of a new fragment identification method.

Fragment identifiers for text/csv as defined in this memo make it possible to refer to specific parts of a text/csv MIME entity. Use cases include, but are not limited to, selecting a part for visual rendering, stream processing, making assertions about a certain value (provenance, confidence, comments, etc.), or data integration.

As long as text/csv fragment identifiers are not supported universally, it is important to consider the implications of incremental deployment. Clients (for example, Web browsers) not supporting the text/csv fragment identifier described in this memo will work with URI references to text/csv MIME entities, but they will fail to understand the identification of the sub-resource specified by the fragment identifier, and thus will behave as if the complete resource was referenced. This is a reasonable fallback behavior, and in general users should take into account the possibility that a program interpreting a given URI will fail to interpret the fragment identifier part. Since fragment identifier evaluation is local to the client (and happens after retrieving the MIME entity), there is no reliable way for a server to determine whether a requesting client is using a URI containing a fragment identifier.

The capitalized 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 .

This memo specifies fragment identification using following methods: "row" for row selections, "col" for columns selections, and "cell" for cell selections. Throughout the sections below, the following example table in CSV (having 7 rows, including one header row, and 3 columns) is used:

date,temperature,place 2011-01-01,1,Galway 2011-01-02,-1,Galway 2011-01-03,0,Galway 2011-01-01,6,Berkeley 2011-01-02,8,Berkeley 2011-01-03,5,Berkeley

To select a specific record, the "row" scheme followed by a single number is used (the first row is at position 1).

http://example.com/data.csv#row=4

The above CSV fragment identifies the fourth row:

2011-01-03,0,Galway

Fragments can also select ranges of rows:

http://example.com/data.csv#row=5-7

The above CSV fragment identifies three consecutive rows:

2011-01-01,6,Berkeley 2011-01-02,8,Berkeley 2011-01-03,5,Berkeley

The value "*" can be used to indicate the last row, so the previous URI is equivalent to:

http://example.com/data.csv#row=5-*

To select values from a certain column, the "col" scheme is used, followed by a position (the first column is at position 1):

http://example.com/data.csv#col=2

The above CSV fragment addresses the second column, identifying the column:

temperature 1 -1 0 6 8 5

The "col" scheme can also be used to identify ranges of columns:

http://example.com/data.csv#col=1-2

The above CSV fragment addresses the first and second column:

date,temperature 2011-01-01,1 2011-01-02,-1 2011-01-03,0 2011-01-01,6 2011-01-02,8 2011-01-03,5

As for rows, the value "*" can be used to indicate the last column.

To select particular fields, the "cell" scheme is used, followed by a row number, a comma, and a column number.

http://example.com/data.csv#cell=4,1

The above CSV fragment addresses the field in the first column within the fourth row, yielding:

2011-01-03

It is also possible to select cell-based fragments that have more than just one cell, in which case the cell selection uses the same range syntax as for row and column range selections. For these selections, the syntax uses the upper-lefthand cell as the starting point of the selection, followed by a minus sign, and then the lower-righthand cell as the end point of the selection.

http://example.com/data.csv#cell=4,1-6,2

The above CSV fragment selects a region that starts at the fourth row and the first column, and ends at the sixth row and the second column:

2011-01-03,0 2011-01-01,6 2011-01-02,8

Row, column, and cell selections can make more than one selection, in which case the individual selections are separated by semicolons. In these cases, the resulting fragment may be a disjoint fragment, such as the selection "#row=3;6" for the example CSV, which would select the third and the sixth row. It is up to the user agent to decide how to handle disjoint fragments, but since they are allowed, user agents should be prepared to handle disjoint fragments.

The syntax for the text/csv fragment identifiers is as follows. The following syntax definition uses ABNF as defined in RFC 4234 , including the rule DIGIT. In the descriptions that follow, specified text values MUST be used exactly as given, using exactly the indicated lower-case letters. In this respect, the ABNF usage differs from .

csv-fragment = rowsel / colsel / cellsel rowsel = "row=" singlespec 0*( ";" singlespec) colsel = "col=" singlespec 0*( ";" singlespec) cellsel = "cell=" cellspec 0*( ";" cellspec) singlespec = position [ "-" position ] cellspec = cellrow "," cellcol [ "-" cellrow "," cellcol ] cellrow = position cellcol = position position = number / "*" number = 1*( DIGIT )

Applications implementing support for the mechanism described in this memo MUST behave as described in the following sections.

If a fragment identifier contains a syntax error (i.e., does not conform to the syntax specified in ), then it MUST be ignored by clients. Clients MUST NOT make any attempt to correct or guess fragment identifiers. Syntax errors MAY be reported by clients.

Rows and columns in CSV are counted from one. Positions thus refer to the rows and columns starting from position 1, which identifies the first row or column of a CSV. The special character "*" can be used to refer to the last row or column of a CSV, thus allowing fragment identifiers to easily identify ranges that extend to the last row or column. If single selections refer to non-existing rows or columns (i.e., beyond the size of of the CSV), they MUST be ignored. If ranges extend beyond the size of the CSV (by extending to rows or columns beyond the size of the CSV), they MUST be interpreted to only extend to the actual size of the CSV. If selections of ranges of rows or columns or selections of cell ranges are specified in a way so that they select "inversely" (i.e., "#row=10-5" or "#cell=10,10-5,5"), they MUST be ignored. Each specification of an identified region is processed independently, and ignored specifications (because of reason listed in the previous paragraphs) do not cause the whole fragment identifier to fail, they just mean that this single specification is ignored. For the example file, the fragment identifier "#row=1-2;5-4;13-16" does identify the first two rows: the second specification is an "inverse" specification and thus is ignored, and the third specification targets rows beyond the actual size of the CSV and thus is also ignored. The complete fragment identifier identifies all the successfully evaluated identified parts as a single identified fragment. This fragment can be disjoint because of multiple selections. Multiple selections also can result in overlapping individual parts, and it is up to the user agent how to process such a fragment, and whether the individual parts are still made accessible (i.e., visualized in visual user agents), or are presented as one unit. For example, the fragment identifier "#row=3-6;4-5" contains a second identified part that is completely contained in the first identified part. Whether a user agent maintains this selection as two parts, or simply signals that the identified fragment spans from the third to the sixth row, is up for the user agent to decide.

Note to RFC Editor: Please change this section to read as follows after the IANA action has been completed: "IANA has added a reference to this specification in the text/csv Media Type registration." IANA is requested to update the registration of the MIME Media type text/csv at http://www.iana.org/assignments/media-types/text/ with the fragment identifier defined in this memo by adding a reference to this memo (with the appropriate RFC number once it is known).

The Internet media type for a CSV document is text/csv. The following registration has been copied from the original registration of text/csv , with the exception of the added fragment identification considerations, and added security considerations for fragment identifiers. text csv none charset, header The "charset" parameter specifies the charset employed by the CSV content. In accordance with RFC 6657 , the charset parameter SHOULD be used, and if it is not present, UTF-8 SHOULD be assumed as the default (this implies that US-ASCII CSV will work, even when not specifying the "charset" parameter). Any charset defined by IANA for the "text" tree may be used in conjunction with the "charset" parameter. The "header" parameter indicates the presence or absence of the header line. Valid values are "present" or "absent". Implementors choosing not to use this parameter must make their own decisions as to whether the header line is present or absent. CSV MIME entities consist of binary data . As per section 4.1.1. of RFC 2046 , this media type uses CRLF to denote line breaks. However, implementers should be aware that some implementations may use other values. Text/csv consists of nothing but passive text data that should not pose any direct risks. However, it is possible that malicious data may be included in order to exploit buffer overruns or other bugs in the program processing the text/csv data. The text/csv format provides no confidentiality or integrity protection, so if such protections are needed they must be supplied externally. The fact that software implementing fragment identifiers for CSV and software not implementing them differs in behavior, and the fact that different software may show documents or fragments to users in different ways, can lead to misunderstandings on the part of users. Such misunderstandings might be exploited in a way similar to spoofing or phishing. Implementers and users of fragment identifiers for CSV text should also be aware of the security considerations in RFC 3986 and RFC 3987 . Due to lack of a single specification, there are considerable differences among implementations. Implementers should "be conservative in what you do, be liberal in what you accept from others" (RFC 793 ) when processing CSV files. An attempt at a common definition can be found in Section 2. Implementations deciding not to use the optional "header" parameter must make their own decision as to whether the header is absent or present. While numerous private specifications exist for various programs and systems, there is no single "master" specification for this format. An attempt at a common definition can be found in Section 2 of RFC 4180 . Spreadsheet programs and various data conversion utilities. Fragment identification for text/csv is supported by using fragment identifiers as specified by RFC XXXX (Note to RFC Editor: Please update with RFC number once it is known). none CSV TEXT Yakov Shafranovich <ietf@shaftek.org> and Erik Wilde <dret@berkeley.edu> COMMON none Yakov Shafranovich <ietf@shaftek.org> and Erik Wilde <dret@berkeley.edu> IESG

The security considerations for text/csv fragment identifiers are listed in the respective section of the media type registration .

Note to RFC Editor: Please remove this section before publication.

Added IESG approval note. Removed "Implementation Status" section.

Changing "charset" parameter to "SHOULD be used" and UTF-8 as default value. Changing encoding to be binary.

Adding complete media type registration by copying and editing the registration from RFC 4180. Moving "Security Considerations" text to media type registration.

Updating "Implementation Status" section to refer to RFC 6982 . Switching to <?rfc symrefs="yes" ?>

Switched category from "std" to "info". Changed the definition of positions to start counting from 1 instead of 0.

Added "Implementation Status" section. Added examples of ranges of rows and columns. Corrected errors in examples.

Removed slices ("#where:") as fragment identification method. Removed any special support for headers, which means that they are now treated as a regular (the first) row (if a header row is present). Changed semantics and syntax to allow multiple selection of rows, columns, and cells, and to allow ranges of rows and columns.

Added cell-based selections. Added Jeni Tennison as author; updated Erik Wilde's affiliation to EMC.

Innosoft International, Inc.

1050 East Garvey Avenue South West Covina CA 91790 US +1 818 919 3600 +1 818 919 3614 ned@innosoft.com

First Virtual Holdings

25 Washington Avenue Morristown NJ 07960 US +1 201 540 8967 +1 201 993 3032 nsb@nsb.fv.com

Innosoft International, Inc.

1050 East Garvey Avenue South West Covina CA 91790 US +1 818 919 3600 +1 818 919 3614 ned@innosoft.com

First Virtual Holdings

25 Washington Avenue Morristown NJ 07960 US +1 201 540 8967 +1 201 993 3032 nsb@nsb.fv.com

SolidMatrix Technologies, Inc.

ietf@shaftek.org

Harvard University

1350 Mass. Ave. Cambridge MA 02138 - +1 617 495 3864

World Wide Web Consortium

Massachusetts Institute of Technology 77 Massachusetts Avenue Cambridge MA 02139 +1-617-253-5702 +1-617-258-5999 timbl@w3.org

Day Software

5251 California Ave., Suite 110 Irvine CA 92617 +1-949-679-2960 +1-949-679-2972 fielding@gbiv.com

Adobe Systems Incorporated

345 Park Ave San Jose CA 95110 +1-408-536-3024 LMM@acm.org

Brandenburg InternetWorking THUS plc. This document changes RFC 2046 rules regarding default "charset" parameter values for "text/*" media types to better align with common usage by existing clients and servers. [STANDARDS-TRACK] ANSI X3.4-1986 University of Southern California (USC)/Information Sciences Institute

4676 Admiralty Way Marina del Rey CA 90291 US

UC Berkeley

School of Information, 311 South Hall Berkeley, CA 94720-4600 U.S.A. +1-510-6432253 dret@berkeley.edu http://dret.net/netdret/

Aoyama Gakuin University

5-10-1 Fuchinobe Sagamihara Kanagawa 229-8558 Japan +81 42 759 6329 +81 42 759 6495 mailto:duerst@it.aoyama.ac.jp http://www.sw.it.aoyama.ac.jp/D%C3%BCrst/

This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature.</t><t> The process in this document is offered as an experiment. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. The authors of this document intend to collate experiences with this experiment and to report them to the community.

Thanks for comments and suggestions provided by Nevil Brownlee, Richard Cyganiak, Ian Davis, Gannon Dick, Leigh Dodds, and Barry Leiba.