Geodataportalen - Metadata - Dokumentation av tjänster

PM 1(13) Geodataportalen - Metadata - Dokumentation av tjänster Organisation Postadress Besöksadress Telefon E-post Internet Lantmäteriet 801 82 Gävle Lantmäterigatan 2 0771-63 63 63 geodatasekretariatet@lm.se www.geodata.se

PM 2(13) 1 Innehållsförteckning Geodataportalen - Metadata - Dokumentation av tjänster... 1 1 Innehållsförteckning... 2 2 Inledning... 3 3 Metadata för tjänster (huvudsakligen WMS)... 3 3.1 Översikt... 3 3.2 Kategorier av tjänster... 3 3.3 En WMS-tjänsts beståndsdelar... 4 3.4 Dokumentation av tjänsten... 5 4 Princip för dokumentation av wms-tjänster... 8 4.1 Dokumentera och publicera datamängder som ingår i tjänsten... 8 4.2 Dokumentera tjänsten som helhet... 8 4.3 Ange kopplade resurser för tjänsten... 9 4.4 Dokumentera hela tjänsten i tjänstens capabilitiesdokument... 9 4.5 Ange länkar till lager i wms-tjänst vid registrering av datamängder...11 4.6 WFS-tjänster...11 4.7 WPS-tjänster...11 5 Dokumentation av generella webbservices ex SOAP- eller RESTtjänster12

PM 3(13) 2 Inledning Detta dokument är en vägledning för hantering av metadata för tjänster i Geodataportalen. Dokumentet beskriver olika typer av tjänster, hur de kan dokumenteras och hur relationen till underliggande data skall beskrivas. Senaste versionen av detta dokument kan återfinnas på: www.geodata.se/ 3 Metadata för tjänster (huvudsakligen WMS) 3.1 Översikt Tjänster med geografisk information är en viktig beståndsdel i den nationella infrastrukturen för geodata. För att informationen i tjänsterna skall vara fullt användbar och tydlig för användarna behöver tjänsterna dokumenteras enligt specifika regler. För tjänster som har hårt kopplade data, t ex WMS-tjänster, är det viktigt att även de ingående datamängderna dokumenteras. De beskrivningar som anges i detta dokument syftar i huvudsak på WMS-tjänster. Andra typer av tjänster exempelvis WFS, WPS samt generella REST- och SOAPtjänster kan också publiceras i portalen och beskrivs i separat kapitel. 3.2 Kategorier av tjänster Tjänster som kommer att publiceras till Geodataportalen är av olika karaktär. Enligt Inspiredirektivet kommer hanterar vi:. Visningstjänster (OGC:WMS) Nedladdningstjänster (OGC:WFS) "Invoke" (Processnings)-tjänster (OGC:WPS) Utöver dessa kommer vi även att hantera generella WEBServices (WS). via Ex SOAP- eller REST-gränssnitt. WMS och WFS skiljer sig från övriga två tjänster genom att dessa är Fast kopplade (Tightly coupled) services. DVS tjänsten har i förväg definierade datakällor som inte kan ändras. Principerna för metadata för dessa tjänstetyper blir därmed speciella. I servicemetadata som dessa tjänstetyper erbjuder beskrivs både vilka operationer de tillhandahåller och vilka data som ingår. Vid publicering av WPS och WS till portalen kommer fokus att vara bara på vilka operationer som tjänsterna tillhandahåller och vilken ingående och utgående information som tjänsten konsumerar/producerar.

PM 4(13) 3.3 En WMS-tjänsts beståndsdelar 3.3.1 Tjänst, lager och datamängder En tjänst består av ett antal lager. Dessa lager kan innehålla geografiskt heterogen information över skilda geografiska områden och med skilda geografiska referenssystem. Det tematiska innehållet kan även variera. Men det är även möjligt att skapa en tjänst med data som täcker ett specifikt område för presentation i ett gemensamt geografiskt referenssystem och som innehåller data för ett specifikt tematiskt område. Denna flexibilitet gör att dokumentationen av tjänsterna måste vara flexibel och tillgodose ovanstående varierande behov. Därför beskrivs tjänsten separat från de ingående datamängderna. Det är möjligt för en datamängd att användas som datakälla i olika lager i två skilda tjänster. Historiskt har i flera fall WMS tjänster publicerats efter tre olika principer Tjänsten innehåller ett fåtal tematiska lager samt en bakgrundskarta som referens. Tjänsten behövde alltså ingen extern tjänst för att kunna användas Tjänsten innehåller ett fåtal lager med ett närliggande tematiskt innehåll Tjänsten innehåller et stort antal lager med stora skillnader i tematiskt innehåll, aktualitet mm. Med denna utgångspunkt har det för de två översta typerna räckt att beskriva hela tjänsten med metadata då denna har haft ett så homogent och specialanpassat innehåll. Men med det tredje alternativet blir tjänsterna så pass heterogena att det inte räcker med en metadatapost för tjänsten som helhet.

