Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Criar definição de identificador universal para entidades representadas nos datasets #182

Open
turicas opened this issue Mar 19, 2020 · 6 comments
Assignees

Comments

@turicas
Copy link
Owner

turicas commented Mar 19, 2020

Problema

Necessidade de um identificador universal único (UUID) para cada entidade representada nos datasets do Brasil.IO. Entidades podem ser: empresas, pessoas, candidaturas etc. A falta de um UUID traz problemas como:

  • A necessidade de filtrar por vários campos ao mesmo tempo (que mudam de dataset para dataset)
  • Dificuldade de buscar em mais de um dataset
  • Dificuldade de gerar o ID offline para consultas externas
  • dentre outras

Atualmente utilizamos o dataset documentos-brasil para fazer essa desambiguação, porém ele não resolve completamente o problema, além de ser de difícil manutenção.

Solução

UUID versão 5 (hash SHA1, usando o namespace OID ou o URL -- ainda a definir), com prefixos de nomes estabelecidos pelo Brasil.IO (ou URLs diretamente), que controlarão a versão e o tipo de entidade.

Referências:

Exemplo em Python (URL)

import uuid

# Pessoa jurídica: 8 primeiros dígitos do CNPJ
# company
banco_do_brasil = uuid.uuid5(uuid.NAMESPACE_URL, "https://id.brasil.io/v1/company/00000000")

# Pessoa jurídica (matriz/filial): 14 dígitos do CNPJ
# company-branch
banco_do_brasil_filial_cajazeiras = uuid.uuid5(uuid.NAMESPACE_URL, "https://id.brasil.io/v1/company-branch/00000000009903")

# person
# Pessoa física: 6 dígitos do CPF ***111111** + nome completo em maiúsculas sem acento (slugified)
pessoa = uuid.uuid5(uuid.NAMESPACE_URL, "https://id.brasil.io/v1/person/111111-JOSE-CARLOS-DA-SILVA")

Nota: talvez o primeiro nome + 6 dígitos não sejam suficientes para a unicidade desse objeto (exemplo: 5,7 milhões de brasileiros possuem o nome José e não temos como garantir que os CPFs deles estarão espalhados uniformemente).

Exemplo em Python (OID)

import uuid

# Pessoa jurídica: 8 primeiros dígitos do CNPJ
# company
banco_do_brasil = uuid.uuid5(uuid.NAMESPACE_OID, "brasil.io/v1/company/00000000")

# Pessoa jurídica (matriz/filial): 14 dígitos do CNPJ
# company-branch
banco_do_brasil_filial_cajazeiras = uuid.uuid5(uuid.NAMESPACE_OID, "brasil.io/v1/company-branch/00000000009903")

# person
# Pessoa física: 6 dígitos do CPF ***111111** + nome completo em maiúsculas sem acento (slugified)
pessoa = uuid.uuid5(uuid.NAMESPACE_OID, "brasil.io/v1/person/111111-JOSE-CARLOS-DA-SILVA")

Implementação

Além do UUID, poderíamos armazenar um título que representa aquele objeto. O título poderia ser o nome da entidade (ou uma categoria) + algum identificador do objeto (não necessariamente único), por exemplo. Exemplos possíveis:

  • Candidato a deputado Fulano de Tal
  • Notebook SN: XXXXX
  • Pessoa: Cicrano da Silva

Na base de dados poderíamos ter os seguintes campos:

  • UUID
  • Name (brasil.io/versao/entidade/id)
  • Versão do UUID
  • Entidade
  • ID
  • Título
  • Texto (para FTS)
@turicas turicas self-assigned this Mar 19, 2020
turicas added a commit that referenced this issue Mar 20, 2020
@reichaves
Copy link

Olá
Parabéns Turicas!
Então o processo para uma base de dados seria assim?

1 - Captura necessária (download, webscraping, LAI etc.)

2 - Avaliação se contém os campos CNPJ, CPF, CPF mascarado, nome da entidade (empresa ou pessoa física), data de atualização, origem dos dados

3 - Se existirem pelo menos os campos CNPJ ou CPF mascarado+nome completo é possível prosseguir, caso contrário reavaliar se há como melhorar os campos da base de dados

4 - Executar funções de limpeza na base dados, como para padronizar formato de campos

5 - Criar as rotinas de código para ler cada linha/coluna da base de dados que vão preencher as novas colunas do UUID a partir de captura de informações

6 - Adicionar na base de dados as colunas de UUID (UUID, Name (brasil.io/versao/entidade/id), Versão do UUID, Entidade, ID, Título, Texto (para FTS))

7 - Executar as rotinas de 5 para preencher as novas colunas de UUID

8 - Testes finais de validação da base

@dschwabe
Copy link

dschwabe commented Mar 25, 2020

Nós discutimos bastante no SLNP como lidar com esta questão de identificadores e identidades.
Chegamos à conclusão que seria útil termos um serviço de gerenciamento de identidades para uma mesma entidade, nas várias fontes de dados. Um primeiro protótipo deste serviço foi feito em Mongo DB, para ser usado internamente no projeto, e tb para apoiar o compartilhamento entre diversos provedores de dados que porventura tivessem interesse em se ligar ao SLNP, e vice versa.

N sei se vc conhece o Wikidata; lá, muitas entidades possuem uma seção de links para outras bases (“Identifiers", veja p. Jair Bolsonaro) - demora um pouco p carregar). O id dele no Wikidata é Q10304982, e através dos links (chamados propriedades no Wikidata) do tipo "Identifer", vc obtém as demais identidades em outros serviço. Por exemplo, a propriedade Brazilian federal deputy ID P7480) te dá o ID dele no site da Câmara dos Deputados; uma outra propriedade dá a URL do site onde este id vale. Esta propriedade P7480 é do tipo Wikidata property for an identifier (Q19847637) , que indica que elá é um identificador.

Este modelo do Wikidata é muito granular, e vem do objetivo deles de serem muito gerais.
O que pensamos seria algo com efeito similar, mas muito mais simples, talvez com um escopo menos geral do que o Wikidata mas que serviria aos nossos propósitos, e acho que tb ao CruzGrafos.

A vantagem é que vc pode manter esta tabela separadamente de qq uma das outras bases, e tornar a correspondência entre o id no Cruza Grafos e os demais ids pública ou não, conforme o desejado.

Se (ou talvez, quando) interessar, posso enviar um rascunho que fizemos descrevendo o serviço

@turicas
Copy link
Owner Author

turicas commented Mar 31, 2020

Talvez a documentação de https://www.doi.org/ possa gerar alguma ideia.

@dschwabe
Copy link

dschwabe commented Mar 31, 2020

Não sei ao certo qual o problema que vc está endereçando..
Se vc esta considerando a questão de ter URL/URIs unicas, a abordagem que pensamos no SLNP foi de gerar um id único interno (tipo UUID), e manter a correspondencia com o id externo, que pode nem ser uma URI.
Sempre haverá um problema de deduplicação qdo a fonte externa não tiver uma chave única (pe.x, Nome).
Vc tem algo particular em mente?

@turicas
Copy link
Owner Author

turicas commented Apr 2, 2020

Vc tem algo particular em mente?

Não, a ideia era só ler a doc deles para ter referências e confirmar se o caminho que estamos seguindo é o melhor (não necessariamente para usá-los).

@dschwabe
Copy link

dschwabe commented Apr 2, 2020 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants