Specifikation för leverantörsreskontra

1. Introduktion

Med leverantörsreskontra menas uppgifter som återfinns om gjorda inköp såsom värde på inköp, leverantörsnamn, inköpande organisation och identifierare till underlag för inköpet. I texten nedan används för enkelhets skull ordet “ett inköp” för att benämna detta.

Denna specifikation definierar en enkel tabulär informationsmodell för inköp. Specifikationen innefattar också en beskrivning av hur informationen uttrycks i formatet CSV, JSON och länkade data (RDF). Som grund förutsätts CSV kunna levereras då det är praktiskt format och skapar förutsägbarhet för mottagare av informationen. Det är också ett format som gör datautdrag enklare då snarlika processer ofta finns.

Ett inköp bokas ibland på flera olika konton då ett inköp kan innehålla olika typer av kostnader. Detta gör att ett inköp kan motsvara flera rader.

Uttrycket i länkade data återanvänder konstruktioner från andra initiativ och ger därmed en grund för interoperabilitet med data som uttrycks utan kunskap om denna specifikation.

Det rekommenderas att publicera månadsvisa dataleveranser i form av CSV och låta en datamängd definieras av ett kalenderår. Detta dels för att tagarna ofta använder tabelldata och för att det mellan ett kalenderår till nästa kan uppstå överlappande information.

2. Datamodell

Datamodellen är tabulär, där varje rad motsvarar exakt en kontering och varje kolumn motsvarar en egenskap för detta inköp. 15 kolumner är definierade, där de första 9 är obligatoriska, om köparen är en kommun bör kolumn 14, kommun_id, som innehåller kommunkod anges.

Observation 1Vi väljer att använda beskrivande men korta kolumnnamn som uttrycks med gemener, utan mellanslag (understreck för att separera ord) och utan å, ä och ö. Orsaken till detta är:

1. Man vill använda kolumnnamn snarare än ordningen för att detektera om viss data finns. Korta och enkla kolumnnamn minskar risken för att problem uppstår.
2. Det är vanligt att man erbjuder söktjänster där frågor mot olika kolumner skrivs in i webbadresser och det är bra om det kan göras utan speciella teckenkodningar.

Observation 2För en enskild organisation är kolumn 1 och 2 (kopare) samma för alla rader. Det kan tyckas onödigt att upprepa detta för varje rad. Alternativet (som valts bort) är att varje mängd inköp måste kompletteras med denna information om datafiler från flera organisationer ska kombineras.

Observation 3Kolumn 3, verifikationsnummer, är en förutsättning för att den egna organisationen enkelt kunna göra en automatiserad förfrågan i en e-tjänst om begäran av fakturakopia.

2.1 Förtydlingar kring värdemängder

Alla reguljära uttryck angivna i tabellen nedan (förkortat reg. exp.) förutsätter att de matchar exakt, dvs inga inledande eller eftersläpande tecken tillåts. Det innebär att om uttrycket i tabellen nedan anges som -?\d+ (vilket motsvarar matcha heltal av obegränsad längd, eventuellt med ett minus framför) motsvaras det av det mer kompletta reguljära uttrycket som inleds av /^ och avslutas med $/, dvs /^-?\d+$/.

3. CSV formatet

Det enklaste formatet att stödja är CSV formatet enligt RFC4180. Se exemplet i Appendix A. Det som krävs är att första raden indikerar vilka kolumner som stöds (mellan X och Y stycken):

Utöver det som sägs i RFC4180 krävs alltid att informationen är uttryckt med teckenkodning UTF-8. På grund av att CSV har funnits länge och det finns en uppsjö av olika ramverk och program som inte alla följer RFC4180 så uppmanas man följa devisen:

"Be conservative in what you do, be liberal in what you accept from others"

För den här specifikationen innebär det att implementatörer rekommenderas även stödja semikolonseparerade filer. Orsaken är att Microsoft Excel använder semikolon istället för komma i CSV filer på operativsystem med svenska som default. Detta på grund av att komma används för decimaltal vilket ofta förekommer i CSV-filer vilket skulle kräva en omfattande användning av dubbla citationstecken kring värden. Denna specifikation kräver dock att man använder punkt i decimaltal (se 2.1).

För att särskilja data som är semikolonseparerade från kommaseparerade måste första raden se ut som:

Om några av de frivilliga kolumnerna utelämnas kan de helt tas bort från filen. Att hoppa över en mellanliggande kolumn, t.ex. kolumnen motsvarande "grund" men ändå tillhandahålla "kommun_id" är tillåtet då identifieringen av en viss kolumn sker via kolumnens namn som står överst, inte kolumnens nummer. Om värden saknas för en viss kolumn för en viss rad utelämnas värdet så att två komman (eller semikolon) kommer efter varandra. Att stoppa in nollvärden, t.ex. ett mellanslag, ett minus eller texten "null" är inte tillåtet och kommer misstolkas.

