RFC 7111

URI Fragment Identifiers for the text/csv Media Type

📅 published January 2014, from ietf

RFC 7111: URI Fragment Identifiers for the text/csv Media Type 🎀✨

okay bestie, let's get into it 🫶 This one is an Informational doc, so it's not a standards-track spec, and it's published "for informational purposes" 💅. It's from the Independent Submission stream, which means it wasn't written through the IETF's normal process. The authors are M. Hausenblas (MapR Technologies), E. Wilde (UC Berkeley), and J. Tennison (Open Data Institute) 👑. It's dated January 2014, ISSN 2070-1721, and it Updates: 4180 (that's RFC 4180, the text/csv one) 🌸. Nothing here obsoletes anything, and the whole vibe is "we're giving text/csv some fragment identifiers so you can point at exactly the row, column, or cell you want" 🦋.

Status of This Memo 🍓

Okay so, this doc is not on the Standards Track 💀. It's just here to inform, no cap. It's a contribution to the RFC Series, and the RFC Editor published it at their discretion and made no claim about whether you should implement it 🙈. It's also not a candidate for any level of Internet Standard (see Section 2 of RFC 5741) ✨. If you want updates, errata, or to leave feedback, check http://www.rfc-editor.org/info/rfc7111 💖.

IESG Note 🔥

Here's some drama 👀: changing the text/csv media type registration needs IESG approval, because the IESG is the change controller for that registration 😭. The IESG checked in with the IETF community and approved the change, which is spelled out in Section 5 of this document 💅.

Copyright (c) 2014 IETF Trust and the document authors. All rights reserved 🫶. This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stood on the publication date, so read those carefully because they're your rights and restrictions 💜.

Table of Contents 🧚

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
  1.1.  What is text/csv? . . . . . . . . . . . . . . . . . . . .   3
  1.2.  Why text/csv Fragment Identifiers?  . . . . . . . . . . .   3
    1.2.1.  Motivation  . . . . . . . . . . . . . . . . . . . . .   3
    1.2.2.  Use Cases . . . . . . . . . . . . . . . . . . . . . .   4
  1.3.  Incremental Deployment  . . . . . . . . . . . . . . . . .   4
  1.4.  Notation Used in this Memo  . . . . . . . . . . . . . . .   4
2.  Fragment Identification Methods . . . . . . . . . . . . . . .   5
  2.1.  Row-Based Selection . . . . . . . . . . . . . . . . . . .   5
  2.2.  Column-Based Selection  . . . . . . . . . . . . . . . . .   6
  2.3.  Cell-Based Selection  . . . . . . . . . . . . . . . . . .   6
  2.4.  Multi-Selections  . . . . . . . . . . . . . . . . . . . .   7
3.  Fragment Identification Syntax  . . . . . . . . . . . . . . .   7
4.  Fragment Identifier Processing  . . . . . . . . . . . . . . .   8
  4.1.  Syntax Errors in Fragment Identifiers . . . . . . . . . .   8
  4.2.  Semantics of Fragment Identifiers . . . . . . . . . . . .   8
5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   9
  5.1.  The text/csv media type . . . . . . . . . . . . . . . . .   9
6.  Security Considerations . . . . . . . . . . . . . . . . . . .  11
7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  11
8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  11
  8.1.  Normative References  . . . . . . . . . . . . . . . . . .  11
  8.2.  Informative References  . . . . . . . . . . . . . . . . .  12

1. Introduction ✨

So this memo updates the text/csv media type from RFC 4180 [RFC4180] by defining URI fragment identifiers for text/csv MIME entities 🎀.

Same IESG story again: the change to the text/csv registration required IESG approval, and the IESG approved it after talking to the community. The change is in Section 5 💅.

This section is the intro to text/csv MIME entities and URI fragment identifiers. It covers why we need fragment identifiers for text/csv, plus deployment stuff. Section 2 walks through the methods, Section 3 defines the syntax, and Section 4 covers how to process text/csv fragment identifiers 🦋.

1.1. What is text/csv? 🌸

