prez

Préz

Prez é uma estrutura de API de dados vinculados configurável que fornece perfis de dados do Knowledge Graph de acordo com o padrão Negociação de conteúdo por perfil.

Onde está a IU?

Prez fornece apenas dados - geralmente RDF, mas pode ser GeoJSON, XML etc. - e fornece uma forma especial de RDF que inclui rótulos para todos os objetos e predicados que Prez pode encontrar em seu banco de dados.

Se você deseja uma UI que possa renderizar o RDF rotulado do Prez como HTML e outros widgets gráficos sofisticados, consulte a UI do Prez.

Conteúdo

• Instalação
• Configuração
• Correndo
• Serviço de redirecionamento
• Validação de dados
• Contato
• Contribuindo
• Licença

Instalação

Para obter uma cópia do Prez no seu computador, execute:

git clone https://github.com/RDFLib/prez

Prez é desenvolvido com Poetry, uma ferramenta de empacotamento e dependência Python. Poetry apresenta todas as dependências do Prez (outros pacotes Python) no arquivo pyproject.toml localizado no diretório raiz do projeto.

Para instalar as dependências do Python, execute:

poetry install

Nota: Poesia deve estar instalada no sistema. Para verificar se você tem o Poetry instalado, execute poetry --version . Para dicas sobre como instalar e gerenciar grupos de dependências específicos, verifique a documentação.

Pontos finais

Prez oferece os seguintes endpoints:

Pontos finais principais

Ponto final	MT padrão
/	texto/anot+tartaruga
/docs	texto/html
/catalogs/{catalogId}	texto/anot+tartaruga
/catalogs/{catalogId}/coleções	texto/anot+tartaruga
/catalogs/{catalogId}/collections/{recordsCollectionId}	texto/anot+tartaruga
/catalogs/{catalogId}/collections/{recordsCollectionId}/items	texto/anot+tartaruga
/catalogs/{catalogId}/collections/{recordsCollectionId}/items/{itemId}	texto/anot+tartaruga
/purge-tbox-cache	aplicativo/json
/tbox-cache	aplicativo/json
/saúde	aplicativo/json
/prefixos	texto/anot+tartaruga
/hierarquia de conceito/{parent_curie}/narrowers	texto/anot+tartaruga
/hierarquia de conceito/{parent_curie}/top-concepts	texto/anot+tartaruga
/cql	texto/anot+tartaruga
/perfis	texto/anot+tartaruga
/procurar	texto/anot+tartaruga
/perfis/{perfil_curie}	texto/anot+tartaruga
/objeto	texto/anot+tartaruga
/identificador/redirecionar	N / D
/identificador/curie/{iri}	texto/simples
/identificador/iri/{curie}	texto/plai

OGC apresenta terminais de API

Os endpoints da API OGC Features são baseados em ROOT /catalogs/{catalogId}/collections/{recordsCollectionId}/

Ponto final	MT padrão
{ROOT}/recursos	aplicativo/json
{ROOT}/recursos/documentos	texto/html
{ROOT}/recursos/conformidade	aplicativo/json
{ROOT}/recursos/coleções	aplicativo/json
{ROOT}/features/collections/{collectionId}	aplicativo/json
{ROOT}/features/collections/{collectionId}/items	aplicação/geo+json
{ROOT}/features/collections/{collectionId}/items/{featureId}	aplicação/geo+jso

Configuração

As seguintes variáveis ​​de ambiente podem ser usadas para configurar o Prez: Na maioria dos casos, tudo o que é necessário é a variável SPARQL_ENDPOINT.

Eles podem ser definidos em um arquivo '.env' que será lido via python-dotenv. Alternativamente, configure-os diretamente no ambiente a partir do qual o Prez é executado.

Configuração do terminal SPARQL

• sparql_endpoint : endpoint SPARQL somente leitura para Prez. O padrão é None .
• sparql_username : um nome de usuário para o endpoint Prez SPARQL, se exigido pelo banco de dados RDF. O padrão é None .
• sparql_password : Uma senha para o endpoint Prez SPARQL, se exigido pelo banco de dados RDF. O padrão é None .
• enable_sparql_endpoint : se deve ativar o endpoint SPARQL. Ou seja, se prez expõe o endpoint SPARQL do repositório remoto (normalmente um triplestore). O padrão é False . NB: o endpoint SPARQL, quando habilitado, suporta solicitações POST. O próprio Prez não faz nenhuma atualização no repositório remoto (por exemplo, o Triplestore remoto), no entanto, se o endpoint SPARQL remoto estiver habilitado, é possível que os usuários possam fazer atualizações no repositório remoto usando o endpoint SPARQL.

Configuração de rede

