Skip to content

Latest commit

 

History

History
204 lines (148 loc) · 17.5 KB

Conventions.md

File metadata and controls

204 lines (148 loc) · 17.5 KB
Raw

Convenções

Nesta seção são descritas as convenções adotadas no projeto.

Apresentação e diretivas

O Projeto OSM-Stable-BR demanda a utilização de infraestrutura PostgreSQL, PostGIS e PostgREST, onde poderá, eventualmente, conviver com outros projetos OSM-Stable (no namespace adota-se o prefixo osms antes da sigla do país).

Não existem padrões muito rigoros no OSM, e diversas convenções, principalmente no que se refere às tags, podem variar de país para país. As ferramentas, tais como OSMose e Osm2pgsql são muito flexíveis tornando sua configuração complexa. Além disso algumas delas são conservadoras, não permitindo a adoção de tecnologias "modernas". A Osm2pgsql por exemplo se recusa a dar a opção JSONb.

No Projeto OSM-Stable adota-se a filosofia "Convention over configuration", e um modelo dados interno baseado em Osm2pgsql e representações JSONb controladas.

As funções de exportação de dados do OSM-Stable, para seu repositório git, também são padronizadas. Foram adotados os formatos GeoJSON para geometrias e CSV para dados cadastrais, com representação de ponto Geohash.

Referência estável

Os metadados da "cópia OSM Planet" ficam registrados no documento da raiz do repositório, brazil-latest.osm.md. Softwares de parsing e templating garantem a sua expressão consistente em JSON.

Nomes de banco de dados

Convenções para nomes e papeis nos bancos de dados. O Projeto OSM-Stable-BR demanda a utilização de infraestrutura PostgreSQL, PostGIS e PostgREST, onde poderá, eventualmente, conviver com outros projetos OSM-Stable (no namespace adota-se o prefixo osms). Além disso, do ponto de vista metodológico, é requerido certo grau de encapsulamento.

Tendo isso em vista, os nomes de bases (utilizados em CREATE DATABASE nome_de_uma_base) precisam ser controlados, respeitando-se as seguintes regras, finalidades e justificativas:

Banco Descrição Justificativas
osms0_lake Repositório tipo "lake" de preparo dos dados (ingestão, transformação e validação automática). Pode conter diversos países. Encapsulamento, faz papel de Data Lake para dados brutos (input "as is" do modelo legado) e VIEWS ou funções para exportação ao testing.
osms1_testing Repositório rigorosamente organizado, nele entram apenas dados do git branch de teste. Fase testing, para estabilização ("quarentena") e validação humana. Encapsulamento, faz papel "testing distribution", ou seja, permite que auditores avaliem os dados novos a tempo de fazer correções. Quando quando houver mais de um país, fará também papel de Data Warehouse.
O código "1" auxilia na manutenção e, quando preservado, na semântica de códigos (ex. porta PostgREST 3101).
osms2_stable Idem base osm2_testing, porém correspondendo à fase de produção. Todos os dados foram homologados, aceitos como "estáveis e qualificados". Requer isolamento, faz papel de entrega final para o uso em produção.
O código "2" auxilia na manutenção e, quando preservado, na semântica de códigos (ex. porta PostgREST 3102).

Nomes de schemas e tabelas

Na base osms0_lake são criados Schemas presentes em ambas bases, osms1_testing e osms2_stable:

  • public: objetos publicados na API do PostgREST.
    Não se trata portanto um "namespace de trabalho" como nas bases de dados PostgreSQL usuais, mas de um namespace crítico por afetar o usuário final e as convenções de acesso na API.
  • lib: funções de biblioteca de uso geral, mas que não se deve misturar ao public.
  • working: temporária ou para tarefas específicas.
  • datasets: tabelas menores com datasets relevantes, tais como datasets.ok.org.br/city-codes.
  • stable: todas as tabelas e funções dependentes de tabelas do Projeto OSM-Stable.

Tabelas principais do schema public:

  • ... ver convenções de publicação final. Datasets menores podem ser publicados diretamente em public

Tabelas principais do schema datasets:

  • ...

Tabelas principais do schema stable:

  • ...

Tabelas do schema osm: geometrias do OSM, podem também vir com o prefixo "planet_osm_".

  • osm.br_point: todos os pontos definidos no OSM, de endereçamento ou não.
  • osm.br_line: linhas de hidrografia, vias secundárias, trilhas, etc.
  • osm.br_polygon: polígonos de jurisdições (municípios e estados), bacias hidrográficas e outros.
  • osm.br_roads: ruas, rodovias, ferrovias, etc.

Prefixos nos nomes, esquemas public e stable:

  • mvw_*: prefixo de MATERIALIZED VIEW
  • vwDDdesc_*: prefixo de VIEW, com DD dois dígitos e desc um menemônico descritivo, antes do nome de tabela ou de relacionamento.

