Documentos e dados

Dicionário de dados para um CSV: como documentar cada coluna

Um CSV pode abrir sem erros e ainda ser difícil de interpretar. Aprenda a documentar nomes, tipos, códigos, ausências, unidades e datas com um modelo prático.

Apification
Exemplo de dicionário de dados para CSV com colunas, tipos, códigos e regras para dados ausentes

Um CSV legível nem sempre é um CSV interpretável

Um arquivo CSV pode abrir corretamente em uma planilha e, ainda assim, deixar perguntas básicas sem resposta: o que cada coluna representa? Um valor como «3» é uma quantidade ou um código? Uma célula vazia significa que não se aplica ou que o dado é desconhecido? O formato organiza valores em linhas e colunas, mas não explica, por si só, o significado de cada campo nem se ele deve estar preenchido. O [Guia de dados tabulares CSV do datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/guia_csv_vf.pdf) observa que o CSV não inclui um mecanismo para indicar o tipo de dado de uma coluna ou se seus valores devem ser obrigatórios. Essa falta de contexto pode fazer com que duas equipes interpretem o mesmo conjunto de dados de maneiras diferentes.

O dicionário de dados resolve essa ambiguidade com uma descrição para cada coluna e regras explícitas de interpretação. Ele não substitui o CSV nem corrige seus dados: acompanha a entrega para que quem a recebe possa entendê-la e usá-la com critérios consistentes. É especialmente útil quando o arquivo circula entre áreas, é integrado a outro sistema ou é atualizado com frequência. O objetivo prático é permitir que alguém que não participou da criação do arquivo reconheça o significado de cada valor e saiba o que fazer diante de uma exceção.

  • Se uma coluna contém códigos, não presuma que seu significado seja evidente.
  • Se um dado pode estar ausente, especifique o que cada forma de ausência representa.
  • Se um número tem unidade, moeda ou escala, documente isso junto ao campo.
Um CSV legível nem sempre é um CSV interpretável

O que documentar e o que deixar de fora

O dicionário descreve o conteúdo: nomes de variáveis, significado, tipo ou formato esperado, unidades e, quando pertinente, valores codificados com seus rótulos. Também pode indicar se um campo admite ausência e como interpretar um valor nulo. Por exemplo, dizer que «estado» usa códigos não é suficiente: é preciso identificar o que cada código representa. Na descrição de dicionários, o DANE inclui o nome da variável, seu tipo ou formato e, para categorias codificadas, o código e o rótulo correspondente. A documentação deve estar relacionada à estrutura real da tabela: cada campo descrito corresponde a uma coluna e cada observação ou registro ocupa uma linha.

Não confunda o dicionário com um manifesto de entrega, que pode identificar arquivos, datas ou versões recebidas, nem com um guia de exportação, que explica como o arquivo foi gerado. Esses documentos podem se complementar, mas respondem a perguntas diferentes. O dicionário também não é o lugar para repetir linhas de dados nem para listar cada arquivo de uma pasta. Manter esses objetivos separados facilita as atualizações: altere a descrição quando uma regra ou um campo mudar e atualize as informações de entrega quando o pacote compartilhado mudar.

  • Dicionário: o que cada coluna significa e como interpretar seus valores.
  • Manifesto: quais arquivos fazem parte de uma entrega.
  • Guia de exportação: como o arquivo é obtido ou preparado.
O que documentar e o que deixar de fora

Modelo mínimo para cada coluna