• protocol : O protocolo usado para entregar Prez. O padrão é "http" .
• host : nome de domínio do host do Prez. O padrão é "localhost" .
• port : A porta em que o Prez fica acessível. O padrão é 8000 .

URI do sistema

• system_uri : Um IRI para o sistema Prez como um todo. Este valor aparece no RDF da landing page entregue pela Prez ( "/" ). O padrão é f"{protocol}://{host}:{port}" .

Configuração de registro em log

• log_level : nível de registro. O padrão é "INFO" .
• log_output : destino de saída de registro. O padrão é "stdout" .

Metadados Prez

• prez_title : Título para a instância Prez. O padrão é "Prez" .
• prez_desc : Descrição da instância Prez. O padrão é uma descrição da API da estrutura da web Prez.
• prez_version : Versão da instância Prez. O padrão é None .

Separador CURIE

• curie_separator : Separador usado em CURIEs. O padrão é ":" . Este separador aparece nos links gerados pelo Prez e, por sua vez, nos caminhos de URL.

Ordenação e configuração de predicado

• order_lists_by_label : se deseja ordenar as listas por rótulo. O padrão é True .

Predicados de rótulo

Usado para exibir RDF com rótulos legíveis por humanos.

• label_predicates : Lista de predicados usados ​​para rótulos. O padrão inclui:
  • skos:prefLabel
  • dcterms:title
  • rdfs:label
  • sdo:name

Quando um tipo de mídia anotado ( +anot ) é usado, Prez inclui triplos para cada URI na resposta inicial que possui uma das propriedades acima. Essas triplas de anotação são então armazenadas em cache. As anotações são usadas para fins de exibição, por exemplo, páginas HTML.

Descrição Predicados

Semelhante aos predicados de rótulo acima.

• description_predicates : lista de predicados usados ​​para descrições. O padrão inclui:
  • skos:definition
  • dcterms:description
  • sdo:description

Predicados de Proveniência

Semelhante aos predicados de proveniência acima.

• provenance_predicates : Lista de predicados usados ​​para proveniência. O padrão inclui:
  • dcterms:provenance

Outros predicados

O mecanismo de anotação pode ainda ser usado para retornar geralmente certas propriedades sempre que presentes.

• other_predicates : Lista de outros predicados. O padrão inclui:
  • sdo:color
  • reg:status
  • skos:narrower
  • skos:broader

Configuração do repositório SPARQL

• sparql_repo_type : Tipo de repositório SPARQL. O padrão é "remote" . As opções são "remote" , "pyoxigraph" e "oxrdflib"
• sparql_timeout : Tempo limite para consultas SPARQL. O padrão é 30 .

Informações de contato

• prez_contact : informações de contato do Prez. O padrão é None .

Geração de prefixo

• disable_prefix_generation : se a geração de prefixo deve ser desativada. É recomendado desabilitar a geração de prefixos para grandes repositórios de dados , além disso, é recomendado sempre especificar prefixos no diretório prez/reference_data/prefixes/ . O padrão é False .

Configuração de idioma e pesquisa

• default_language : idioma padrão para Prez. O padrão é "en" .
• default_search_predicates : Predicados de pesquisa padrão. O padrão inclui:
  • rdfs:label
  • skos:prefLabel
  • sdo:name
  • dcterms:title

Diretório RDF local

Usado em conjunto com o repositório Pyoxigraph. Especifica um diretório (da raiz do repositório) para carregar no gráfico de dados Pyoxigraph na memória. Não usado para outros tipos de repositório.

• local_rdf_dir : Diretório para arquivos RDF locais. O padrão é "rdf" .

Estrutura do terminal

• endpoint_structure : Estrutura padrão dos endpoints, usada para gerar links. O padrão é ("catalogs", "collections", "items") .

Terminais do sistema

• system_endpoints : lista de endpoints do sistema. O padrão inclui:
  • ep:system/profile-listing
  • ep:system/profile-object

Configuração de listagem e pesquisa

• listing_count_limit : o número máximo de itens a serem contados para um endpoint de listagem. Contagens superiores a este limite serão retornadas como ">N", onde N é o limite. O padrão é 100 .
• search_count_limit : o número máximo de itens a serem retornados em um resultado de pesquisa. O padrão é 10 .

Configuração temporal

• temporal_predicate : o predicado usado para propriedades temporais. O padrão é sdo:temporal .

Configuração do modelo de consulta

• endpoint_to_template_query_filename : Um dicionário que mapeia terminais para consultar nomes de arquivos de modelos. O padrão é um dicionário vazio.

Correndo

Esta seção é para desenvolver o Prez localmente. Veja as opções de execução abaixo para executar o Prez em produção.

Para executar o servidor de desenvolvimento (com recarga automática nas alterações de código):