Nomes e API no schema public

Os datasets expostos através do schema public são tabelas e views de menor volume. Dados GeoJSON e acesso a tabelas maiores deve ser realializado através de funções, que na API PostgREST respondem pelo namespace rpc.

As APIS estão atualmente configuradas nos seguintes endpoints:

  • api.addressforall.org/osms1: API PostgREST da base osms1_testing. Tabelas do schema public podem ser recuperadas em formato JSON como /osms1/{nomeTabela} ou /osms1.json/{nomeTabela}; ou recuperadas em formato CSV por /osms1.csv/{nomeTabela}.
  • api.addressforall.org/osms2: API PostgREST da base osms2_stable. Item API /osms1.
  • api.addressforall.org/osms: endpoint descritor da API da base osms2_stable para funções mais requisitadas. Por exemplo /osms.json/br/SP/Campinas retorna todos os metadados de Campinas, enquanto /osms.geojson/br/SP/Campinas o seu mapa.

Jurisdições e nomenclatura

Diferentes áreas do mundo pertencem a diferentes países, e o mapeamento OSM sobre uma determinada área é realizado principalmente pela comunidade daquele país. As convenções toponímicas, a língua e as leis de demarcação do território são fixadas pelo pais que detém a jurisdição sobre aquele território, ou as jurisdições tais como estados e municípios, determinadas pela normas do país.

No OSM as jurisdições são marcadas pela tag boundary=administrative, e seu nível hierárquico pela key admin_level. Apesar do nome de cada unidade administrativa ser fixado adequadamente pela key name ou official_name, não há uma convenção para uma versão simplificada do nome, mais útil para a referência em URLs e nomes de arquivo.

No projeto OSM-Stable estão sendo adotadas as convenções de transcrição ortográfica da norma URN LEX. Além disso a adoção de qualquer outra convenção, no escopo do projeto, prioriza as normas de autoridades da jurisdição.

No Brasil a URN LEX foi officialmente adotada a partir de 2008, quando entrou em vigor o padrão LexML do Brasil. Nomes de jurisdição são representados sem acento, hifens e apóstrofes ou preposições. Nomes como Machadinho D'Oeste (RO) e Pingo-d'Água (MG) ficam normalizados para "br;ro;machadinho.oeste" e "br;mg;pingo.agua" respectivamente. Na convenção OSM-Stable esses nomes são mapeados de forma reversível para CamelCase e siglas em maiúsculas, em path Unix: "BR/RO/MachadinhoOeste" e "BR/MG/PingoAgua". A função responsável por esta conversão de nomes próprios é a stable.std_name2unix(). Exemplos:

uf name ibge_id path
AM Boca do Acre 1300706 AM/BocaAcre
AC Brasiléia 1200104 AC/Brasileia
RO Alta Floresta D'Oeste 1100015 RO/AltaFlorestaOeste
RO Colorado do Oeste 1100064 RO/ColoradoOeste
RO Espigão D'Oeste 1100098 RO/EspigaoOeste
RO Guajará-Mirim 1100106 RO/GuajaraMirim
RO Ji-Paraná 1100122 RO/JiParana
RO Alto Alegre dos Parecis 1100379 RO/AltoAlegreParecis

Formatos CSV e GeoJSON

A ideia do repositório git do Projeto OSM-Stable é ser um pouco também de uma interface para auditoria e visualização dos dados, principalmente para leigos (não-nerds). E essa auditoria (ou visualização) precisa ser praticável por humanos ("human readable") tanto via Web como via editores e visualizadores de "texto bruto", o assim-chamado TXT (padrão plain text com caracters UTF-8).

Em outras palavras, o código-fonte dos dados, que é escrito em formatos abertos tais como JSON, XML ou CSV (todos em substrato TXT) precisam ser legíveis para humanos e máquinas.