PM 5(13) För att kunna hantera ovanstående vid publiceringen till portalen i version 3.0 är det därför möjligt att publicera metadata om en datamängd som har flera olika distributionsformer. För en och samma datamängd kan det alltså vara möjligt att den har exempelvis: - En länk till en nedladdningsbar zip-fil med data - En länk till en tjänst där datamängden är datakälla till ett lager eller flera lager - En länk till ytterligare en tjänst där datamängden är datakälla till ett annat lager Ovanstående synsätt delas inte av alla. I många länder har man hittills inte dokumenterat tjänster på datamängdnivå utan endast dokumenterat tjänsterna som helhet. Detta är delvis styrt av ambitionsnivå då arbete blir mer omfattande när varje enskild datamängd skall dokumenteras. Inom Inspire krävs dock dokumentation av en tjänsts ingående datamängder. Inom arbetet med den svenska infrastrukturen har vi dock ansett att informationen för användaren inte blir tillräckligt användbar om inte de ingående datamängdernas relation till lager i en tjänst blir tydligt för användaren. 3.4 Dokumentation av tjänsten 3.4.1 Alternativ för dokumentation av en WMS-tjänst En WMS-tjänst kan dokumenteras på två olika sätt. Via dokumentation med en metadatapost enligt ISO19115/ISO19139. Genom att tjänsten dokumenteras i sin helhet i tjänstens Capabilities-dokument Orsaken till att båda ovanstående metoder för att dokumentera en tjänst finns är att de standarder som idag används har tagits fram genom 2 olika organisationer. WMS-tjänster och dess hantering av metadata som del av tjänstens gränssnitt ( via metoden GetCapabilities) har utvecklats av OGC (Open Geospatial Consortium). ISO har parallellt med detta arbetat fram standarderna ISO19115 för generella metadata och ISO19119 för metadata om tjänster. Arbete pågår att försöka få en enhetlig hantering av ovanstående 2 standarder, men fram tills dessa metoder existerar är en enhetlig metodik det bästa vi kan åstadkomma. Det finns även en tredje möjlighet att dokumentera en tjänst och då mera ur ett tekniskt gränssnittsperspektiv. Det är beskrivning av en tjänst med en wsdl-fil. Detta används huvudsakligen för beskrivning av generella webbservices. Principiellt ligger en WMS-tjänsts capabilities-dokument nära innehållet i en wsdl-fil. Det pågår därför diskussioner hur ovanstående tre metoder för dokumentation skall kunna integreras så metadata inte behöver hanteras på fler ställen. Dock har inga tydliga lösningar på detta framtagits som kan användas ännu. 3.4.1.1 Dokumentation med ISO19115 Tjänsten kan dokumenteras i sin helhet med metadata i ISO19115/ISO19119 så att metadata följer Inspires krav. Detta kan

PM 6(13) exempelvis göras i Redigeringsverktyget för metadata eller i de webbaserade formulären. 3.4.1.2 Dokumentation med Capabilities-dokument En WMS-tjänst har en adress som kan anropas med tre huvudsakliga operationer. GetCapabilities GetMap GetFeatureInfo WMS-tjänsten har alltså definierad adress som kan svara på dessa anrop. Metadata för tjänsten kan beskrivas i tjänstens Capabilities-dokument. Dock kan inte all information som hanteras i ISO19115 anges i Capabilities-dokumentet. Därför är det just nu rekommenderat att tjänstens fullständiga metadata hanteras i ett metadatadokument enligt ISO19115. Längre fram i texten beskrivs fler alternativ för att hantera tjänstemetadata enligt Inspires krav. 3.4.2 Metadata för en wmstjänst och dess komponter WMS-tjänst Lagermetadata Capabilities ISO19115 MD ISO19115 MD Tjänste metadata ISO19115 MD ISO19115 MD ISO19115 MD ISO19115 MD Figur 1 Beskriver hur tjänster kan beskrivas med metadata. Tjänsten kan beskrivas i ett capabilitiesdokument som är integrerat i kartjänsten (wms-tjänsten). Varje lager i tjänsten kan även beskrivas med en metadatapost enligt ISO19115. Hela tjänsten kan även dokumenteras med ett dokument enligt ISO19115. Capabilities En wms-tjänst är dokumenterad med ett capabilities-dokument. Detta beskriver tjänsten som helhet men även dess ingående lager. I varje lager

