Metadados de Campo Zero - Adicionando metadados em seus arquivos CSV

3.1 # como comentários ou metadados

Esse parece ser o jeito mais comum de adicionar metadados ou comentários para um csv, ele requer um parser customizado ou pré-processamento, não possui padrão e pode ser meio ambíguo já que um campo começando com # também pode ser um campo válido.

1. #Isso é meu arquivo csv!
2. #tipo=vetores
3. x,y,z
4. 1,2,3
5. 4,5,6
6. 7,8,9

3.2 Arquivo de metadados/Arquivo Zip

Um arquivo para propósitos de metadados é carregado junto com o arquivo csv normalmente com o mesmo nome do arquivo csv mais um sufixo (-meta.tipo) e usa qualquer formato de dados, ambos os arquivos podem ser juntados em um arquivo zip.

1. meu-csv.csv:
2. x,y,z
3. 1,2,3
4. 4,5,6
5. 7,8,9
7. meu-csv-meta.xml:
8. <meta>
9. <descricao>Isso é meu arquivo csv!</descricao>
10. <tipo>vetores</tipo>
11. </meta>
13. meu-csv.zip:
14. meu-csv.csv
15. meu-csv-meta.xml

3.3 W3C

Eles tentaram (em inglês), eu nunca ouvi falar desse formato da W3C até que comecei a pesquisar sobre metadados em arquivos csv.

1. #publisher,W3C
2. #updated,2015-10-17T00:00:00Z
3. #name,sensor,temperature
4. #datatype,string,float
5. sensor,temperature
6. s-1,25.5

3.4 Referências (em inglês)

• Adding metadata / identifier data to a CSV file?

• Store metadata in CSV file

• How to add metadata to a csv file?

• A Straightforward Way To Extend CSV With Metadata

4.1 Campo Zero

Depois de pensar sobre, não há melhor lugar para adicionar metadados do que se não no primeiro campo do arquivo csv.

1. "metadados",y,z
2. 1,2,3
3. 4,5,6
4. 7,8,9

4.2 Sem outros formatos de dados

Ao invés de usar outros formatos de dados como json ou xml, nós usamos um csv embutido para isso, isso elimina o requerimento para outros formatos de dados.

1. "a,b,c,d",y,z
2. 1,2,3
3. 4,5,6
4. 7,8,9

4.3 Identificável

Nós usamos um cabeçalho de csv para isso que só pode ter uma chave e um valor, qualquer outro cabeçalho não é válido e deve ser processado como um campo normal, mesmo que o cabeçalho seja meio único, ainda é uma boa ideia para os parsers adicionarem uma opção para ler como texto ao invés de metadados, redefinição de campos é permitida e é feita na ordem de aparição, como isso é um arquivo csv embutido, aspas duplas devem ser escritas como duas ao invés de uma e quatro ao invés de duas dentro de campos com aspas duplas.

1. "csv-metadata-key,csv-metadata-value
2. a,10
3. b,20
4. x,""campo, com, vírgulas""
5. y,""campo com """"aspas duplas""""!""
6. c,30
7. c,40
8. ",y,z
9. 1,2,3
10. 4,5,6
11. 7,8,9

4.4 Identificação dos dados CSV

Nós adicionamos um opcional "csv-type-name" para identificação de tipos, similar aos namespaces de XML, isso permite que um arquivo csv seja facilmente distinguível de outro, assim como é pra XML eu recomendo usar uma URL para isso mas qualquer string é válida, até uma vazia ou nada.

1. "csv-metadata-key,csv-metadata-value
2. csv-type-name,https://example.com/vectors.txt
3. ",y,z
4. 1,2,3
5. 4,5,6
6. 7,8,9

4.5 Valor do Campo Zero

Nós adicionamos um opcional "csv-field-zero" para definir o valor do campo zero (o primeiro campo), se não presente uma string vazia é assumida.

1. "csv-metadata-key,csv-metadata-value
2. csv-type-name,https://example.com/vectors.txt
3. csv-field-zero,x
4. ",y,z
5. 1,2,3
6. 4,5,6
7. 7,8,9

4.6 Compatibilidade

Se é necessário manter compatível com um sistema, podemos mover todos os dados para a direita e remover o "csv-field-zero", isso não afeta nada, altera apenas a estrutura do csv em si e faz o cabeçalho reaparecer corretamente novamente.