Neste sentido cede-se a demandas mais específicas da infraestrutura TXT e Web do git:

  1. As operações git (pull/push) não podem gerar falsas atualizações, comprometendo o repositório. Por exemplo o acréscimo de um espaço em branco entre palavras de um texto em português não altera a informação, portanto causa falsa atualização se for aceito no git. Para evitar o problema são adotadas as seguintes convenções:

    1.1. O "sistema operacional de referência" é o Linux, onde é adotado como padrão de newline apenas caracter de LF (diferente do Windows que é CRLF). Para que o próprio git acate a recomendação, usar o arquivo .gitattributes.
    Na prática isso significa que o git irá converter automaticamente as sequências \r\n (CR LF), postadas pelo colaborador Windows, para \n (LF).

    1.2. Não adotar atributo CRS do GeoJSON: a interface Github só aceita o default dado pela omissão, apesar de ser equivalente à declaração explícita de EPSG:4326 (ou WGS84 ou urn:ogc:def:crs:EPSG::4326), gerada inclusive como option no ST_AsGeoJSON() do PostGIS. Omitir o CRS parece ser uma recomendação geral, por exemplo da rfc5870.

    1.3. Adotar saídas "JSON pretty" conforme padrão PostgreSQL, jsonb_pretty(). É ligeiramente gastona por encher de newlines e espaços... Mas com ela o git diff funciona (!) e usuários não acostumados com JSON (sem plugin no browser) conseguem visualizar o arquivo e as eventuais alterações.

  2. Para evitar centenas ou milhares de arquivos numa mesma pasta do repositório, "poluindo" e dificultando o acesso humano através da navegação por pastas, são adotadas as seguintes convenções:

    2.1. Uma pasta por Estado, expresso por sua abreviação de UF (unidade federal).

    2.1.1. A pasta contém apenas README.me e (opcional) o arquivo GeoJSON, estado.geojson, com mapfeature controlada (polygon com dados da relation da região administrativa).

    2.2. Uma pasta por município, expresso por seu "nome lex" em formato Camel. Por exemplo "São Bernardo do Campo" em URN LEX de jurisdição é sp;sao.bernardo.campo que em Camel e adaptada para path fica SP/SaoBernardoCampo.

    2.2.1. A pasta contém README.me, o arquivo GeoJSON, municipio.geojson, com mapfeature controlada (polygon com dados da relation da região administrativa), e subpastas para map features "oficiais", definidas e controladas pela equipe curadora do município.

  3. Para respeitar "o grande público", que não vai sequer usar git GUI desktop é preciso confiar o repositório a uma boa "git Web-based Use Interface" (git WUI), que atualmente é a interface Web Github. Convenções adotadas para garantir consistência com a git WUI:

    3.1. No JSON de properties GeoJSON, priorizar as chave-valores de primeiro nível. Justificativa: na visualização do GeoJSON do Github apenas atributos de primeiro nível são visíveis ao se clicar num polígono.

    3.2. ...

Inicialmente, devido à demanda para prefeituras e aplicações de roteamento, apenas:

  • polígonos de delimitações administrativa (cidades e bairros oficiais)
  • linhas de logradouros
  • pontos de endereçamento (entrada principa do lote ou portão de entidade registrada na Wikidata - parques, hospitais, etc.).

Exemplo em planilha amigável com alguns descritores de ponto de Curitiba

Elementos do GeoJSON de município

O município é um sh:GeoShape expresso em formato GeoJSON, minimamente contendo os seguintes elementos JSON:

Chave Valor
id identificador (sh:identifier) alfanumérico, letra representando o OSM-type (W=Way, R=Relation).
bbox array com coordenadas da diagonal do retângulo envolvente, BBOX padrão do GeoJSON, válido como sh:box. Canto de baixo depois canto de cima, ambos Lng-Lat.
type Typo de geometria (line, polygon, collection, etc.).
properties objeto JSON com metadados do município.
coordinates array de arrays, contendo um sh:polygon.

Os valores de primeiro nível válidos como properties do município são:

Chave Significado ou valor esperado
name Nome oficial do município, sh:name.
type Valor constante, definindo osm:tag:type=boundary.
source osm:​key:source, indicando o autor do dado (em geral IBGE).
boundary Valor constante, definindo osm:tag:boundary=administrative.
wikidata osm:​key​:wikidata, contendo identificador Wikidata.
wikipedia osm:​key​:wikipedia, contendo rótulo do município na Wikipedia da língua portugesa, em geral pt:Nome do Município.
admin_level osm:​key​:admin_level contendo sempre o valor "8", exceto para Brasília.
IBGE:GEOCODIGO osm​:​key​:​IBGE:GEOCODIGO contendo o número do município no padrão IBGE.
members objeto JSON definindo, através de arrays, os identificadores OSM dos componentes (map features Node, Way ou Relation) que se juntaram para formar a geometria.

Exemplo de members:

        "members": {
            "n": {
                "admin_centre": [
                    415523067
                ]
            },
            "w": {
                "outer": [
                    43958163,
                    220383175,
                    242892566,
                    372374865,
                    372374871,
                    372374880,
                    372374883,
                    372374884
                ]
            }
        }

Na representação interna do banco de dados pode ainda conter, como cache para otimizar velocidade na auditoria, as chaves n_md5 e w_md5 para controle de casos duplicados.

Ver exemplo completo de Santa Cruz de Minas. A visualização do mapa deve permitir também a visualização dos atributos, através por exemplo de clique sobre o polígono, e minimamente os atributos do primeiro nivel da árvore JSON.