Specifikation för skoldata

Information om skolor, förskolor och gymnasier

Denna version:
https://lankadedata.se/spec/skoldata/1.1
Senaste versionen:
https://lankadedata.se/spec/skoldata/
Förra version:
https://lankadedata.se/spec/skoldata/1.0
Författare:
Matthias Palmér - MetaSolutions
Magnus Burell - Hemnet
Licens:
CC-BY 4.0

1. Introduktion

Med skoldata menas kontakt- och platsinformation om förskolor, familjedaghem, grundskolor och gymnasier inom en kommun. I texten nedan används för enkelhets skull ordet “skola” för att benämna alla dessa former.

Denna specifikation definierar en enkel tabulär datamodell för skoldata som passar utmärkt att leverera i formatet CSV, dvs kommaseparerade värden enligt RFC4180. Inget hindrar att ytterligare format stöds, t.ex. beskrivs också nedan hur JSON uttrycket ska se ut. Men som grund förutsätts CSV kunna levereras då det är praktiskt och skapar förutsägbarhet för mottagare av informationen.

2. Datamodell

Datamodellen är tabulär, där varje rad motsvarar exakt en skola och varje kolumn motsvarar en egenskap för denna skola. 16 kolumner är definierade, där de första 8 är obligatoriska, kolumn 9 och 10 är starkt rekommenderade för att skolinformationen ska få spridning. Övriga kolumner 11 till 16 är frivilliga.

Observation 1Första kolumnen (source) varierar inte som de andra egenskaperna då den motsvarar vart skolorna tillhör och kommer således vara samma för alla rader som kommer från en kommun. Det kan tyckas onödigt att upprepa detta för varje rad. Alternativet (som valts bort) är att varje mängd skoldata måste kompletteras med information om tillhörighet i en separat metadata fil.

Observation 2Kolumn 8 och 9 är en förutsättning för att enkelt kunna visa upp skolor på en karta.

Kolumner i datmodellen
# Kolumnnamn Värdemängd Exempel och förklaring
1 source heltal Ange SCB:s kommunkod för er kommun. Exempel: "0163" för Sollentuna kommun.
2 id text Ange en unik och stabil identifierare för skolan inom er kommun, förslagsvis ett heltal, men en text är också acceptabelt. Undvik mellanslag och andra tecken som inte passar bra i en URI (webbadress). Man använda namnet för skolan, men då ersätta mellanrum med “_”, t.ex. “Förskolan_Bikupan”.
3 name text Ange skolans namn. Exempel: "Förskolan Bikupan"
4 type FS|FD|
GR|GY|KV
Ange typ av skola, alternativen motsvarar: FörSkola, FamiljeDaghem, GRundskola, GYmnasium, KomVux Använd de angivna förkortningarna i versaler.
5 operation K|F Ange ett av alternativen: "Kommunal", "Fristående/Privat". Använd de angivna förkortningarna i versaler.
6 street text Ange gatuadress (för besöksadressen) inklusive gatunummer. Exempel: "Drevkarlsstigen 5"
7 postalcode heltal Ange postnummer utan mellanslag. Exempel: “19253"
8 locality text Ange postort. Exempel: "Sollentuna"
9 lat WGS84 Ange latitud enligt WGS84. WGS84 är samma koordinatsystem som används av GPS samt av de flesta karttjänster som t.ex. Google Maps, Bing Maps, OpenStreetMap, Mapquest, Esri, Mapbox osv. Exempel: 59.4434403
10 long WGS84 Ange longitud enligt WGS84. Exempel: 17.96793
11 email email Ange e-postadress för allmänna frågor till skolan. Uttryckt i enlighet med RFC6068 utan “mailto:” scheme delen, t.ex. “johan@example.com”
12 phone heltal och - Ange telefonnummer (inklusive riktnummer) till skolans växel eller motsvarande. Använd - inte mellanrum om du vill öka läsbarheten (detta för att öka kompatibiliteten med RFC3966). T.ex.: 018-727-00-00 Ange inte landskod, +, parentes eller liknande.
13 url URL Ange i första hand fullständig webbadress till skolan, i andra hand webbadressen till en samlingssida för skolor på kommunens webbplats. Exempel: https://www.sollentuna.se/sv/uweb/gardesskolan-med-forskolor/vara-verksamheter1/Forskolan/ Notera att man måste ange URL:en med protokoll, dvs inklusive http:// eller https://.
14 capacity heltal Antal platser / elever som skolan kan ta emot.
15 open.from hh:mm Ange timme och minut i ett format som är kompatibelt med ISO 8601, t.ex. 07:30.
16 open.to hh:mm Ange timme och minut i ett format som är kompatibelt med ISO 8601, t.ex. 17:00.

