DCAT-AP-SE Processor är ett verktyg för att automatisera framställningen av metadata enligt metadataspecifikationen DCAT-AP-SE , som används för att publicera information om datamängder och API:er på Sveriges dataportal. 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.
Sveriges dataportal 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 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.
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.
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.
Kör med docker:
docker build --no-cache -t "dcatprocessor" .
docker run -it --rm -p 8080:8080 dcatprocessor:latest
Kör med Podman:
podman build --no-cache -t "dcatprocessor" .
podman run -it --rm -p 8080:8080 dcatprocessor:latest
Varje release har en färdigbyggd image publicerad.
podman run --rm -p 8080:8080 ghcr.io/diggsweden/dcat-ap-se-processor:1.0.0
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.
Starta docker container, öppna browser till http://localhost:8080
I gränssnittet finns en editor där det går att lägga till och redigera en/flera API-definitioner innan de skickas in för generering. Det finns också en startmalls funktion — ett formulär som hjälper till att skapa upp x-dcat-attribut i en API-definition.
När generering lyckas levereras resultatet som en RDF på sidan och en kvalitetsrapport blir tillgänglig under fliken rapport. Om något går fel visas en felrapport.
Anropa endpoints med valfritt verktyg. I utveckling har vi använt curl från git bash, t.ex:
curl "http://localhost:8080/dcat-generation/files/?dir=<path-to-your-folder>"
Vid lyckat anrop kommer en XML med genererad RDF att returneras.
Jenkins pipeline exempel Jenkinsfile.
Applikationen kan köras som kommandoradsverktyg för att konvertera en enskild fil eller en hel katalog. När argument skickas med körs den i CLI-läge och ingen webbserver startas.
| Flagga | Värde | Beskrivning | Exempel |
|---|---|---|---|
-f |
FIL | Konverterar en specifikationsfil (.raml, .yaml, .json) | java -jar dcat-ap-se-processor-1.0.0.jar -f api.yaml |
-d |
KATALOG | Konverterar alla specifikationsfiler i en katalog | java -jar dcat-ap-se-processor-1.0.0.jar -d ./specs |
-h |
- | Visa hjälpmenyn | java -jar dcat-ap-se-processor-1.0.0.jar -h |
Endast en CLI-flagga kan användas per körning. Flaggorna -f och -d kräver ett värde i form av en fil- eller katalogsökväg, medan -h och -help används utan värde.
Ogiltiga argument, exempelvis okända flaggor, saknade värden eller flera CLI-flaggor, resulterar i exitkod 2.
Argument som börjar med --, t.ex. --server.port=8081, är Spring-inställningar och påverkar inte vilket läge applikationen startar i.
Bygg en java JAR fil.
mvn clean package -DskipTests
Konvertera en specifikationsfil, resultatet blir en RDF samt en kvalitetsrapport, båda ges som fil och visas via stdout:
java -jar dcat-ap-se-processor-1.0.0.jar -f FIL
Konvertera en katalog med specifikationsfiler, resultatet blir en RDF samt en kvalitetsrapport, båda ges som fil och visas via stdout:
java -jar dcat-ap-se-processor-1.0.0.jar -d KATALOG
Visa hjälpmenyn med information om tillgängliga flaggor och exempel på användning:
java -jar dcat-ap-se-processor-1.0.0.jar -h
Hjälpmenyn kan även visas med -help. Båda alternativen avslutar programmet med exitkod 0.
Vid lyckad konvertering skrivs DCAT-datan till stdout och filerna dcat.rdf och dcat-quality-report.json skapas i aktuell katalog.
Om konverteringen misslyckas skrivs en felrapport till stderr och ingen fil skapas.
| Kod | Betydelse |
|---|---|
| 0 | DCAT-data genererad eller visad hjälpmeny |
| 1 | Oväntat internt fel |
| 2 | Felaktiga argument, t.ex. okänd flagga eller saknat värde |
| 3 | Indata kunde inte konverteras, felrapport skriven till stderr |
Applikationen exponerar två endpoints för dokumentation och metadata om sitt API.
Interaktiv dokumentation för samtliga endpoints, inklusive parametrar, svarsformat och möjlighet att anropa API:et direkt från webbläsaren.
https://<host>/swagger-ui
Den underliggande OpenAPI-specifikationen finns på /openapi.yaml
Metadata om API:et
GET https://<host>/api-info
{
"apiName": "DCAT-AP-SE Processor API",
"apiVersion": "0.1.0",
"apiReleased": "2026-08-06",
"apiDocumentation": "https://<host>/api-docs",
"apiStatus": "beta"
}apiDocumentation pekar som standard på den svarande instansens egen Swagger UI.
Hostas verktyget bakom en gateway eller med publik dokumentation på annan plats
kan länken sättas via api-info.documentation i application.properties.
Sekvensdiagram över flödet i verktyget.

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.
"/" - Är index sidan för Web-UI. Genom UI kan en eller flera filer skickas via endpointen "/dcat-generation/web/spec". Endpoint accepterar objektet SpecRequest vilket innehåller en array av ApiSource, se openapi.yaml för schema beskrivning. Filerna skickas vidare till Managern.
Se kapitlet API-dokumentation för att läsa mer om vilka endpoints som finns tillgängliga.
Tar emot anrop från REST API't eller Cli och styr parsning, konvertering och uppskapande av RDF-data.
Använder 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.
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.
Använder RDF4J.
Tar emot en lista av Katalog objekt och skapar matchande RDF utifrån det.
Översikt över vad som finns och fungerar enligt DCAT-AP-SE spec
Tillägg i Converter
Tillägg i RDFWorker
specifikationsfil
- Skapa konto till de bakomliggande systemen för dataportal.se eller kontrollera status om er organisation redan finns upplagd. Upprätta sedan en skördningskälla, Komma igång.
- 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.
- Verifiera att skördningen fungerar. Dataportalen docs har ingående information om hur skördningen fungerar samt hur en organisation sätter upp sin katalogkälla.
För att verktyget ska ges information att generera data behöver api definitionen uppdateras med metadata information.
Detta repository innehåller exempelfiler som visar hur metadata kan införas i apidefinition eller i separat metadatafil.
Attribut som stöds finns listade med beskrivning.
Utgå från exempelfilerna och ta hjälp av rekommendationer 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.
Se exempel enkel fil, där Katalog elementet ligger i samma fil som resterande metadata.
Exempel med obligatoriska och rekommenderade värden.
RAML
OAS YAML
OAS JSON
För API som inte har en definition (code-first) kan dataproducenten tillhandahålla separat metadata på json format
Separat JSON
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.
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 - 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 - Api A på RAML format
full_example_oas.yaml - Api B på OAS3 yaml format
full_example_oas.json - Api C på OAS3 json format
full_example.json, Api D, separat metadataspecifikation på json format
DCAT-AP-SE-Processor är licensierad under EUPL-1.2
Se licens för mer information.
Samtliga tredjepartsberoenden och deras licenser listas i THIRD-PARTY.txt,
som genereras från pom.xml. För att uppdatera filen kör:
mvn license:add-third-party
Mjukvaran utvecklas av DIGG och Arbetsförmedlingen.
Aktuell version är 1.0.