Internet Media Types (aka "MIME types") are defined in [RFC2045] and [RFC2046], and they're how we label different types and subtypes of media 💖. The text/csv type is defined in [RFC4180], and it uses US-ASCII [ASCII] as the default character encoding, though other encodings work too 🫶. There's also a charset parameter for picking the encoding, and a second parameter called header that says whether the CSV has a header row or not ✨.

1.2. Why text/csv Fragment Identifiers? 💅

URIs are how we identify stuff on the Web 🌈. The URI syntax in [RFC3986] has an optional fragment identifier, which comes after a number sign (#) 🎀. The fragment is extra reference info that the client interprets after the retrieval has successfully finished 👑. What a fragment means depends on the media type of what came back, not on the URI scheme, so the format and interpretation of fragments depend on that media type 🧚.

1.2.1. Motivation 💜

This is similar to the motivation in [RFC5147], which defines fragment identifiers for plain text files 🍓. Pointing at a specific part of a resource is super useful, because users and apps can make more precise references and not just link the whole thing 🦋. It's suggested that fragment identification methods get specified in a media type's registration (see [RFC6838]), but lowkey, a lot of media types don't have any 😭.

Fragments only work if the client supports them, since only the client interprets them 💅. So a new fragment method takes time to get adopted, and older clients won't support it 🙈. The good news? The URI still works without support: the resource gets retrieved, the fragment just doesn't get interpreted. That means rapid adoption isn't critical for a new method to succeed 🫶✨.

1.2.2. Use Cases 🌸

text/csv fragment identifiers from this memo let you refer to specific parts of a text/csv MIME entity 🎀. Use cases include (but aren't limited to) picking a part to render visually, stream processing, making assertions about a value (provenance, confidence, comments, etc.), or data integration 💖.

1.3. Incremental Deployment 🧚

Until text/csv fragment identifiers are supported everywhere, it's important to think about incremental deployment 🍓. Clients that don't support this fragment identifier (Web browsers, for example) will still work with URI references to text/csv MIME entities, but they won't understand the sub-resource the fragment points at. So they act like the whole resource was referenced 🌈. That's a reasonable fallback, and in general, users should keep in mind that a program might not interpret the fragment part at all 💅. Fragment evaluation happens locally in the client after the MIME entity is retrieved, so a server has no reliable way to tell whether a requesting client is using a fragment 🙈.

1.4. Notation Used in this Memo 💖

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 [RFC2119] 🫶. Yes, these are the official BCP 14 words, bestie, so they're capitalized on purpose 👑.

2. Fragment Identification Methods 🦋

This memo uses the following methods: row for row selections, col for column selections, and cell for cell selections 🎀.

Throughout the sections below, we use this example CSV table (7 rows including one header row, and 3 columns) 💅:

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

2.1. Row-Based Selection 🌸

To select one record, use the row scheme followed by a single number (the first row is at position 1) 💖.

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

That fragment identifies the fourth row ✨:

2011-01-03,0,Galway

You can also select a range of rows 🧚:

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

That gives you three consecutive rows 🦋:

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

The value * means "the last row," so the previous URI is equivalent to 🎀:

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

2.2. Column-Based Selection 💅

To grab values from a column, use the col scheme followed by a position (the first column is at position 1) 👑:

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

That addresses the second column 🌈:

temperature
1
-1
0
6
8
5

You can select a range of columns too 💜:

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

That addresses the first and second columns 🫶:

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

Same as rows: * can be used to indicate the last column 🍓.

2.3. Cell-Based Selection 🔥

To select particular fields, use the cell scheme followed by a row number, a comma, and a column number 💖.

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

That addresses the field in the first column of the fourth row, which gives you 🧚:

2011-01-03

Cell selections can also cover more than one cell, and they use the same range syntax as row and column ranges ✨. The upper left-hand cell is the starting point, then a minus sign, then the lower right-hand cell as the end point 🦋.

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

That selects a region from the fourth row and first column to the sixth row and second column 🌸:

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

To be continued in Part 2 🌈💖 Stay tuned, bestie!

2.4. Multi-Selections ✨

okay so row, column, and cell selections can all make MORE than one selection at a time 🫶 you just separate the individual picks with semicolons. so #row=3;6 on the example CSV grabs the third AND the sixth row, skipping everything in between 🦋 that's a disjoint fragment (basically a not-all-touching bundle of bits) and it's giving main character energy 💅 it's totally up to the user agent (your browser, your PDF viewer, whatever) to decide how it handles those, but since they're allowed, user agents should be prepared to handle disjoint fragments 💜

3. Fragment Identification Syntax 🎀

okay the grammar time 🧚 the text/csv fragment identifiers are written in ABNF, which is defined in RFC 5234 [RFC5234] (it borrows the rule DIGIT from there too). here's the whole thing:

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 )
NOTE 📣 the specified text values MUST be used exactly as given, using exactly the indicated lowercase letters. so yes, this ABNF is a little different from the usual [RFC5234] vibe, so don't get it twisted 🙈

4. Fragment Identifier Processing 🌸

applications implementing support for this mechanism MUST behave as described in the following sections. no vibes-based guessing, we're following the rules 💖

4.1. Syntax Errors in Fragment Identifiers 🙅‍♀️

okay so if a fragment identifier has a syntax error (aka it doesn't match the grammar from Section 3), then it MUST be ignored by clients. clients MUST NOT try to correct or guess what you meant 😭 like absolutely no fixing your typos for you. syntax errors MAY be reported by clients, which is optional but iconic if they do 🫶

4.2. Semantics of Fragment Identifiers 🧠

rows and columns in CSV are counted from ONE, not zero 🙈 so position 1 is the first row or column. the special character * refers to the LAST row or column, which makes it super easy to grab ranges that go all the way to the end ✨

if single selections point at rows or columns that don't exist (aka they're beyond the size of the CSV), they MUST be ignored 💀

if ranges extend past the size of the CSV, they MUST be interpreted as only extending to the actual size of the CSV. so the range gets trimmed, no drama 💅

if selections of ranges of rows, columns, or cells are specified "inversely" (like #row=10-5 or #cell=10,10-5,5), they MUST be ignored. backwards ranges are not it 🚫

each specification is processed independently, and ignored specs don't break the whole fragment identifier. they just get skipped 🦋 for the example file, #row=1-2;5-4;13-16 still identifies the first two rows: the second spec is "inverse" so it's ignored, and the third one targets rows beyond the actual size of the CSV, so that one's ignored too 💜

the complete fragment identifier identifies all the successfully evaluated parts as ONE identified fragment. this can be disjoint because of multiple selections 🎀 multiple selections can also overlap, and it's up to the user agent how to process that and whether the individual parts stay accessible (visualized in visual user agents) or get presented as one unit 👑 for example, #row=3-6;4-5 has a second part completely contained in the first one. whether a user agent keeps that as two parts or just says "the fragment spans rows three to six" is totally up for the user agent to decide 🌈

5. IANA Considerations 📋

IANA has added a reference to this specification in the text/csv media type registration 🎀

5.1. The text/csv media type 💜

the Internet media type [RFC6838] for a CSV document is text/csv 🍓 this registration was copied from the original text/csv registration [RFC4180], with the exception of the added fragment identification considerations and added security considerations for fragment identifiers ✨

Type name:  text

Subtype name:  csv

Required parameters:  none

Optional parameters:  charset, header

okay the charset parameter specifies the charset the CSV content uses. in accordance with RFC 6657 [RFC6657], the charset parameter SHOULD be used, and if it's not present, UTF-8 SHOULD be assumed as the default (which means US-ASCII CSV still works even without specifying charset 🌸). any charset IANA has defined for the "text" tree may be used with the charset parameter 💅

the header parameter tells you whether the header line is present or absent. valid values are "present" or "absent" 🦋 implementors who choose not to use this parameter MUST make their own decisions about whether the header line is present or absent 🫶

Encoding considerations: CSV MIME entities consist of binary data [RFC6838]. as per Section 4.1.1. of RFC 2046 [RFC2046], this media type uses CRLF to denote line breaks 🌈 however, implementers should be aware that some implementations may use other values 🙈

Security considerations: okay this part is SERIOUS bestie 😭

text/csv consists of nothing but passive text data that should not pose any direct risks. HOWEVER, it's possible that malicious data may be included in order to exploit buffer overruns or other bugs in the program processing the text/csv data 💀 so be careful!!

the text/csv format provides NO confidentiality or integrity protection, so if those protections are needed, they MUST be supplied externally 🔐 (yes, it's giving "not my job" but make it someone else's job 🙅‍♀️)

the fact that software implementing fragment identifiers for CSV and software not implementing them behaves differently, 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 😵 those misunderstandings might be exploited in a way similar to spoofing or phishing 🎣 scary stuff!!

implementers and users of fragment identifiers for CSV text should also be aware of the security considerations in RFC 3986 [RFC3986] and RFC 3987 [RFC3987] 📚

Interoperability considerations: 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 [RFC0793]) 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 🎀

Published specification: 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 [RFC4180] ✨

Applications that use this media type: spreadsheet programs and various data conversion utilities 📊

Fragment identifier considerations: fragment identification for text/csv is supported by using fragment identifiers as specified by RFC 7111 🦋

Additional information:

  • Magic number(s): none
  • File extension(s): CSV
  • Macintosh file type code(s): TEXT

Person & email address to contact for further information: Yakov Shafranovich <ietf@shaftek.org> and Erik Wilde <dret@berkeley.edu> 💌

Intended usage: COMMON 🌈

Restrictions on usage: none 🫶

Author: Yakov Shafranovich <ietf@shaftek.org> and Erik Wilde <dret@berkeley.edu> 👑

Change controller: IESG 🧚

6. Security Considerations 🔐

the security considerations for text/csv fragment identifiers are listed in the respective section of the media type registration in Section 5.1 💖

7. Acknowledgements 🫶

thanks for the comments and suggestions from Nevil Brownlee, Richard Cyganiak, Ian Davis, Gannon Dick, Leigh Dodds, and Barry Leiba 🌸 you all are iconic ✨

8. References 📚

8.1. Normative References 🎀

[RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
           Extensions (MIME) Part One: Format of Internet Message
           Bodies", RFC 2045, November 1996.

[RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
           Extensions (MIME) Part Two: Media Types", RFC 2046,
           November 1996.

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66, RFC
           3986, January 2005.

[RFC3987]  Duerst, M. and M. Suignard, "Internationalized Resource
           Identifiers (IRIs)", RFC 3987, January 2005.

[RFC4180]  Shafranovich, Y., "Common Format and MIME Type for Comma-
           Separated Values (CSV) Files", RFC 4180, October 2005.

[RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
           Specifications: ABNF", STD 68, RFC 5234, January 2008.

[RFC6657]  Melnikov, A. and J. Reschke, "Update to MIME regarding
           "charset" Parameter Handling in Textual Media Types", RFC
           6657, July 2012.

8.2. Informative References 💜

[ASCII]    ANSI X3.4-1986, "Coded Character Set - 7-Bit American
           National Standard Code for Information Interchange", STD
           63, RFC 3629, 1992.

[RFC0793]  Postel, J., "Transmission Control Protocol", STD 7, RFC
           793, September 1981.

[RFC5147]  Wilde, E. and M. Duerst, "URI Fragment Identifiers for the
           text/plain Media Type", RFC 5147, April 2008.

[RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
           Specifications and Registration Procedures", BCP 13, RFC
           6838, January 2013.

Authors' Addresses 🦋

Michael Hausenblas
MapR Technologies
32 Bushypark Lawn
Galway
Ireland

Phone: +353-86-0215164
EMail: mhausenblas@maprtech.com
URI:   http://mhausenblas.info


Erik Wilde
UC Berkeley

EMail: dret@berkeley.edu
URI:   http://dret.net/netdret/


Jeni Tennison
Open Data Institute
65 Clifton Street
London EC2A 4JE
U.K.

Phone: +44-797-4420482
EMail: jeni@jenitennison.com
URI:   http://www.jenitennison.com/blog/

That's the whole thing, bestie 🌈💖 RFC 7111 is wrapped up!

📦 where this page comes from