3.2 Åtkomst via HTTP

Om data görs tillgängligt på en webbadress bör följande gälla:

• Content-type ska vara text/csv (även för data med semikolonseparerade värden)
• Last-modified bör ange när datat senast ändrats
• HEAD requests bör stödjas där Last-modified ingår

3.2 Schema

Du som är nöjd med att leverera eller använda data utifrån vad som beskrivs skriftligen i denna specifikation och exemplifieras i appendixen kan ignorera detta avsnitt.

Sedan 2015 finns, "Metadata Vocabulary for Tabular Data", en W3C rekommendation för hur man anger metadata för datamodeller uttryckta i CSV.

För detta fall innebär detta schema:

• maskinell verifiering att CSV-uttryck är korrekta
• länka ihop med andra datakällor
• konvertera data till länkade data

De två sistnämnda kommer sig av att schemat också tillhandahåller saknad information, bland annat hur man konverterar ett visst CSV uttryck till RDF. Mer specifikt innehåller metadatan hur rader konverteras till instanser av schema.orgs Invoice.

Valet av schema.org gjordes eftersom den tillhandahåller en mängd egenskaper som till stor del täcker in fakturainformationen. För den som är intresserad går det att hitta andra representationer av fakturainformationen som RDF/länkade data.

4. JSON formatet

JSON uttrycket följer direkt ifrån CSV schemat och W3C rekommendationen "Generating JSON from Tabular Data on the Web" . Se exempel i appendix B.

4.1 Åtkomst via HTTP

Samma gäller som för CSV förutom att content-type ska vara "application/json".

4.2 Schema

Indirekt via CSV schemat.

5. Beskrivning i datakatalog

För den som vill lägga in sin data som en datamängd i en datakatalog ska man använda sig av W3C rekommendationen DCAT. För svenska behov är det DCAT-AP-SE som gäller. För att göra det enklare att hitta alla datamängder som följer specifikationen på t.ex. dataportal.se är det viktigt att man markerar dessa datamängder. Man bör då göra följande:

1. På datamängden peka ut denna specifikation via propertyn dcterms:conformsTo (med fältnamnet "uppfyller").
2. Lägg till "leverantörsreskontra", "inköp" som nyckelord på svenska.
3. På distributionen som motsvarar CSV-filen peka ut schemat via propertyn dcterms:conformsTo (med fältnamnet "länkade scheman").

Appendix A: Exempel på inköp i CSV

Exempel: Nedan är en fil med två riktiga inköp från Göteborg stad, fälten grund och avtal innehåller påhittade värden dock.
kopare_id,kopare,verifikationsnummer,leverantor,leverantor_id,konto_nr,konto_text,belopp,datum,forvaltning,fakturanummer,grund,avtal,kommun_id,s_kod_nr
2120001355,3921217387,Jordbruksverket distriktsveterinärerna,2021004151,7459,övriga konsulttjänster,2022.31,2020-01-01,392 - Park- och Naturnämnden,,,,,
2120001355,8001020462,Folkhälsomyndigheten,7499,Övriga främmande tjänster,444.75,2020-01-01,2021006545,800 - Miljö- och klimatnämnden,,,,,

Appendix B: Exempel på inköp i JSON

Exempel: Samma två inköp som för CSV fast nu i json.
[
  {
    "kopare_id": "2120001710",
    "kopare": "Skövde kommun",
    "verifikationsnummer": "3921217387",
    "leverantor": "Jordbruksverket distriktsveterinärerna",
    "leverantor_id": "2021004151",
    "konto_nr": "7459",
    "konto_text": "övriga konsulttjänster",
    "belopp": "2022.31",
    "datum": "2020-01-01",
    "forvaltning": "392 - Park- och Naturnämnden",
    "fakturanummer": "",
    "grund": "",
    "avtal": "",
    "kommun_id": "",
    "s_kod_nr": ""
  },
  {
    "kopare_id": "2120001710",
    "kopare": "Skövde kommun",
    "verifikationsnummer": "8001020462",
    "leverantor": "Folkhälsomyndigheten",
    "leverantor_id": "2021006545",
    "konto_nr": "7499",
    "konto_text": "Övriga främmande tjänster",
    "belopp": "444.75",
    "datum": "2020-01-01",
    "forvaltning": "800 - Miljö- och klimatnämnden",
    "fakturanummer": "",
    "grund": "",
    "avtal": "",
    "kommun_id": "",
    "s_kod_nr": ""
  }
]