Leverans via RSS

Teknisk specifikation för elektroniska pliktleveranser via RSS

Detta dokument beskriver hur en leverantör kan leverera elektroniskt pliktmaterial med hjälp av RSS. Leveransmetoden lämpar sig väl för webb-publicerat material som uppdateras relativt ofta.

Aktuell version: 2024-12-09

Ändringslogg samt äldre versioner

Grundförutsättningar

En leverantör som vill leverera elektroniska pliktexemplar via ett RSS-flöde publicerar detta RSS-flöde på en fix URL.

I dokumentet "Introduktion - metadata" [1] finns en lista med de metadata-element som Kungliga biblioteket främst är intresserade av att få in. Varje sådant metadata-element har ett ID-nummer och en beskrivande rubrik.

ID-numren inleds med en kategoriserande bokstav:

R=metadata om resursen
S=metadata om struktur
F=metadata om objekt (filer).

I detta dokument finns det urval av metadata-element – från introdokumentet [1] – som kan anges vid leverans via RSS. För varje sådant metadata-element beskrivs hur det ska anges med XML-element i ett RSS-flöde.

Varje XML-element <item> i RSS-flödet representerar en resurs som ska levereras. Varje resurs motsvarar ett pliktexemplar enligt "Lag (2012:492) om pliktexemplar av elektroniskt material" [2].

De filer som tillsammans utgör resursen pekas ut med hjälp av metadata-elementen "R102 - Nätadress" [3] samt "F302, F303 - Fil som ingår i resursen (R)" [4] . Dessa innehåller information om var filer är tillgängliggjorda (URL) samt deras filformat (MIME type).

Beroende på leverantörens publiceringstakt så varierar systemet:s hämtningsintervall – med vilket RSS-flödet hämtas – från var 5:e minut till en gång per dygn.

Tekniska krav

Om URL för RSS-flödet ändras måste Kungliga biblioteket kontaktas.
RSS-flödet måste godkännas i vår validering, se rubrik längre ned: Validering [5].
RSS-flödet får inte vara paginerat.
De filer som pekas ut måste vara tillgängliga för hämtning av Kungliga biblioteket på de URL:er som anges. Alla URL:er ska vara av typen http eller https.
Elementet <pubDate> ska innehålla tidpunkten då resursen publicerades. En uppdatering av en redan levererad resurs ses som en ny resurs och skall levereras på nytt med ett uppdaterat <pubDate>.
Alla de <item> som publiceras eller uppdateras under den tidsperiod som motsvarar hämtningsintervallet måste synas i flödet.
För att göra hanteringen mindre känslig för tillfälliga driftproblem (på er eller vår sida) bör materialet ligga kvar i RSS-flödet minst 5-7 dygn beroende på mängden material som publiceras.

Ordlista

Här beskrivs vad vi menar med och hur vi använder vissa termer i detta dokument.

metadataelement
namngiven specifikation av ett metadatavärde eller en sammanhållen mängd metadatavärden

Anmärkning: Metadataelement är det abstrakta begrepp där metadatavärden beskrivs och namnges. Här besvaras frågan om vad som ska anges.

XML-element
syntaktisk del av ett XML-dokument

Anmärkning: I detta dokument specificeras XML-element för varje metadataelement. Det kan ses som implementationen av metadataelementen, dvs. här besvaras frågan om hur man praktiskt anger värdena i XML. Ett visst metadataelement har ofta olika XML-element för olika leveransmetoder.

resurs, pliktexemplar
data som representerar en tydligt avgränsad enhet av intellektuellt innehåll

Anmärkning: En resurs består normalt av en eller flera datafiler innehållande text, ljud eller bild. Termen resurs är synonym med termen pliktexemplar i Lag (2012:492) om pliktexemplar av elektroniskt material Länk till annan webbplats..

Format och namnrymder

Formatet på själva RSS-flödeskoden ska vara RSS 2.0 med tillägg av vissa element från MediaRSS 1.5.1 (https://www.rssboard.org/media-rss), Dublin Core DCMI Metadata Terms samt XML Schema instance.

För Dublin Core använder vi den mer omfattande namnrymden DCMI Metadata Terms enligt rekommendation från Dublin Core.

För tydlighets skull rekommenderar vi att prefixen media, dcterms samt xsi används.

Här listas våra fyra aktuella standarder:

RSS

Version: 2.0

Prefix: används inte

Namnrymds-URI:

Dokumentation: https://www.rssboard.org/rss-specification [6]

Media RSS Specification

Version: 1.5.1

Prefix: media

Namnrymds-URI: http://search.yahoo.com/mrss/

Dokumentation: https://www.rssboard.org/media-rss [7]

DCMI Metadata Terms

Version: 2020-01-20

Prefix: dcterms

Namnrymds-URI: http://purl.org/dc/terms/

Dokumentation: https://www.dublincore.org/specifications/dublin-core/dcmi-terms/ [8]

XSI

Version: 2012-04-05

Prefix: xsi

Namnrymds-URI: http://www.w3.org/2001/XMLSchema-instance

Dokumentation: https://www.w3.org/TR/xmlschema11-1/#xsi-namespace [9]

Begränsningar

Leverans via RSS-flöden har vissa begränsningar:

Leveranser av filer som har DRM-skydd stöds ej.
Kungliga bibliotekets system hämtar bara de URL:er som specificeras i RSS-flödet. Systemet undersöker inte hämtade filer för att hitta länkar till andra resurser att hämta (som en sökrobot/web crawler gör). Mer tekniskt: vårt system gör en HTTP GET.

Säkerhet

Om en leverantör levererar material som inte ska vara publikt tillgängligt måste vi ges åtkomst till den. I och med att vi använder HTTP GET finns idag följande alternativ:

IP-filtrering – Leverantören konfigurerar sin nätverksinfrastruktur att endast tillåta hämtningar från vissa IP-adresser som används av Kungliga biblioteket.
Inloggning med Basic Authentication – Leverantören skyddar resurserna med användarnamn/lösenord och kommunicerar dessa till Kungliga biblioteket.

Validering

För kontroll, validering, av att levererade RSS-flöden uppfyller kraven i denna specifikation finns två metoder som leverantören själv kan använda.

Enklast är att använda Kungliga bibliotekets valideringstjänst:
1. Gå till https://e-plikt.kb.se/validera/rss Länk till annan webbplats, öppnas i nytt fönster..
2. Kopiera RSS-koden.
3. Klistra in den direkt i formuläret.
4. Klicka ”Validera!”.
Kungliga bibliotekets validerings-API. Det beskrivs här (Obs! endast engelsk instruktion):
1. Gå till http://api.eplikt.kb.se Länk till annan webbplats, öppnas i nytt fönster..
2. Följ instruktion.
3. Se exempel nedan med curl där myrss.xml är den lokala fil som ska valideras.

curl --header "Content-Type:text/xml" --data-binary @myrss.xml "http://api.eplikt.kb.se/validate?schema=WEB_ARTICLE_RSS"

Format - inledande information

För att ett RSS-flöde ska fungera korrekt – enligt ovan angivna standarder – behöver det inledas med två deklarationer, en XML-deklaration samt en RSS-deklaration.

XML-deklaration

Denna anges alltid på detta sätt:

<?xml version="1.0" encoding="utf-8"?>

RSS-deklaration

RSS-deklaration innehåller rss-version samt namnrymder. Här anges även XML-elementet <channel> som beskriver RSS-flödet. Här måste följande information anges:

<title> - Ett beskrivande namn för RSS-flödet.
<link> - Den webbsajt där pliktleveranserna publiceras.
<description> - Beskrivning av RSS-flödet.

Exempel

Första exemplet visar inledande information för ett RSS-flöde med artiklar.

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" 
    xmlns:media="http://search.yahoo.com/mrss/" 
    xmlns:dcterms="http://purl.org/dc/terms/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <channel>
        <title>Organisationen - Pliktleverans av elektroniskt material till Kungliga biblioteket</title>
        <link>http://www.organisationen.se/</link>
        <language>sv</language>
        <copyright>Organisationen 2024</copyright>
        <description>Digitala pliktleveranser från organisationen.se</description>

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" 
    xmlns:media="http://search.yahoo.com/mrss/" 
    xmlns:dcterms="http://purl.org/dc/terms/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <channel>
        <title>Organisationen - Pliktleverans av elektroniskt material till Kungliga biblioteket</title>
        <link>http://www.organisationen.se/</link>
        <language>sv</language>
        <copyright>Organisationen 2024</copyright>
        <description>Digitala pliktleveranser från organisationen.se</description>

Det andra exemplet visar ett RSS-flöde som endast innehåller podcast-avsnitt.

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" 
    xmlns:media="http://search.yahoo.com/mrss/" 
    xmlns:dcterms="http://purl.org/dc/terms/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <channel>
        <title>Organisationen - Podcasts</title>
        <link>http://www.organisationen.se/podcast</link>
        <description>Pliktleveranser från Organisationen. Detta flöde innehåller endast podcasts</description>

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" 
    xmlns:media="http://search.yahoo.com/mrss/" 
    xmlns:dcterms="http://purl.org/dc/terms/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <channel>
        <title>Organisationen - Podcasts</title>
        <link>http://www.organisationen.se/podcast</link>
        <description>Pliktleveranser från Organisationen. Detta flöde innehåller endast podcasts</description>

Format - metadata-elementen

Varje metadata-element är beskrivet på en egen undersida, se länkar i menyn och nedan. Alla element är också samlade i två exempel-filer; kommenterad och o-kommenterad: Fullständiga exempel

Metadata-elementen är ett urval av elementen i introdokumentet Länk till annan webbplats, öppnas i nytt fönster..

För varje metadata-element beskrivs hur dessa ska förmedlas via XML-elementvärden och XML-attributvärden i ett RSS-flöde.

Obligatoriska metadata-element har en asterisk (*) framför namnet.

Upprepningsbara metadata-element – som kan förekomma flera gånger för samma resurs – har ett (R) efter namnet.

De angivna XML-namnrymderna (avsnitt Format och namnrymder) innehåller många fler XML-element och XML-attribut än de som i dagsläget används av Kungliga biblioteket. Alla namn i namnrymderna är tillåtna i ett RSS-flöde och förmedlade värden bevaras i vårt arkiv, även om inte alla används aktivt av Kungliga biblioteket idag.