Comece com uma linha de documentação para cada cabeçalho do CSV. Inclua o nome exato da coluna para que seja fácil relacionar a ficha ao arquivo. Acrescente uma descrição concreta, o tipo ou formato esperado, a unidade, se aplicável, os valores permitidos ou o vocabulário utilizado e se o campo admite ausência. Registre também outras regras, por exemplo, se um campo é calculado a partir de outros. Uma definição útil esclarece a interpretação, em vez de apenas reformular o nome. O [guia de procedimentos para registros administrativos do DANE](https://www.dane.gov.co/files/sen/registros-administrativos/cooperacionBID/peru/peru_procedimientos.pdf) descreve elementos de uma ficha por variável, como nome, tipo ou formato, código e rótulo, quando pertinente.

Evite deixar campos essenciais a critério do leitor. «Data» é genérico demais se for importante saber se ela indica o dia de criação ou de encerramento; «valor» é incompleto sem moeda ou unidade; «categoria» não explica quais opções são válidas. Se o conjunto ainda não tiver uma regra definida, indique que ela está pendente, em vez de apresentar uma suposição como norma. Mantenha as descrições breves, mas com detalhes suficientes para que seja possível tomar decisões sem consultar quem produziu o arquivo.

  • nome_coluna: igual ao cabeçalho do CSV.
  • significado: o que representa e, se ajudar, o que não representa.
  • tipo/formato: por exemplo, texto, inteiro ou data com formato definido.
  • unidade: por exemplo, unidades, quilogramas ou uma moeda especificada.
  • valores permitidos: códigos, rótulos ou vocabulário aplicável.
  • ausência: se é permitida e como é codificada.
  • regra: origem ou cálculo, quando o campo for derivado.

Exemplo fictício: códigos, valores nulos, datas e cálculos

Considere um arquivo fictício de acompanhamento de pedidos, sem dados pessoais. O campo «estado» poderia ser texto com os valores permitidos «aberto», «em_andamento» e «fechado», ou usar códigos numéricos. Se forem usados códigos, o dicionário deve associar cada um ao seu rótulo, por exemplo: 1 = aberto, 2 = em andamento, 3 = fechado. O exemplo não estabelece uma convenção universal: mostra por que a correspondência deve estar escrita e por que é conveniente manter a mesma codificação para o mesmo conceito em entregas relacionadas.

Para «data_fechamento», documente que é a data em que o pedido é fechado, o formato esperado e se pode ficar vazia enquanto o pedido estiver aberto. Se o horário for importante, especifique também o fuso horário ou a regra temporal utilizada; não deixe que leitores diferentes deduzam isso por conta própria. Para «valor_total», indique a moeda e se o campo é calculado a partir de outros valores. Se uma coluna calculada incluir arredondamento ou outra regra, descreva-a de forma operacional. Esses detalhes tornam o exemplo interpretável sem transformá-lo em uma norma para outros conjuntos de dados.

  • estado: 1 = aberto; 2 = em andamento; 3 = fechado.
  • data_fechamento: data de fechamento; ausência permitida enquanto o pedido não estiver fechado.
  • valor_total: quantia em uma moeda indicada; anote a regra de cálculo, se aplicável.
  • quantidade: número de unidades; não confunda uma quantidade igual a zero com um dado ausente.

Defina ausências, unidades e vocabulários

A distinção entre zero, vazio e desconhecido é fundamental. Zero pode ser um valor real; uma célula vazia pode significar ausência; e um código como «-1» poderia representar um dado não obtido, se assim tiver sido definido. Eles não são equivalentes. O [Guia de qualidade de dados abertos do datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/guia_calidad_de_datos_abiertos.pdf) indica que o zero deve ser representado como «0» e que um valor desconhecido ou não obtido deve ser explicado, especificando no dicionário o código utilizado. Se espaços em branco puderem ter várias interpretações, descreva-as explicitamente; o [Guia para a publicação de dados abertos do Datos Argentina](https://datosgobar.github.io/paquete-apertura-datos/pdf/anexo-II-guia-abiertos.pdf) também recomenda explicitar essas interpretações. Se os espaços em branco sempre indicarem ausência, documente essa regra sem inventar categorias adicionais.

Em campos categóricos, enumere as opções válidas e seus significados e use uma codificação consistente para conceitos equivalentes. Em campos numéricos, indique a unidade ou a moeda: «12» não basta para saber se se trata de peças, horas ou uma quantia em dinheiro. A [ficha de dados tabulares CSV do datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/cheat_sheet_csv_vf.pdf) recomenda documentar as unidades associadas a valores numéricos e manter uma codificação coerente. Em datas e horários, esclareça o formato e o fuso horário, quando pertinente, e descreva o evento registrado pelo campo. Essas precisões reduzem erros de leitura e integração, mas não garantem, por si só, que todos os valores do CSV cumpram as regras: ainda é necessário revisar o arquivo.

  • Diferencie o valor zero, a célula vazia e o código para desconhecido ou não obtido.
  • Explique se a ausência é permitida e em quais condições.
  • Indique unidade, moeda, formato e fuso horário quando forem relevantes.
  • Defina categorias e códigos com seus rótulos correspondentes.

Revise o CSV e o dicionário como uma única entrega

Antes de compartilhar, compare um a um os cabeçalhos do CSV com as fichas do dicionário: procure colunas não documentadas, nomes antigos e campos descritos que já não aparecem. Em seguida, confira os exemplos e os valores permitidos em relação aos dados reais. Se o dicionário afirmar que um campo aceita apenas três códigos, verifique se os valores observados correspondem a essa lista ou registre e resolva a exceção. Essa leitura conjunta permite detectar contradições que passam despercebidas quando cada arquivo é revisado separadamente.

Convém pedir a revisão de alguém que não tenha preparado os dados. Peça que essa pessoa explique o significado de uma coluna, como trataria uma célula vazia e qual unidade atribuiria a um número. Se precisar adivinhar, melhore a documentação. Mantenha uma cópia editável para revisões futuras e associe cada dicionário à entrega específica do CSV. Quando o esquema ou uma regra de significado mudar, atualize a documentação ao mesmo tempo; não confie que uma nota informal ou o nome de um arquivo permita reconstruir o contexto.

  • Verifique a correspondência exata entre os cabeçalhos e as fichas.
  • Compare códigos, unidades, formatos e exemplos com os dados.
  • Procure regras contraditórias sobre valores obrigatórios e ausências.
  • Registre qual versão do dicionário acompanha cada CSV.
  • Peça a alguém que não participou da preparação para interpretar alguns campos.

Referências e conservação da documentação

Estes guias fundamentam as recomendações sobre estrutura tabular, fichas por variável, códigos, unidades e ausências. Consulte as fontes para revisar suas convenções e aplicá-las de acordo com as necessidades do seu conjunto de dados:

Guarde o CSV e seu dicionário juntos ou em uma estrutura que deixe inequívoco a qual arquivo e versão a documentação corresponde. O Apification Cloud permite organizar arquivos e projetos em um espaço versionado, desenvolvido para compartilhamento; também permite criar e editar arquivos de escritório com o ONLYOFFICE dentro do Cloud. Isso pode ajudar a manter a documentação editável junto com os dados. Ao compartilhar, identifique claramente os dois elementos e a entrega a que pertencem. A ferramenta ajuda a organizar e compartilhar arquivos; definir o significado e revisar a coerência continuam sendo responsabilidades da equipe.

  • Guia de dados tabulares CSV, datos.gob.es: https://datos.gob.es/sites/default/files/doc/file/guia_csv_vf.pdf
  • Cheat sheet: dados tabulares CSV, datos.gob.es: https://datos.gob.es/sites/default/files/doc/file/cheat_sheet_csv_vf.pdf
  • Guia de qualidade de dados abertos, datos.gob.es: https://datos.gob.es/sites/default/files/doc/file/guia_calidad_de_datos_abiertos.pdf
  • Procedimentos para registros administrativos, DANE: https://www.dane.gov.co/files/sen/registros-administrativos/cooperacionBID/peru/peru_procedimientos.pdf
  • Guia para a publicação de dados abertos, Datos Argentina: https://datosgobar.github.io/paquete-apertura-datos/pdf/anexo-II-guia-abiertos.pdf
  • Nomeie os dois arquivos de forma que a relação entre eles fique clara.
  • Mantenha uma versão editável do dicionário junto com a entrega correspondente.
  • Use o histórico de versões para revisar ou recuperar versões anteriores quando necessário.

Perguntas frequentes

O dicionário de dados deve incluir uma linha para cada valor do CSV?

Não. Normalmente, ele documenta cada coluna e suas regras. Para uma coluna codificada, convém incluir a correspondência entre códigos e rótulos, mas não reproduzir todos os registros.

Como documento uma célula vazia?

Indique se ela representa ausência e o que isso significa naquele campo. Se puder ter mais de uma interpretação, descreva cada caso e como distingui-los. Não a equipare automaticamente a zero.

Posso usar uma planilha como dicionário?

Sim. Uma tabela editável é uma forma prática de manter uma ficha para cada coluna. O importante é definir os campos com clareza e fazer com que a documentação corresponda à versão do CSV entregue.

Um dicionário garante que o CSV cumpre suas regras?

Não. Ele explica as regras e facilita a interpretação, mas é preciso comparar o arquivo com a documentação. A revisão conjunta ajuda a encontrar discrepâncias e exceções.

Fontes e leituras

Documentação consultada para preparar este artigo.

Explore Apification

Artigos relacionados

Voltar ao blog