Formato data package

Introdução ao formato

Data packages vs. Tabular Data Packages

O que compõe uma data package?

A melhor forma de começar é analisar uma data package existente, como a das datas das eleições. As partes fundamentais a reter são:

• O diretório data/, que contém um ou mais ficheiros CSV e/ou JSON
• O ficheiro datapackage.json, que descreve todos os metadados da data package em formato JSON
• O ficheiro README.md, em formato Markdown, com informação para seres humanos sobre as fontes de informação, limitações do conteúdo e outros pormenores relevantes.

Recursos

• Boas práticas de packaging

Documentação

README.md

Para além dos dados e metadados, que servem principalmente para ser entendidos e processados por computadores, existe a necessidade de acrescentar informação para as pessoas que acederão e utilizarão a data package.

Para isso, inclui-se em cada data package um ficheiro README.md, escrito em formato MarkDown, com toda a informação relevante que importa transmitir a quem use estes dados.

Não existe uma norma definida no standard das data packages sobre como estruturar o README. Na Central de Dados optámos por definir alguns pontos a incluir nos README de todas as data packages que publicamos.

• Introdução -- descrição de uma ou duas frases sobre os conteúdos da data package. Pormenores de utilização são colocados na secção Notas.
• Fontes -- uma listagem completa das fontes de informação usadas.
• Notas -- detalhes que seja oportuno mencionar sobre o conteúdo e utilização dos dados.
• Obtenção -- breve descrição técnica dos processos necessários para criar a data package: bibliotecas usadas, links para scrapers e outras referências técnicas.
• Limitações -- lacunas, omissões e outros pormenores em falta que importe mencionar: se um dataset está limitado no tempo, ou se existem campos que não são fiáveis ou completos.
• Licença -- a licença de utilização sob a qual o dataset é disponibilizado. Na Central de Dados, usamos as licenças CC-BY e CC-BY-SA. Basta a indicação da licença com o respetivo link.
• Edição -- a lista de pessoas envolvidas na edição dos dados e da data package. Os nomes dos autores podem ser acompanhados do link para a sua página pessoal.

Metadados

Toda a informação da data package é integrada no ficheiro datapackage.json. Este ficheiro pode ser automaticamente criado com o comando dpm init, mas deve ser cuidadosamente revisto para assegurar que não falta nada.

Campos para os metadados

Segue-se uma explicação dos campos que importa preencher, juntamente com exemplos do que colocar em cada um.

• name:
  • Exemplo: parlamento-registos_interesses
• title:
  • Exemplo: Registos de interesses dos deputados
• description
  • Exemplo: Registos de interesses dos deputados da AR desde 2005
• homepage: URL da Central de Dados para esta data package
  • Exemplo: http://centraldedados.pt/datasets/parlamento-registos_interesses
• version:
  • Exemplo: 0.2.0
• repository: URL onde pode ser encontrado o repositório git da data package.
  • Exemplo: git://....
• sources: Lista de uma ou mais fontes de informação. Ver abaixo para o formato.
• license:
  • Open Database License: OdBL
  • Public Domain Database License: PDDL
• resources: Detalhes sobre os ficheiros de dados incluídos. Ver abaixo para o formato.

Resources:

• name:
• path:
• format:
• mediatype:
• bytes:
• schema: fields -> name, type, description

Sources: