<?xml version="1.0" encoding="utf-8"?>
<?xml-model href="rfc7991bis.rnc"?>
<!DOCTYPE rfc [
<!ENTITY nbsp " ">
<!ENTITY zwsp "​">
<!ENTITY nbhy "‑">
<!ENTITY wj "⁠">
]>
<rfc
xmlns:xi="http://www.w3.org/2001/XInclude"
category="info"
docName="draft-davydov-csvs-00"
ipr="trust200902"
obsoletes=""
updates=""
submissionType="IETF"
xml:lang="en"
version="3">
<front>
<title abbrev="Abbreviated Title">Title</title>
<seriesInfo name="Internet-Draft" value="draft-davydov-csvs-00"/>
<author fullname="Anton Davydov" initials="A" role="editor" surname="Davydov">
<address>
<email>fetsorn@gmail.com</email>
</address>
</author>
<date year="2025"/>
<area>General</area>
<workgroup>Internet Engineering Task Force</workgroup>
<keyword>file format</keyword>
<abstract>
<t>This RFC documents the format used for Comma-Separated Value Store (CSVS)
files.</t>
</abstract>
</front>
<middle>
<section>
<name>Introduction</name>
<t>The comma separated values format has been formally defined in <xref target="RFC4180"/>. This RFC documents a narrow subset that has only two columns, and a dataset that represents relations between values.</t>
<section anchor="requirements">
<name>Requirements Language</name>
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT
RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in BCP 14 <xref target="RFC2119"/>
<xref target="RFC8174"/> when, and only when, they appear in
all capitals, as shown here.</t>
</section>
</section>
<section>
<name>Grammar</name>
<t>
A csvs file MUST have UTF-8 encoding.
A csvs file MUST have .csv file extension.
newline: either Carriage Return 0x0D \r, Line Feed 0x0A \n, or both CR LF 0x0D 0x0A \r\n
string: sequence of any utf8 characters, newlines MUST be escaped
key: string
value: string
file: [[key][,[value]]newline]
each line in csvs file MUST represent a relation between values of two collections
each line MUST contain zero, one, or two values separated by a comma
value that contains a comma, a newline or a double quote MUST be escaped with double quotes ""
omitted value MUST represent an empty string
all characters between the first unescaped comma and an unescaped newline MUST be read as part of the second value
multiple identical lines MUST represent multiple unique relations between identical values
an exact duplicate of a line MUST represent two unique relations
a line that consists only of a newline character MUST represent a relation between one empty string value "" and another empty string value ""
empty lines \n MUST be ignored.
what does it mean that an empty line must be "ignored"? in a sorted file I guess they are at the end and do not yield records. but in an unsorted file - are they dividers of groups of values?
a trailling newline \n MUST be ignored.
these are equivalent
,\n
"",\n
"",""\n
a line CAN have no comma.
these are equivalent
2024-01-01\n
2024-01-01,""\n
these are equivalent
"\n"\n
"\n",\n
</t>
</section>
<section>
<name>.csvs.csv</name>
<t>
a dataset MUST contain a tablet named.csvs.csv which describes the dataset
tablet is for metadata
.csvs.csv tablet MUST have a line csvs,0.0.2
this line is to support future breaking changes to the format.
</t>
</section>
<section>
<name>_-_.csv</name>
<t>a dataset SHOULD contain a tablet named _-_.csv which describes relationships between collections
reserved technical implementation details
underscroll-dash-underscroll
examples:
_-_.csv: event,date - dataset has an "event" collection with an attribute "date"
if there is no _-_.csv tablet, dataset MUST be considered empty
a collection name MUST NOT be "_".
a collection name MUST NOT include the following characters: [/\<>':"```|?*-.,[];{}$&].
a collection name CAN include any of the following: [azAZ09_%+@], white-space and other Unicode characters
NOTE: when there's no _-_.csv file, list directory and deduce relations from tablet names.
</t>
</section>
<section>
<name>collection-collection.csv</name>
<t>underscore is like SQL table? underscore is not like SQL table? underscore is like MongoDB collection? underscore is not like MongoDB collection?
a dataset CAN have a tablet named {collection1}-{collection2}.csv which describes relationships between values of two collections
contains values of two collections
"went to groceries" is an identifier here examples:
description-date.csv: went to groceries,2024-01-01
description-date.csv: went to groceries,2003-01-01 { _: description, description: "went to groceries", date: [2024-01-01, 2003-01-01]} { _: date, date: "2024-01-01"} { _: date, date: "2003-01-01"}
event-description: 0acab,went to groceries\n0abac,went to groceries
event-date: 0acab,2024-01-01\n0abac,2003-01-01 { _: event, event: "0acab", description: "went to groceries", date: "2024-01-01"} { _: event, event: "0abac", description: "went to groceries", date: "2003-01-01"}
how to create two different values with the same text
a relation between collections MUST be listed in _-_.csv
a relation between collections CAN be recursive.
examples:
collection "person" CAN have an attribute "person".
collection "product" CAN have an attribute "competitor" which has an attribute "product".
</t>
</section>
<section>
<name>List Examples</name>
<section>
<name>Simple Unordered (Bullet) List</name>
<t>Text before the list</t>
<ul spacing="normal">
<li>1,bob\n: key is 1, value is bob</li>
<li>1,bob\\n\n: key is 1, value is bob\n</li>
<li>,bob\n: key is "", value is bob</li>
<li>1,\n: key is 1, value is ""</li>
<li>1\n: key is 1, value is ""</li>
<li>\n: key is "", value is ""</li>
<li>2,bob,alice\n: key is 2, value is bob,alice</li>
<li>3,apple\n3,pear\n: key is 3, values are apple and pear</li>
<li>3,apple\n3,apple\n: key is 3, values are apple and apple</li>
</ul>
<t>Text after the list.</t>
</section>
</section>
<section>
<name>Definition Lists</name>
<dl newline="true">
<dt>branch</dt>
<dd>a collection</dd>
<dt>twig</dt>
<dd>a collection without attributes</dd>
<dt>trunk</dt>
<dd>a collection with attributes</dd>
<dt>leaf</dt>
<dd>a collection that is an attribute of another collection</dd>
<dt>root</dt>
<dd>a collection that is not an attribute of any other collection</dd>
<dt>tablet</dt>
<dd>a file in csvs format</dd>
<dt>key</dt>
<dd>the first column</dd>
<dt>value</dt>
<dd>the second column</dd>
</dl>
</section>
<section anchor="IANA">
<name>IANA Considerations</name>
<t>This memo includes no request to IANA. CSVS files use 'text/csv'.</t>
</section>
<section anchor="Security">
<name>Security Considerations</name>
<t>This document should not affect the security of the Internet.</t>
</section>
</middle>
<back>
<references>
<name>References</name>
<references>
<name>Normative References</name>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4180.xml"/>
</references>
</references>
</back>
</rfc>