poetry run python main.py

Executando em um contêiner

As imagens de contêiner Prez são criadas usando uma ação do Github e estão disponíveis aqui.

O Dockerfile no repositório também pode ser usado para construir uma imagem Docker.

Variantes de imagem

O nome da imagem é ghcr.io/rdflib/prez .

A tag latest aponta para a versão estável mais recente do Prez. Todas as versões estáveis ​​mais recentes têm uma etiqueta principal, principal e secundária, e principal, secundária e patch apontando para ela.

Por exemplo, para uma versão com uma tag git 3.2.4, as seguintes tags estarão na imagem do contêiner:

• 3
• 3.2
• 3.2.4
• latest

Novos commits no branch main criam uma imagem dev contínua com a tag dev . As compilações de desenvolvimento também incluirão uma tag no formato major.minor.{patch+1}-dev.{commits-since-last-release}.{short-commit-sha}. Isso está em conformidade com o versionamento semântico e será reconhecido pelos sistemas de orquestração para realizar lançamentos automáticos.

Por exemplo, se a versão mais recente for 3.2.4 e houver 7 novos commits desde o lançamento e o SHA curto do commit for fc82562, a tag da imagem do contêiner será:

• 3.2.5-dev.7.fc82562

Para executar a imagem do Docker extraída:

 docker run -p 8000:8000 
    -e SPARQL_ENDPOINT=<your_sparql_endpoint> 
    <your_image_id>

O comando acima inicia um contêiner Docker executando Prez na porta 8000, conectado ao endpoint sparql especificado.

Teste

Prez usa PyTest e Coverage para testes e relatórios de cobertura de testes.

Para executar todos os testes disponíveis:

poetry run pytest tests

Para executar todos os testes disponíveis para análise de cobertura:

poetry run coverage run -m pytest tests

Para gerar um relatório de cobertura:

poetry run coverage report

Serviço de redirecionamento

Como um servidor Linked Data, o Prez fornece um serviço de redirecionamento em /identifier/redirect que aceita um parâmetro de consulta iri , procura o iri no banco de dados em busca de um predicado foaf:homepage com um valor e, se existir, retorna uma resposta de redirecionamento para o valor.

Esta funcionalidade é útil para instituições que emitem os seus próprios identificadores persistentes sob um nome de domínio que controlam. O mapeamento do identificador persistente para o recurso da web de destino é armazenado no armazenamento SPARQL de back-end.

Esta é uma solução alternativa para serviços de identificação persistentes, como w3id.org. Em alguns casos, ele pode ser usado junto com esses serviços de identificação persistente para evitar a necessidade de fornecer o mapeamento de redirecionamento na configuração do servidor web (NGINX, Apache HTTP, etc.) e, em vez disso, definir a configuração como dados RDF.

Validação de dados

Para que o Prez forneça dados por meio de seus vários subsistemas, os dados precisam estar em conformidade com alguns requisitos mínimos: você não pode, por exemplo, executar o VocPrez sem nenhum SKOS ConceptSchemes definido!

Validação

Todos os perfis listados acima fornecem validadores que podem ser usados ​​com dados RDF para testar se são válidos. Se for, Prez ficará bem com isso.

Os validadores dos perfis estão todos disponíveis nos próprios perfis (navegue para as listagens de outros recursos de perfil através dos links de especificação acima) e também são carregados na ferramenta online RDFTools que você pode usar sem baixar ou instalar nada:

• http://rdftools.kurrawong.net/validate

Procure os validadores VocPrez Compounded e similares. O bit 'composto' significa que o validador validará os dados em relação a todos os VocPrez e requisitos herdados.

Contato

NOTA : Esta ferramenta de código aberto é ativamente desenvolvida e apoiada pela KurrawongAI, uma pequena empresa australiana do Knowledge Graph, desenvolvedores da Universidade de Melbourne e também por contribuidores de código aberto.

Para sinalizar problemas ou levantar dúvidas, crie problemas no Issue Tracker ou entre em contato com os desenvolvedores usando os detalhes abaixo.

Aqui estão os principais desenvolvedores:

KurrawongAI https://kurrawong.net

David Habgood [email protected]

Nicholas Car [email protected]

Edmond Chuc [email protected]

Universidade de Melbourne - Prez UI principalmente Jamie Feiss [email protected]

Contribuindo

Adoramos contribuições para esta ferramenta e encorajamos você a criar problemas no Issue Tracker deste repositório ou a enviar solicitações pull!

Há documentação sobre como contribuir com o Prez, consulte README-Dev.md.

Licença

Esta versão do Prez e o conteúdo deste repositório também estão disponíveis sob a licença BSD-3-Clause. Consulte o arquivo LICENSE deste repositório para obter detalhes.