1. "csv-metadata-key,csv-metadata-value
2. csv-type-name,https://example.com/vectors.txt
3. ",x,y,z
4. ,1,2,3
5. ,4,5,6
6. ,7,8,9

4.7 Comentários de uma ou mais linhas e pulo de linhas

O Fato de que permitimos a redefinição de campos significa que agora podemos utilizar chaves vazias como comentários de uma ou mais linhas ou para pular linhas, cuidado deve ser tomado com as aspas duplas, já que isso ainda é um campo normal.

1. "csv-metadata-key,csv-metadata-value
2. csv-type-name,https://example.com/vectors.txt
3. ,
4. ,Comentário de uma linha!
5. ,
6. ,""
7. Isso é
8. um comentário
9. de várias linhas!
10. ""
11. ",x,y,z
12. ,1,2,3
13. ,4,5,6
14. ,7,8,9

5.1 Lendo

1. CSV csv = CSV.read(...);
3. String keyHeader = "csv-metadata-key";
4. String valueHeader = "csv-metadata-value";
5. String header = keyHeader + "," + valueHeader;
6. String quotedHeader = "\"" + keyHeader + "\",\"" + valueHeader + "\"";
8. Map<String, String> metadata = new LinkedHashMap<>();
9. String fieldZero = csv.get(0, 0);
11. //cheque se o campo começa com o cabeçalho
12. if (fieldZero.startsWith(header) || fieldZero.startsWith(quotedHeader)) {
14. //leia os metadados como csv e cheque se o cabeçalho é válido
15. CSV csvMetadata = CSV.read(fieldZero);
16. if (csvMetadata.getNumberOfFields() == 2
17. && csvMetadata.get(0, 0).equals(keyHeader)
18. && csvMetadata.get(1, 0).equals(valueHeader)
19. ) {
21. //leia os metadados, ignorando o cabeçalho
22. for (int metaRecord = 1; metaRecord < csvMetadata.getNumberOfRecords(); metaRecord++) {
23. String k = csvMetadata.get(0, metaRecord);
24. String v = csvMetadata.get(1, metaRecord);
25. //remove comentários
26. if (k.isEmpty()) {
27. continue;
28. }
29. metadata.put(k, v);
30. }
32. //define o campo zero
33. csv.set(0, 0, metadata.get("csv-field-zero"));
34. }
35. }
36. System.out.println("Type: "+metadata.get("csv-type-name"));
37. System.out.println("Field zero: "+csv.get(0, 0));

5.2 Escrevendo

1. CSV csv = CSV.read(...);
3. String keyHeader = "csv-metadata-key";
4. String valueHeader = "csv-metadata-value";
5. ...
6. Map<String, String> metadata = new LinkedHashMap<>();
7. ...
9. //define o campo zero
10. metadata.put("csv-field-zero", csv.get(0, 0));
12. //cria um novo csv com o tamanho de metadata mais 1
13. CSV csvMetadata = new CSV(null, 2, metadata.size() + 1);
15. //escreve o cabeçalho
16. csvMetadata.set(0, 0, keyHeader);
17. csvMetadata.set(1, 0, valueHeader);
19. //escreve o metadata
20. int index = 1;
21. for (Map.Entry<String, String> e:metadata.entrySet()) {
22. csvMetadata.set(0, index, e.getKey());
23. csvMetadata.set(1, index, e.getValue());
24. index++;
25. }
27. //escreve a saída no campo zero
28. csv.set(0, 0, csvMetadata.toString());
29. System.out.println(csv.toString());

7.1 Google Sheets

Google Sheets foi o melhor, parece seguir a RFC4180 em importar e exportar arquivos csv.

7.2 LibreOffice

LibreOffice conseguiu importar/exportar corretamente mas ele tem um estranho comportamento de trocar aspas duplas por aspas duplas curvadas no editor e a falta de um scroll suave torna chata a edição de grandes campos de metadados.

7.3 Excel

Excel nunca suportou a RFC4180 até onde eu sei, se as coisas não mudaram, excel ainda deve ser o diabo dos arquivos csv, gerando arquivos diferentes que dependem de qual país você está, garantindo que sua vida como programador será dolorida.

7.4 Outros Editores Online

Eu consegui encontrar vários editores online pequenos de arquivos csv, todos os que eu testei parecem seguir a RFC4180.