3. CSV formatet

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

source,id,name,type,operation,street,postalcode,locality,lat,long,email,phone,url,capacity, open.from,open.to

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.

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

source;id;name;type;operation;street;postalcode;locality;lat;long;email;phone;url;capacity;open.from;open.to

3.1 Åtkomst via HTTP

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

3.2 Schema

Du som är nöjd med att leverera eller använda skoldata utifrån vad som beskrivs skrifligen 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.

Schema för skoldata: https://lankadedata.se/spec/skoldata/schema.json

För skoldata innebär detta schema:

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 EducationalOrganization.

Valet av schema.org gjordes eftersom den tillhandahåller en mängd egenskaper som till stor del täcker in skolinformationen. För den som är intresserad går det att hitta andra representationer av skolor 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 skoldata 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 skoldataspecifikationen på t.ex. öppnadata.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 "skoldata" som nyckelord på svenska.
  3. På distributionen som motsvarar CSV filen peka ut schemat via propertyn dcterms:conformsTo (med fältnamnet "länkade scheman").
Exempel: Datamängd med skoldata uttryckt i en DCAT katalog
<dcat:Catalog>
    <dct:title>En datakatalog</dct:title>
    <dcat:dataset rdf:resource="http://example.com/dataset1"/>
</dcat:Catalog>
<dcat:Dataset rdf:about="http://example.com/dataset1">
    <dct:title>En skoldatamängd</dct:title>
    <dcat:keyword xml:lang="sv">skoldata</dcat:keyword>
    <dct:conformsTo rdf:resource="https://lankadedata.se/spec/skoldata/"/>
    <dcat:distribution rdf:resource="http://example.com/distribution1"/>
</dcat:Dataset>
<dcat:Distribution rdf:about="http://example.com/distribution1">
    <dct:title>Skoldata som CSV</dct:title>
    <dcat:downloadURL rdf:resource="http://example.com/skoldatafil.csv"/>
    <dcat:accessURL rdf:resource="http://example.com/skoldatafil.csv"/>
    <dct:format>text/csv</dct:format>
    <dct:conformsTo rdf:resource="https://lankadedata.se/spec/skoldata/schema.json"/>
</dcat:Distribution>

Appendix A: Exempel på skoldata i CSV

I exemplet nedan ser ni första raden med kolumnnamn och sen en förskola, en grundskola och en gymnasieskola. Alla tre skolorna har de 13 första kolumnerna ifyllda.
Exempel: Tre skolor från Södertälje
source,id,name,type,operation,street,postal code,locality,lat,long,url
0181,1023_algarden,Algården förskola,FS,K,Algårdsv 1,15249,Södertälje,59.2111914307184,17.633231273029,https://www.sodertalje.se/skola-och-forskola/Forskola/Forskolor/Algardens-forskola/
0181,3003_soldalaskolan,Soldalaskolan,GR,K,Lundbygatan 5,15146,Södertälje,59.1856082200489,17.6046049054264,https://www.sodertalje.se/Soldalaskolan
0181,6005_orjangymnasiet,Örjangymnasiet,GY,F,Nibble,15191,Järna,59.0660021271055,17.616635823744,http://www.orjangymnasiet.se

Appendix B: Exempel på skoldata i JSON

Nedan ser ni första raden från exemplet ovan som JSON.
Exempel: En förskola i Södertälje
{
  "street": "Algårdsv 1",
  "postal code": "15249",
  "name": "Algården förskola",
  "locality": "Södertälje",
  "id": "1023_algarden",
  "source": "0181",
  "type": "FS",
  "operation": "K",
  "lat": "59.2111914307184",
  "url": "https://www.sodertalje.se/skola-och-forskola/Forskola/Forskolor/Algardens-forskola/",
  "long": "17.633231273029"
}

Appendix C: Versionshistorik