Documentos y datos

Diccionario de datos para un CSV: cómo documentar cada columna

Un CSV puede abrirse sin errores y seguir siendo difícil de interpretar. Aprende a documentar nombres, tipos, códigos, ausencias, unidades y fechas con una plantilla práctica.

Apification
Ejemplo de diccionario de datos para CSV con columnas, tipos, códigos y reglas de ausencia

Un CSV legible no siempre es un CSV interpretable

Un archivo CSV puede abrirse correctamente en una hoja de cálculo y, aun así, dejar preguntas básicas sin respuesta: ¿qué representa cada columna?, ¿un valor como «3» es una cantidad o un código?, ¿una celda vacía significa que no aplica o que el dato se desconoce? El formato organiza valores en filas y columnas, pero no explica por sí solo el significado de cada campo ni si debe estar completo. La [Guía de datos tabulares CSV de datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/guia_csv_vf.pdf) señala que CSV no incluye un mecanismo para indicar el tipo de dato de una columna o si sus valores deben ser obligatorios. Esa falta de contexto puede provocar que dos equipos interpreten de manera distinta el mismo conjunto de datos.

El diccionario de datos resuelve esa ambigüedad con una descripción por columna y reglas explícitas de interpretación. No sustituye al CSV ni corrige sus datos: acompaña la entrega para que quien la recibe pueda entenderla y usarla con criterios consistentes. Es especialmente útil cuando el archivo pasa entre áreas, se integra en otro sistema o se actualiza con frecuencia. La meta práctica es que una persona que no participó en la creación del archivo pueda reconocer qué significa cada valor y qué hacer ante una excepción.

  • Si una columna contiene códigos, no presupongas que su significado es evidente.
  • Si un dato puede faltar, especifica qué representa cada forma de ausencia.
  • Si una cifra tiene unidad, moneda o escala, documéntala junto al campo.
Un CSV legible no siempre es un CSV interpretable

Qué documenta y qué queda fuera

El diccionario describe el contenido: nombres de variables, significado, tipo o formato esperado, unidades y, cuando corresponda, valores codificados con sus etiquetas. También puede indicar si un campo admite ausencia y cómo interpretar un valor nulo. Por ejemplo, decir que «estado» usa códigos no basta: hay que identificar qué representa cada código. El DANE incluye en su descripción de diccionarios el nombre de la variable, su tipo o formato y, para categorías codificadas, el código y la etiqueta correspondiente. La documentación debe relacionarse con la estructura real de la tabla: cada campo descrito corresponde a una columna y cada observación o registro ocupa una fila.

No lo confundas con un manifiesto de entrega, que puede identificar archivos, fechas o versiones recibidas, ni con una guía de exportación, que explica cómo se generó el archivo. Esas piezas pueden complementarse, pero responden preguntas diferentes. El diccionario tampoco es el lugar para repetir filas de datos ni para listar cada archivo de una carpeta. Mantener estos objetivos separados facilita las actualizaciones: cambia la descripción cuando cambia una regla o un campo, y actualiza la información de entrega cuando cambia el paquete compartido.

  • Diccionario: qué significa cada columna y cómo interpretar sus valores.
  • Manifiesto: qué archivos forman parte de una entrega.
  • Guía de exportación: cómo se obtiene o prepara el archivo.
Qué documenta y qué queda fuera

Plantilla mínima para cada columna

