DCAT-AP-SE-Processor

KO | EN

gitlite — search

#javascript #python #ai #typescript #llm #golang #machine-learning #docker #java #awesome #vue #ios #mcp #open-source

DCAT-AP-SE-Processor

(★ 10)

No description available.

DCAT-AP-SE-Processor Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DCAT-AP-SE Processor

[![License: EUPL 1.2](https://img.shields.io/badge/License-European%20Union%20Public%20Licence%201.2-library?style=for-the-badge&&color=lightblue)](https://raw.githubusercontent.com/diggsweden/DCAT-AP-SE-Processor/main/LICENSE)  
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/diggsweden/DCAT-AP-SE-Processor/badge?style=for-the-badge)](https://scorecard.dev/viewer/?uri=github.com/diggsweden/DCAT-AP-SE-Processor)

DCAT-AP-SE Processor är ett verktyg för att automatisera framställningen av metadata enligt metadataspecifikationen [DCAT-AP-SE](https://docs.dataportal.se/dcat/sv/) , som används för att publicera information om datamängder och API:er på [Sveriges dataportal](https://www.dataportal.se/).
Verktyget tar en API-definition som indata och genererar en RDF-fil redo för skördning av dataportalen. Som indata stöds API-definitioner i formaten OpenAPI och RAML, samt separata metadatafiler på JSON-format för OAS2/RAML0.8 eller för API:er utan en formell definition. Detta verktyg är framtaget för att enkelt kunna integreras i en CI/CD-pipeline eller köras fristående.

## Innehållsförteckning

- [DCAT-AP-SE Processor](#dcat-ap-se-processor)
  - [Innehållsförteckning](#innehållsförteckning)
  - [Bakgrund](#bakgrund)
  - [Instruktioner för att komma igång snabbt](#instruktioner-för-att-komma-igång-snabbt)
  - [Användning](#användning)
  - [Systemkomponenter](#systemkomponenter)
  - [Lägga till stöd för nya metadata i verktyget](#lägga-till-stöd-för-nya-metadata-i-verktyget)
  - [Arbetsprocess för att publicera api/er på dataportalen](#arbetsprocess-för-att-publicera-apier-på-dataportalen)
  - [Licens](#licens)
  - [Beroenden](#beroenden)
  - [Underhållare](#underhållare)
  - [Versioner](#versioner)
  - [Bidra](#bidra)

## Bakgrund

### Sveriges dataportal

[Sveriges dataportal](https://www.dataportal.se/) synliggör information om datamängder (d.v.s. metadata) där själva datamängderna och åtkomstpunkterna finns publicerade hos olika aktörer.
Detta sker genom att Sveriges dataportal automatiskt inhämtar, ”skördar”, informationen hos publicerande aktör.
En aktör kan vara både från offentlig och privat sektor samt från civilsamhället.

En förutsättning för att dataportalen ska kunna synliggöra bland annat information om datamängder och dess API:er,
är att aktörerna upprättar och publicerar informationen enligt en gemensam och standardiserad metadataspecifikation som är tillgänglig för skördning.
Den specifikationen heter [DCAT-AP-SE](https://docs.dataportal.se/dcat/sv/) och är speciellt framtagen för att passa Sveriges dataportal på grund av den är tillräckligt övergripande för
att passa inhämtning av metadata från olika typer av organisationer och datadomäner.
Det möjliggör en enhetlig beskrivning av datamängder för att förenkla insamling, sökning och presentation av data på Sveriges dataportal. Följande information innehåller mycket tekniska termer och begrepp. För att kunna tillgodogöra sig informationen bör därför någon med sådan typ av kompetens läsa instruktionen.

### Automatiserad process för framställning av metadata

I syfte att hjälpa producenter av metadata, som ska skördas till dataportalen, har detta verktyg tagits fram för att kunna införlivas i godtycklig CI/CD driven kedja eller köras separat.
Verktyget skapar en metadataspecifikation på RDF-format utifrån en API-definition alternativt separat metadatafil.
RDF är det språk som används för att uttrycka metadata om ting på webben. En central egenskap med RDF är att man använder webbadresser (URI:er) för att referera till ting i olika påståenden.

## Instruktioner för att komma igång snabbt

Bygg en container image från koden i detta repository.

När container startas finns ett webbaserat UI och ett REST API tillgängligt att använda efter behov.

### Docker

Kör med docker:

```text
docker build --no-cache -t "dcatprocessor" .
```

```text
docker run -it --rm -p 8080:8080 dcatprocessor:latest 
```

### Podman

Kör med Podman:

```text
podman build --no-cache -t "dcatprocessor" .
```

```text
podman run -it --rm -p 8080:8080 dcatprocessor:latest 
```

### Färdigbyggd image

Alternativt, finns det också en experimentell färdigbyggd image för att testa.

```text
docker run ghcr.io/diggsweden/dcat-ap-processor:latest
```

```text
podman run ghcr.io/diggsweden/dcat-ap-processor:latest
```

**ANVÄND INTE OVAN IMAGE I PRODUKTIONSYFTEN** - Den är endast avsedd för lokal test, och inga garantier lämnas på säkerhetsuppdateringar med mera.

## Användning

### Format på API-definitioner

Det finns stöd för formaten OpenAPI eller RAML.

- OpenAPI 3.x tillägg av metadata sker via extensions 
 Lägg till en extension x-dcat och underliggande metadata hanteras.
- RAML1.x tillägg av metadata sker via annotations 
 Definiera en annotationType och använd den sedan.
- OAS2.x och RAML0.8 tillägg av metadata sker via separat metadatafil på json format.

Verktyget kan användas på följande sätt.

### 1. Via UI

Starta docker container, öppna browser till <http://localhost:8080>

Det finns val för att:

- skicka in en sträng med API-definitionen.
- bifoga en fil med API-definitionen.
- ange en katalog som håller flera API-definitioner.

Verktyget levererar resultatet som svar på sidan.

### 2. Via anrop till REST gränssnitt

Anropa endpoints med valfritt verktyg. I utveckling har vi använt curl från git bash, t.ex:

```text
curl "http://localhost:8080/dcat-generation/files/?dir=<path-to-your-folder>"
```

Vid lyckat anrop kommer en XML med genererad RFD att returneras.

Jenkins pipeline exempel
[Jenkinsfile](docs/jenkinsfile).

### 3. Via CLI

Vid användning av CLI kan enstaka filer pekas ut ( -f ) eller en hel mapp ( -d )

Bygg en java JAR fil.

```text
mvn clean package -DskipTests
```

Konvertera en specifikationsfil och få DCAT-data till stdout:

```text
java -jar dcat-ap-processor-0.0.3-SNAPSHOT.jar -f FIL
```

Konvertera en katalog med specifikationsfiler och få DCAT-data till stdout:

```text
java -jar dcat-ap-processor-0.0.3-SNAPSHOT.jar -d KATALOG
```

## Systemkomponenter

Sekvensdiagram över flödet i verktyget. 
![img_1.png](https://raw.githubusercontent.com/diggsweden/DCAT-AP-SE-Processor/main/docs/dcat-sekvens.png)

### PreprocessorController (REST API)

REST API:n för verktyget, följande två är de som finns att använda:

"/dcat-generation/files/" - Skickar man in directory (dir) som sedan skickas vidare till Managern för hantering. 
"/dcat-generation/web/" - Är endpointen för Web-UI som skickar med antingen en sträng med hela apidefinitionen eller en lista med filer som sedan skickas vidare till Managern.

### Manager

Tar emot anrop från REST API't eller formuläret och styr parsning, konvertering och uppskapande av RDF-data.

### ApiDefinitionParser

Använder [snakeYaml](https://bitbucket.org/asomov/snakeyaml) för att parsa RAML1.0 och OAS3 yaml strängen, som innehåller apidefinitionen, till JSONObject.

När det gäller OAS3 json format läses den strängen in som JSONObject direkt.

RAML0.8 och/eller OAS2 på json/yaml format stöder inte annotations/extensions, så där får användaren tillgång att lägga metadata i en separat fil på json format, som parsas till JSONObject.

### Converter

Använder MultiValuedMap (Apache Commons) och org.json.

För att konvertera mellan inläst metadata till element på DCAT-AP-SE format används konverteringsfiler (t.ex. TO_DCAT_OAS.json). 
I senare skeden kan man enkelt lägga till nya konverteringsfiler för andra format eller ändra till nyare versioner av befintliga format.

### RDFWorker

Använder RDF4J.

Tar emot en lista av Katalog objekt och skapar matchande RDF utifrån det.

## Lägga till stöd för nya metadata i verktyget

[Översikt över vad som finns och fungerar enligt DCAT-AP-SE spec](docs/DCATAPSE_completion.md) 
[Tillägg i Converter](docs/converter-tutorial.md) 
[Tillägg i RDFWorker](docs/rdfworker-tutorial.md) 
[specifikationsfil](src/main/resources/dcat_specification.properties)

## Arbetsprocess för att publicera api/er på dataportalen

- [Skapa konto](https://docs.dataportal.se/accounts/) till de bakomliggande systemen för dataportal.se eller kontrollera [status](https://admin.dataportal.se/status/public) om er organisation redan finns upplagd. Upprätta sedan en skördningskälla, [Komma igång](https://docs.dataportal.se/registry/start/). 
- Inför metadata i apidefinitionen, eller skapa en separat metadatafil. 
- Använd verktyget för att generera en RDF fil.
- Skörda RDF filen, [Hantera organisationer och skördningskällor](https://docs.dataportal.se/registry/organisationer/#lagga-till-en-organisation).
- Verifiera att skördningen fungerar.
[Dataportalen docs](https://docs.dataportal.se/) har ingående information om hur skördningen fungerar samt hur en organisation sätter upp sin katalogkälla.

### Införa metadata

För att verktyget ska ges information att generera data behöver api definitionen uppdateras med metadata information. 
Detta repository innehåller [exempelfiler](src/main/resources/metadataExample) som visar hur metadata kan införas i apidefinition eller i separat metadatafil. 
[Attribut som stöds](docs/supported_attributes.md) finns listade med beskrivning.
Utgå från exempelfilerna och ta hjälp av [rekommendationer](https://docs.dataportal.se/dcat/docs/recommendations/) på dataportalen

Det finns exempelfiler som visar hur obligatoriska, rekommenderade och valfria värden kan läggas in. 
När apidefinition/erna är uppdaterade med metadata görs de tillgängliga på en publikt nåbar folder, så att den separata pipeline som kör verktyget kan nå dem.

#### Om ni har ett API

Se exempel [enkel fil](src/main/resources/metadataExample/single), där Katalog elementet ligger i samma fil som resterande metadata. 
Exempel med obligatoriska och rekommenderade värden. 
[RAML](src/main/resources/metadataExample/single/full_example.raml) 
[OAS YAML](src/main/resources/metadataExample/single/full_example_oas.yaml) 
[OAS JSON](src/main/resources/metadataExample/single/full_example_oas.json)

För API som inte har en definition (code-first) kan dataproducenten tillhandahålla separat metadata på json format 
[Separat JSON](src/main/resources/metadataExample/single/full_example.json)

#### Om ni har flera API:er

Organisation med multipla API att producera RDF från använder en separat catalog.json fil för att hålla samman de ingående API:ernas metadata, se exempel under [multipla filer](src/main/resources/metadataExample/multiple). 
För att verktyget ska generera en sammanslagen RDF-fil krävs att organisationen skapar filer enligt följande: 
catalog.json - beskriver det övergripande katalog elementet och är samma för alla ingående apier. 
[catalog.json](src/main/resources/metadataExample/multiple/catalog.json) - Katalog elementet i separat fil på json format.

Exempel på ingående API-definitioner innehållande metadata för DCAT-AP-SE 
[full_example.raml](src/main/resources/metadataExample/multiple/full_example.raml) - Api A på RAML format 
[full_example_oas.yaml](src/main/resources/metadataExample/multiple/full_example_oas.yaml) - Api B på OAS3 yaml format 
[full_example_oas.json](src/main/resources/metadataExample/multiple/full_example_oas.json) - Api C på OAS3 json format 
[full_example.json](src/main/resources/metadataExample/multiple/full_example.json), Api D, separat metadataspecifikation på json format

## Licens

DCAT-AP-SE-Processor är licensierad under EUPL-1.2 
Se [licens](LICENSES/EUPL-1.2.txt) för mer information.

## Beroenden

snakeYaml [Apache license](docs/Licenser/Apache.txt) 
RDF4J [EDL v1.0 license](docs/Licenser/edl-v10.txt) 
Spring boot, Spring framework [Apache license](docs/Licenser/Apache.txt) 
commonmark-java [BSD-2 clause simplified license](docs/Licenser/BSD-2.txt) 
jackson-dataformat-yaml [Apache license](docs/Licenser/Apache.txt) 
JSON-java [Public domain](https://github.com/stleary/JSON-java) 
commons-collections4 [Apache license](docs/Licenser/Apache.txt)

## Underhållare

Mjukvaran utvecklas av [DIGG](https://github.com/diggsweden) och Arbetsförmedlingen.

## Versioner

Aktuell version är 0.9.

Detta är en första version av verktyget. Arbetsförmedlingen och Bolagsverket kommer prova mjukvaran skarpt under hösten 2022. När mjukvaran fungerar för tillräckligt många offentliga organisationer kommer versionen uppdateras till 1.0.

## Bidra

DCAT-AP-SE-Processor

DCAT-AP-SE-Processor Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

DCAT-AP-SE-Processor

DCAT-AP-SE-Processor Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README