PM 7(13) som beskrivs capabilties-dokumentet kan man referera (via MetadataURL) till ett metadata dokument i ISO19115 som beskriver varje enskilt lagers datamängd. Lagermetadata Varje enskilt lager/datamängd i tjänsten kan beskrivas med metadata enligt ISO19115. Dessa lager definieras som datamängder. Tjänstemetadata ISO19115/ISO19119 Tjänsten kan som helhet även beskrivas med ett metadatadokument enligt ISO19115/ISO19119 Relationer mellan tjänstemetadata i ISO19115/ISO19119 och Lagermetadata Som pilarna i figuren ovan visar kan man skapa relationer mellan Tjänstemetadata i ISO9115/ISO19119 och dess ingående lager. Det gör att man för tjänsten kan beskriva vilka datamängder som ingår i tjänsten och att man för den omvända relationen kan för en datamängd ange vilken tjänst detta ingår i. För att beskriva i dokumentationen för en tjänst vilka lager som ingår kan man använda elementet Kopplade resurser 3.4.3 Lager respektive datamängder i en WMStjänst En tjänst har en eller flera lager definierade i sin capabilities-fil. Det är även lager (Layer) som anropas när man vill ange vilka delar av en tjänst som skall ritas upp. Dock är det normalt den underliggande datamängden som skall dokumenteras och publiceras som metadata. Det är dock inte allrid ett 1-1 för hållande mellan ett lager och dess data. Som figuren nedan visar kan en datamängd ingå i flera olika lager. Det kan vara skillnader mellan olika lager som använder samma datamängd som exempelvis: Skala som lagren visas i Symboliseringen kan variera Urval av objekt kan variera

PM 8(13) I normalfallet är det alltså de underliggande datamängderna som skall dokumenteras. 4 Princip för dokumentation av wms-tjänster Nedanstående kan ses som en vägledning till hur en tjänst och dess ingående lager kan dokumenteras. Genom att följa principerna för denna så uppfyller man kraven från Inspire och tar fram olika dokument i den ordning som behövs. 4.1 Dokumentera och publicera datamängder som ingår i tjänsten En tjänst använder en eller flera datamängder för att skapa en kartbild. Respektive datamängd skall publiceras till portalen. 4.2 Dokumentera tjänsten som helhet En metadatapost som beskriver hela tjänsten skall skapas och publiceras till katalogtjänsten All information om tjänsten kan inte skapas i detta första steg, men genom att skapa en metadatapost för tjänst erhålls en unik metadataidentifierare för tjänstens metadatapost som skall användas senare. Tjänster skall för att följa Inspires förordning om tjänster ha en utökad beskrivning (extended capabilities) av tjänsten i capabilities-dokument. Dessa extended catabilities kan hanteras på två olika enligt Technical Guidelines för visningstjänster. Capabilities-dokumentet utökas med ett element MetadataURL för hela tjänsten som helhet. Denna URL skall peka på metadataposten i katalogtjänsten i ISO19115/IUSO19119 som beskriver tjänsten i sin helhet, detta motsvarar metadata som skapas i kapitel 3.4.1.1 ovan. Alternativt utökas capabilities-dokumentet med ytterligare extended capabilities så att det kan hantera alla de metadata som Inspire kräver av en tjänst och dess underliggande datamängder.

PM 9(13) I nuläget rekommenderar vi myndigheter att använda metoden enligt första punkten i punktlistan ovan. Det är enligt denna metod som nedanstående beskrivningar är avpassade till. 4.3 Ange kopplade resurser för tjänsten De publicerade datamängder (1 ovan) skall refereras från tjänstens metadatapost via elementet kopplade resurser (OperatesOn) som anges för en tjänst. OperatesOn är ett metadataelement som används vid dokumentation av tjänster. För varje ingående datamängd som ingår i tjänsten skall en post med OperatesOn anges. OperatesOn skall anges både för lokala specifikation och för data som följer Inspires specifikationer. Detta anges i tjänstens metadatapost enligt ISO19115/ISO19139. Exempelvis om en wmstjänst för sin presentation använder två datamängder som har identifierare för metadatamängd a5c7dbfb-6865-473d-a9bf-dec0e158380b respektive 83d7684e-ac3f-45a3-8aca-373a9489d07. Då skall man in ISO19115/ISO19139-metadata för tjänsten ange två förekomster av operateson som pekar på metadataposten. 4.4 Dokumentera hela tjänsten i tjänstens capabilitiesdokument Dokumentera tjänstens egenskaper i capabilities-dokument. Med den metod som anges här följer man principerna för WMS 1.3.

