dg:Guia do make conf

Texto original: https://github.com/digital-guard/preserv/blob/main/docs/pt/man-makeConf.md

Os arquivos make_conf.yaml têm como finalidade principal a conversão automática para makefile, e, secundariamente, conversões para geração de "conteúdo esqueleto" do README e de e-mails do workflow de aprovação.

Resumo da ferramenta

Os dados recebidos de diferentes doadores apresentam diferentes formatos e estruturas. Na Digital-Guard, por outro lado, criamos uma estrutura padrão para que os dados "conversem" e sejam comparáveis entre si... A compatibilidade dos dados é um aspecto fundamental, mas não podemos devolver os dados para os doadores dizendo "coloque no formato padrão". É uma condição de trabalho que a Digital-Guard se propôs a enfrentar. Enfrentamos o desafio através da implementação de "motores de conversão", que são softwares que convertem dados de outros formatos para o formato e estrutura padronizados.

Outra condição é a preservação: os dados originais são guardados por 20 anos, e qualquer um que desejar, hoje ou no futuro, recuperar os dados, poderá fazê-lo.

Os makefiles rodam softwares padronizados (ex. shp2pgsql), com ampla comunidade de usuários de geoprocessamento e Unix, consolidados por mais de 10 anos de domínio público, garantindo reprodutibilidade da ingestão em banco de dados PostgreSQL+PostGIS.

JSONs de configuração WFS OpenAdressess podem ser convertidos para make_conf. Ver exemplos do estado de São Paulo no Brasil, https://github.com/openaddresses/openaddresses/tree/master/sources/br/sp

Formato

JSON e YAML são equivalentes, se precisar use ferramentas de conversão "JSON to YAML". A preferência por YAML é por ser mais "legível ao humano" (human readable), assim como mais fácil de interpretar no diff de cada novo commit do git. Adotamos o padrão YAML v1.2.2, que preserva sua compatibilidade sintática com a especificação de 2001, RFC 2822, e estende sua semântica para interpretadores JSON.

Estrutura e sintaxe mais comum

Os templates são flexíveis, mas as variantes são pouco usadas, de modo que a estrutura mais comum acaba servindo de referência para 90% dos casos. A estrutura a seguir é utilizada por exemplo em BR-pk046.

Primeiro nível, cabeçalho:

pkid: identificador local (país) do package, um número sequencial controlado por
pkversion: entre aspas o número de versão, "001" para que não seja depois seja convertido em decimal corretamente.
(bug do YAML que poderia ser corrigido no Python)
schemaId_input:

Primeiro nível, demais objetos:

files: lista dos arquivos preservados a serem submetidos a algum tipo de transformação para se tornarem úteis para os projetos-patrocinadores. Cada item da lista é contextualmente único e totalmente identificável.
layers: chaves definidoras de layers conforme convenções especificadas em ... Cada layer pode ter um ou mais arquivos como fonte, e dois layers diferentes podem ser oriundos de um mesmo arquivo (por exemplo OSM gera todos os layers).

A seguir cada subseção descritiva de segundo nível segue a nomenclatura da respectiva chave de primeiro nível.

files

Cada item da lista de arquivos é especificado da seguinte maneira:

-
- p: Identificador local do arquivo no arquivo de configuração
- file: nome de arquivo no formato "sha256.ext".
- name: nome livre, sugerindo conteúdos do arquivo.

...

layers

Comumente, cada layer é especificado pelas seguintes chaves:

layer: nome padronizado do layer, conforme tabela dos feature types.
- subtype: completeza do layer com relação a dados-core do sponsor: full, ext ou none. Dados complementares (cadastrais) aos dados-core são descritos pelos valores: cmpl, noid e none.
- method: método de conversão utilizado para a ingestão de file. Os mais comuns são shp2sql e ogr2ogr. Outros disponíveis são csv2sql e ogrWshp.
- p: identificador do arquivo seguido de letra identificadora do layer.
- file: referência ao identificador p de um dos itens da lista de arquivos files.
- sql_view: [OPCIONAL] query completa referenciando "FROM $(tabname)". Torna inócua select_sql.
- select_sql: [OPCIONAL] lista de nomes de coluna da tabela de referência do method. É obrigatória se sql_view não existir.
- orig_filename: nome do arquivo (ou arquivo de referência como no caso de shape) a ser utilizado pelo método de conversão.

...

Outras estruturas

(Avaliar se é o local correto) Além das opções mais comuns, outras podem ser utilizadas:

orig_subfilename: nome do arquivo para o caso de file possuir arquivo compactado dentro de arquivo compactado.
join_id: nome da coluna utilizada para correlacionar um layer e seu respectivo layer complementar (cadastral).
orig_ext: utilizada em algumas situações com o método ogr2ogr para indicar a extensão do arquivo.
method_opts: opções para os programas shp2pgsql (utilizado pelo método shp2sql) e xlsx2csv (utilizado por csv2sql na conversão de um arquivo xlsx para csv, quando combinado com orig_ext: .xlsx).
7z_opts: opções para o compactador de arquivos 7z utilizado na descompactação de dos arquivos listados em files.
srid: ou srid_local (???).
tabname: (obsoleta?)

Estrutura do arquivo commomFirst.yaml

O arquivo é utilizado para configurações de cada jurisdição ...

pg_io: ??? /tmp/pg_io
orig: ??? /var/www/dl.digital-guard.org
pg_uri: URI para conexão com base de dados (postgres://postgres@localhost)
pg_db: nome da base de dados.
sandbox: caminho de diretório temporário utilizado durante o processo de ingestão de dados.
thisTplFile_root: ??? Como foi centralizado em preserv, acho que essa chave se tornou obsoleta.

Commom files

Processamento

O processamento dos arquivos make_conf.yaml é feito pelo software run_mustache.py, escrito em python, utilizando templates Mustache. Os principais templates utilizados estão em src/maketemplates. Antes da renderização é incluído no arquivo make_conf.yaml o conteúdo do arquivo commomFirst.yaml, especifico para cada jurisdição.

... usando Mustache... usando

Semântica

Uso do makefile como ETL ...
Semântica dos dados-origem e dos dados gerados ... ver feature types.

Referências

Outros documentos A4A:

...

Casos análogos: