Regras de CSV da RFC 4180

A gramática: registros, campos, CRLF

A gramática da RFC 4180 cabe em um parágrafo. Um arquivo consiste em registros, cada registro uma sequência de campos separados por vírgulas; os registros são separados por CRLF — os dois bytes 0x0D 0x0A, não o LF puro das ferramentas Unix —, e o último registro pode ou não terminar com um CRLF final. Os campos podem ou não estar entre aspas: o uso de aspas é condicional, não um estilo. O esboço em ABNF é file = [header CRLF] record *(CRLF record); record = field *(comma field) — repare no cabeçalho opcional dentro dos colchetes.

id,name,score
1,Ada,99
2,Grace,98

registro 1: id=1, name=Ada,   score=99
registro 2: id=2, name=Grace, score=98

(cada registro termina com os dois bytes CRLF;
o último pode omiti-los legalmente)

Aspas: a aspa dupla é todo o sistema de escape

Um campo é envolto em aspas duplas quando precisa estar, e a única forma de colocar uma aspa dupla dentro de um campo com aspas é dobrá-la — "" dentro de um campo com aspas significa uma aspa literal. Esse é todo o mecanismo de escape: sem barras invertidas, sem entidades nomeadas, sem um segundo caractere de aspas. Aspas simples são dados comuns, e um espaço perdido depois de uma vírgula faz parte do campo seguinte — a especificação é explícita que os espaços são preservados e não devem ser aparados.

year,quote,note
1962,"she said ""look, no hands""","multi-word, no problem"

year   → 1962
quote  → she said "look, no hands"
note   → multi-word, no problem

Quebras de linha e vírgulas dentro dos campos

Como campos com aspas podem conter quebras de linha, uma linha de CSV não é um registro: um divisor ingênuo em \n corrompe qualquer arquivo com campos de múltiplas linhas — e é por isso que blocos de endereço, colunas de observações e payloads de JSON-in-CSV quebram importadores ingênuos. Um parser em conformidade é uma pequena máquina de estados: dentro das aspas, vírgulas e quebras de linha são dados; fora, são separadores. Não dá para escrever corretamente com split() sozinho.

A mesma máquina de estados resolve os casos extremos da aspa dupla: uma aspa abrindo no meio de um valor, uma aspa sem fechamento no fim do arquivo, aspas dobradas no fim mesmo de um campo. Esses são exatamente os casos para os quais as poucas regras da RFC 4180 foram escritas, e exatamente onde parsers artesanais discordam entre si — a origem da maioria dos relatos de 'funciona no Excel, quebra no importador'.

name,address
"Ada","12 St James Square,
London"
"Grace","1 Loop Rd"

registro 1: Ada | 12 St James Square,
London
registro 2: Grace | 1 Loop Rd

(a vírgula dentro do endereço é dado;
o CRLF entre aspas também)

CRLF, o cabeçalho opcional e text/csv

Três detalhes são fixados pela especificação e rotineiramente assumidos ao contrário. Os registros terminam com CRLF — embora o registro final possa omiti-lo, e todo parser que você usa diariamente aceite LF puro. O primeiro registro pode conter nomes de colunas, mas a gramática o trata como opcional: um cabeçalho é uma convenção que o formato suporta, não uma estrutura que ele exige, e é por isso que as ferramentas precisam ser avisadas — ou precisam adivinhar — se a linha um é dado. E o tipo MIME registrado é text/csv — registrado pela própria RFC 4180 —, com parâmetros de charset deixados para o remetente.

Mais uma fronteira que a RFC traça com firmeza: o delimitador é a vírgula. Arquivos separados por ponto e vírgula são uma convenção de localidade de planilhas — comum onde a vírgula decimal é padrão —, não uma variante que o padrão reconheça. Um escritor em conformidade nunca adivinha, e um parser em conformidade ou detecta o delimitador ou é avisado, mas o próprio arquivo não carrega marca alguma de qual convenção segue.

Onde arquivos reais se desviam do padrão

O CSV real é anterior à RFC, então divergência é a norma, não a exceção. Cinco desvios explicam quase todos os incidentes do tipo 'este CSV não analisa':

Boas ferramentas trazem essas divergências à tona em vez de adivinhar em silêncio. Quando um arquivo importa — faturas, importações financeiras, qualquer coisa que um regulador possa ler —, compare-o com a gramática acima e corrija o desvio na origem, em vez de ensinar a mesma exceção a todos os parsers a jusante.

Escrevendo CSV que sobrevive a idas e voltas

A lista de verificação do produtor confiável decorre diretamente da gramática: use aspas de forma uniforme — todos os campos, ou exatamente os campos que as regras exigem; ambos estão em conformidade, mas uniforme é mais seguro para ler de volta —, emita CRLF, escreva a linha de cabeçalho e codifique em UTF-8, aceitando que um BOM às vezes é o preço do reconhecimento por uma planilha. Faça ida e volta de tudo que importa: analise o arquivo que você acabou de escrever, confirme que cada campo corresponde aos dados de origem e só então envie. O modo de falha recorrente é sempre o mesmo — um valor contendo o delimitador que o escritor nunca colocou entre aspas.