PM 10(13) 4.4.1 Ange MetadataURL för tjänsten som helhet En MetadataURL som anges för hela tjänsten som sådan skall peka in i katalogtjänsten på det metadatadokument som beskriver tjänsten (4.2 ovan) För att ange en referens till metadata för hela tjänsten anges i capabilitiesfilen följande information: Denna MetadataUrl pekar in i Geodataportalen katalogtjänst och refererar till en metadatapost med UUID qc7f8260-3pe9-66e0-9031- d15699a4fda4. Denna metadatapost beskriver tjänsten som helhet i ISO19115/ISO19119 enligt Inspires krav. Genom att denna adress är angiven kan klienter som använder tjänsten hämta och visa metadata för tjänsten. 4.4.2 Ange MetadataURL för varje ingående lager Varje lager i en tjänst skall ha en MetadataURL som pekar ut den datamängd som detta lager arbetar mot. Det innebär att flera lager kan ha samma MetadataURL. Dock kan inte flera datamängder ingå i ett lager (vad gäller metadataurl) <MetadataURL type="tc211"> <Format>text/html</Format> <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:href=" http://www.geodata.se/geonetwork/srv/en/csw? UUID=44d5c95b-ba75-4510-9a77-ac8e1ad535a4"/> </MetadataURL>

PM 11(13) Ovanstående utdrag från ett capabilities-dokument visar hur man för ett lager i tjänsten anger en referens till metadata för den till lagret underliggande datamängden. 4.5 Ange länkar till lager i wms-tjänst vid registrering av datamängder För att datamängder som ingår i en tjänst skall vara lätt åtkomliga att finna igen skall man för en datamängd ange länken via Online-linkage till de lager som datamängden presenteras via. Detta är en rekommendation från Geodataportalen och ej ett krav från Inspire. Varje datamängd som dokumenteras som är en del av en WMS-tjänst rekommenderas ha en onlinelinkage till de lager som denna datamängd verkar mot. I adressen skall layer=lager1,lager2 etc. användas. Namnet på OnlineLinkage kan lämpligen vara samma titel som för Titleelement i capabilities. Exempelvis om en tjänst är dokumenterad som har adressen http://map.smhi.se/geoserver/wms I denna tjänst ingår en datamängd som innehåller avrinningsområden. Detta lager i wms-tjänsten heter SMHI_avromr. Då är det lämpligt att i metadata för datamängden ange en online-länk till http://map.smhi.se/geoserver/wms?layers=smhi_avromr <srv:operateson xlink:type="simple" xlink:title="hastighetsgräns" xlink:href="http://www.geodata.se/geonetwork/csw/?service=csw&version=2.0.2& request=getrecordbyid&id=58e79a60-4a59-405e-9bea-d821cc333a03"/> 4.6 WFS-tjänster Utförligare beskrivning kommer i kommande versioner av dokumentet 4.7 WPS-tjänster Utförligare beskrivning kommer i kommande versioner av dokumentet

PM 12(13) 5 Dokumentation av generella webbservices ex SOAP- eller RESTtjänster Även generella webbservices som inte direkt genererar en kartbild kan publiceras till Geodataportalen. Exempel på sådana typer av webbservices är SOAP-tjänster REST-tjänster I princip kan alla typer av tjänster dokumenteras och publiceras med ISO19115/ISO19119. Dessa kan normalt inte förhandsgranskas i Geodataportalen på samma sätt som WMS men de kan dokumenteras med liknande metadata som övriga tjänster. Utöver de metadata för tjänster som normalt rekommenderas är det därför lämpligt att ytterligare dokumentation av tjänsten görs tillgänglig via en länk från metadataposten. Det kan vara en länk till en webbsida eller ett pdf-dokument. Det man normalt beskriver i ett sådant dokument är exempelvis: Metoder och anrop som webbservices stöder Exempel på användning Länk till wsdl-fil Det är i huvudsak teknisk information riktat till utvecklare eller systemintegrerare så att man vet hur tjänsten kan användas. För en WMStjänst finns motsvarande information i capabilities-dokumentet.

PM 13(13)