Empieza con una fila de documentación por cada encabezado del CSV. Incluye el nombre exacto de la columna para que sea fácil relacionar la ficha con el archivo. Añade una descripción concreta, el tipo o formato esperado, la unidad si aplica, los valores permitidos o el vocabulario que utiliza y si el campo admite ausencia. Si hay reglas adicionales —por ejemplo, que un campo se calcula a partir de otros— regístralas también. Una definición útil aclara la interpretación, no se limita a reformular el nombre. La [guía de procedimientos para registros administrativos del DANE](https://www.dane.gov.co/files/sen/registros-administrativos/cooperacionBID/peru/peru_procedimientos.pdf) describe elementos de una ficha por variable como el nombre, tipo o formato, código y etiqueta cuando corresponda.

Evita dejar campos esenciales a criterio del lector. «Fecha» es demasiado general si importa saber si se registra el día de creación o el de cierre; «importe» es incompleto sin moneda o unidad; «categoría» no explica qué opciones son válidas. Si el conjunto todavía no tiene una regla fija, indícalo como pendiente en vez de presentar una suposición como norma. Mantén las descripciones breves, pero con suficiente detalle para tomar decisiones sin consultar a quien produjo el archivo.

  • nombre_columna: igual al encabezado del CSV.
  • significado: qué representa y, si ayuda, qué no representa.
  • tipo/formato: por ejemplo, texto, entero o fecha con formato definido.
  • unidad: por ejemplo, unidades, kilogramos o una moneda especificada.
  • valores permitidos: códigos, etiquetas o vocabulario aplicable.
  • ausencia: si se permite y cómo se codifica.
  • regla: origen o cálculo, cuando el campo sea derivado.

Ejemplo ficticio: códigos, nulos, fechas y cálculos

Considera un archivo ficticio de seguimiento de pedidos, sin datos personales. El campo «estado» podría ser texto con los valores permitidos «abierto», «en_proceso» y «cerrado», o utilizar códigos numéricos. Si se usan códigos, el diccionario debe asociar cada uno a su etiqueta, por ejemplo: 1 = abierto, 2 = en proceso, 3 = cerrado. El ejemplo no establece una convención universal: muestra por qué la correspondencia debe estar escrita y por qué conviene mantener la misma codificación para el mismo concepto en entregas relacionadas.

Para «fecha_cierre», documenta que es la fecha en que se cierra el pedido, el formato esperado y si puede estar vacía mientras siga abierto. Si la hora importa, especifica también la zona horaria o la regla temporal que se usa; no dejes que distintos lectores la deduzcan. Para «importe_total», indica moneda y si el campo se calcula a partir de otros valores. Si una columna calculada incluye redondeo u otra regla, descríbela de forma operativa. Estos detalles hacen que un ejemplo sea interpretable sin convertirlo en una norma para conjuntos distintos.

  • estado: 1 = abierto; 2 = en proceso; 3 = cerrado.
  • fecha_cierre: fecha de cierre; ausencia permitida mientras el pedido no esté cerrado.
  • importe_total: cantidad en una moneda indicada; anotar la regla de cálculo si procede.
  • cantidad: número de unidades; no confundir una cantidad igual a cero con un dato ausente.

Define las ausencias, unidades y vocabularios

La distinción entre cero, vacío y desconocido es fundamental. Un cero puede ser un valor real; una celda vacía puede significar ausencia; y un código como «-1» podría representar un dato no obtenido, si así se ha definido. No son equivalentes. La [Guía de calidad de datos abiertos de datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/guia_calidad_de_datos_abiertos.pdf) indica que el cero debe representarse como «0» y que un valor desconocido o no obtenido debe explicarse, especificando el código utilizado en el diccionario. Si los espacios en blanco pueden tener varias interpretaciones, descríbelas de forma explícita; la [Guía para la publicación de datos abiertos de Datos Argentina](https://datosgobar.github.io/paquete-apertura-datos/pdf/anexo-II-guia-abiertos.pdf) también recomienda explicitar esas interpretaciones. Si siempre indican ausencia, documenta esa regla sin inventar categorías adicionales.

En campos categóricos, enumera las opciones válidas y su significado, y utiliza una codificación consistente para conceptos equivalentes. En campos numéricos, indica unidad o moneda; «12» no basta para saber si se trata de piezas, horas o una suma monetaria. La [ficha de datos tabulares CSV de datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/cheat_sheet_csv_vf.pdf) recomienda documentar las unidades asociadas a valores numéricos y mantener una codificación coherente. En fechas y horas, aclara formato y zona horaria cuando corresponda, y describe qué evento registra el campo. Estas precisiones reducen errores de lectura y de integración, pero no garantizan por sí solas que todos los valores del CSV cumplan las reglas: la revisión del archivo sigue siendo necesaria.

  • Distingue valor cero, celda vacía y código de desconocido o no obtenido.
  • Explica si la ausencia está permitida y bajo qué condiciones.
  • Indica unidad, moneda, formato y zona horaria cuando sean relevantes.
  • Define categorías y códigos con sus etiquetas correspondientes.

Revisa el CSV y el diccionario como una sola entrega

Antes de compartir, compara uno por uno los encabezados del CSV con las fichas del diccionario: busca columnas sin documentar, nombres antiguos y campos descritos que ya no aparecen. Revisa después los ejemplos y valores permitidos contra los datos reales. Si el diccionario afirma que un campo solo admite tres códigos, comprueba que los valores observados correspondan a esa lista o registra y resuelve la excepción. Esta lectura conjunta permite detectar contradicciones que pasan inadvertidas al revisar cada archivo por separado.

Conviene hacer una revisión con alguien que no haya preparado los datos. Pídele que explique qué significa una columna, cómo trataría una celda vacía y qué unidad asignaría a una cifra. Si necesita adivinar, mejora la documentación. Conserva una copia editable para futuras revisiones y vincula cada diccionario a la entrega concreta del CSV. Cuando cambia el esquema o una regla de significado, actualiza la documentación al mismo tiempo; no confíes en que una nota informal o un nombre de archivo permita reconstruir el contexto.

  • Comprobar correspondencia exacta entre encabezados y fichas.
  • Contrastar códigos, unidades, formatos y ejemplos con los datos.
  • Buscar reglas contradictorias sobre valores obligatorios y ausencias.
  • Registrar qué versión del diccionario acompaña a cada CSV.
  • Pedir a una persona ajena a la preparación que interprete algunos campos.

Referencias y conservación de la documentación

Estas guías respaldan las recomendaciones sobre estructura tabular, fichas por variable, códigos, unidades y ausencias. Consulta las fuentes para revisar sus convenciones y aplicarlas de acuerdo con las necesidades de tu conjunto de datos:

Guarda el CSV y su diccionario juntos o en una estructura que deje inequívoco qué documentación corresponde a cada archivo y versión. Apification Cloud permite organizar archivos y proyectos en un espacio versionado diseñado para compartir; también permite crear y editar archivos de oficina con ONLYOFFICE dentro de Cloud. Esto puede servir para mantener editable la documentación junto con los datos. Al compartir, identifica claramente ambos elementos y la entrega a la que pertenecen. La herramienta ayuda a organizar y compartir archivos; la definición del significado y la revisión de coherencia siguen siendo responsabilidad del equipo.

  • Guía de datos tabulares CSV, datos.gob.es: https://datos.gob.es/sites/default/files/doc/file/guia_csv_vf.pdf
  • Cheat sheet: datos tabulares CSV, datos.gob.es: https://datos.gob.es/sites/default/files/doc/file/cheat_sheet_csv_vf.pdf
  • Guía de calidad de datos abiertos, datos.gob.es: https://datos.gob.es/sites/default/files/doc/file/guia_calidad_de_datos_abiertos.pdf
  • Procedimientos para registros administrativos, DANE: https://www.dane.gov.co/files/sen/registros-administrativos/cooperacionBID/peru/peru_procedimientos.pdf
  • Guía para la publicación de datos abiertos, Datos Argentina: https://datosgobar.github.io/paquete-apertura-datos/pdf/anexo-II-guia-abiertos.pdf
  • Nombre ambos archivos de forma que su relación sea clara.
  • Conserve una versión editable del diccionario junto a la entrega correspondiente.
  • Use el historial de versiones para revisar o recuperar versiones anteriores cuando sea necesario.

Preguntas frecuentes

¿El diccionario de datos debe incluir una fila por cada valor del CSV?

No. Normalmente documenta cada columna y sus reglas. Para una columna codificada, sí conviene incluir la correspondencia entre códigos y etiquetas, pero no reproducir todos los registros.

¿Cómo documento una celda vacía?

Indica si representa ausencia y qué significa en ese campo. Si puede tener más de una interpretación, describe cada caso y cómo distinguirlo. No la equipares automáticamente con cero.

¿Puedo usar una hoja de cálculo como diccionario?

Sí. Una tabla editable es una forma práctica de mantener una ficha por columna. Lo importante es que los campos estén definidos con claridad y que la documentación corresponda a la versión del CSV entregado.

¿Un diccionario garantiza que el CSV cumple sus reglas?

No. Explica las reglas y facilita la interpretación, pero hay que contrastar el archivo con la documentación. La revisión conjunta ayuda a encontrar discrepancias y excepciones.

Fuentes y lecturas

Documentación consultada para elaborar este artículo.

Explora Apification

Artículos relacionados

Volver al blog