Veileder for utarbeidelse av Produktspesifikasjoner i Norge digitalt Versjon 0.5 (2012-10-19) 1 Hva er en produktspesifikasjon En produktspesifikasjon er en detaljert beskrivelse av et datasett eller datasettserier (produktgruppe) med tilliggende informasjon som vil gjøre det mulig å fremstille produktet gi brukere tilgang til et produkt gi brukere muligheten til å vurdere om et produkt er egnet til en tiltenkt bruk En produktspesifikasjon gir en beskrivelse av interesseområdet/fagområdet samt en mapping fra den generell beskrivelse av dette fagområdet til et datasett. 1.1 Hva en produktspesifikasjon skal brukes til En produktspesifikasjon kan benyttes for produksjon, salg, sluttbruk av et produkt, samt for andre formål. Mer detaljert kan den brukes til: Holde oversikt over egne produserte data Holde oversikt over datasett ved bestilling av data Den mest presise måten å fortelle hva som skal leveres Solid grunnlag for å kontrollere at leveransen er slik den skal være (SOSIkontroll) Leveranse av data Den beste måten å fortelle mottakere hva produktet er Styre forventninger Unngå erstatningskrav Svært godt grunnlag for å sette opp tjenester som bruker dataene som inngår i et produkt, herunder Tjenesteorientert arkitektur og Modelldrevet arkitektur (MDA) 1.2 Hvilken dokumentasjon finnes for å lage produktspesifikasjoner Det finnes mange dokument som forteller om ulike sider av det å lage og bruke en produktspesifikasjon.
Noen dokumenter er laget for å ha spesielle roller i forbindelse med utarbeidelse av produktspesifikasjoner. Dokumenter i denne kategorien er listet med egne underkapitler i dette kapittelet Underliggende veiledere, standarder. Disse finnes i referanselista for hvert av dokumentene. Eksempel: SOSI Del 1 Retningslinjer for UML-modellering, Veileder i installasjon og bruk av SVN. Eksempel på eksisterende produktspesifikasjoner, som kan være maler for andre som skal lages, eksempel: Produktspesifikasjon Primærdata Kystkontur Ulik dokumenter på ulikt nivå: - Produktspesifikasjoner - Norsk profil av NS-EN ISO 19131 v0 5 - Installasjon av nødvendig programvare for arbeid med produktspesifikasjoner - Løype for å modellere en produktspesifikasjon som et utplukk av objekttyper fra SOSI del 2 v0 7-1.2.1 Veileder for utarbeidelse av produktspesifikasjoner i Norge digitalt (Dette dokumentet som du leser i nå) Det har til hensikt å beskrive hvordan en utarbeider en produktspesifikasjon, fra starten til den er ferdig. Dokumentet er tilgjengelig på Kartverkets SOSI-sider, se http://www.kartverket.no/sosi 1.2.2 Norsk profil av Geografisk informasjon Produktspesifikasjoner Dette dokumentet tilpasser metodene og prinsippene i NS-EN ISO19131 til norske forhold. Den definerer bl.a. norske navn på en del av begrepene. Dokumentet er tilgjengelig på Kartverkets SOSI-sider, se http://www.kartverket.no/sosi 1.2.3 NS-EN ISO19131:2008 Geografisk informasjon Produktspesifikasjoner Denne har også et endringsblad NS-EN ISO 19131:2008/A1:2011. Standarden kan kjøpes fra StandardNorge, se http://www.standard.no 1.2.4 Om bruken av dokumentene Dokumentene er lagt opp slik at dokumentet Veileder for utarbeidelse av produktspesifikasjoner i Norge digitalt er det naturlige startstedet når en planlegger en å lage en produktspesifikasjon. Her vil en finne beskrivelse av de ulike trinnene i løypa fram mot ferdig produktspesifikasjon. Dokumentet har henvisninger videre til andre dokumenter som er nødvendige/nyttige i arbeidet med produktspesifikasjoner. Disse kan det være hensiktsmessig å slå opp når en trenger mer info om enkelte av trinnene.
2 Krav til en produktspesifikasjon Dette er en oppsummering av noen av de overordnede kravene som gjelder til en produktspesifikasjon. De er tatt med her, fordi det er nyttig å ha en oversikt over kravene når en er i oppstarten på å lage en produktspesifikasjon. Siden dette er en veileder, er ingen av kravene original-formulert her, men er kun gjengivelse av krav stilt i andre dokumenter. De fleste av kravene kommer fra Norsk profil av NS-EN ISO19131 2.1 Krav om utarbeidelse av produktspesifikasjoner Alle som etter partsavtaler i Norge digitalt skal levere data inn til Norge digitaltsamarbeidet, skal ha produktspesifikasjoner for det som skal leveres. (Kilde: Norge digitalt partsavtalen). For data som ikke inngår i Norge digitalt-samarbeidet, er det formelt ikke noe krav om produktspesifikasjoner, men likevel nyttig å ha. 2.2 Hvordan en produktspesifikasjon skal se ut En produktspesifikasjon skal ha et forhåndsdefinert innhold (stort sett basert på NS- EN ISO 19131) og følge et vedtatt oppsett. Dette er bl.a. angitt med En forhåndsdefinert kapitelinndeling Teksten i de ulike kapitlene og underkapitlene skal følge bestemte regler For noen av underkapitlene skal produktspesifikasjons-tekstene henvise til forhåndsdefinerte kodelister.??? Alle krav er referert og forklart i dokumentet SOSI standard veiledning for utarbeidelse for produktspesifikasjon Bør samles med pkt. 2.3 2.3 Ferdigredigering, godkjenning, arkivering og tilgjengeliggjøring av produktspesifikasjoner Egne underpunkter for hvert moment, alternativt egne kapitler for hver syklus/fase. Bør vi ha med en skisse som viser hele livssyklusen til produktspesifisering? 2.3.1 Ferdigredigering En dataeier skal lage en mest mulig ferdig produktspesifikasjon. Dette inkluderer arbeidet med å fylle ut alle påkrevde feltene i et produktspesifikasjons-dokument. I tillegg inkluderer det å fylle inn alle andre felt som er nødvendige for det spesielle produktet. 2.3.2 Godkjenning De produktspesifikasjonene som skal inngå i den nasjonale infrastrukturen, skal godkjennes av nasjonal geodatakoordinator. Godkjente produktspesifikasjoner blir en del av SOSI Del 3. For godkjente produktspesifikasjoner vil det også bli utarbeidet SOSI-kontroll definisjonsfiler, slik at brukere kan kontrollere om et datasett som sier det skal være i henhold til en produktspesifikasjon, faktisk er det. SOSI-kontroll definisjonsfilene for godkjente produktspesifikasjoner vil bli distribuert sammen med SOSI-vis/SOSI-kontroll.
2.3.3 Arkivering Dataeier er ansvarlig for at produktspesifikasjonen og tilhørende dokumentasjon, arkiveres på en forsvarlig måte. Dette vil gjøre arbeidet med eventuelle oppdateringer lettere. For godkjente produktspesifikasjoner som inngår i SOSI Del 3, vil UML-modellene (representert som XMI-filer) være arkivert/forvaltet i SOSI-standardens SVN-arkiv. 2.3.4 Tilgjengeliggjøring Nasjonal geodatakoordinator skal sørge for et opplegg som gjør at ferdige produktspesifikasjonene som inngår i den nasjonale infrastrukturen er tilgjengelig på en omforent måte, og slik at brukerne enklest mulig får tilgang til produktspesifikasjonen i den formen som passer med brukerbehovet. 2.4 Krav til produktspesifikasjons-disposisjon En produktspesifikasjon skal følge en nærmere angitt disposisjon. Disposisjonen inneholder alle påkrevde og valgfrie deler. I de tilfeller der en del ikke er relevant for en bestemt produktspesifikasjon, skal dette angis med tekst ikke relevant. Ingen kapitler i disposisjonen skal utelates. Er ikke dette det samme som 2.1? Bør samles.
1. Forberedelse Klargjøre det som skal til for å lage en produktspesifikasjon 2. Beskrive hensikten/bruk Klargjøre hva som er hensikten og hovedbruken av produktspesifikasjonen 3. Faglig introduksjon Forklare for brukerne hvilke faglige prinsipper som ligger til grunn 4. Datainnhold Avklare hvilke objekttyper som trengs i en produktspesifikasjon. Datainnholdet må tilpasses hensikten 5. Applikasjonsskjema Lage applikasjonsskjemaet for produktspesifikasjonen (UML) 6. Datakvalitet Stille kvalitets-krav til dataene (nøyaktighet, fullstendighet, logisk konsistens) 9. Identifikasjon Produktspesifikasjonen som inngår i den nasjonale infrastrukturen skal ha et entydig navn 10. Datafangst Dersom det er spesielle bestemmelser om datafangsten, skal dette dokumenteres 11. Vedlikehold Dersom det er forventet at produktene skal vedlikeholdes/ ajourholdes, må dette beskrives 12. Presentasjon Dersom det er spesielle krav til hvordan produktet skal presenteres/visualiseres, må dette dokumenteres 13. Tillegg Dersom det trengs å sies mer om produktene, som ikke passer inn noen andre steder, settes dette 7. Referanse-system Bestemme hvilke referasesystem som skal brukes. NB! Sterke føringer i nasjonale bestemmelser 14. Metadata Hva som trengs for å dokumentere et datasettene 8. Leveranseinformasjon Avklare hvordan produktet skal kunne leveres til brukere 15. Avsluttende arbeid Fylle ut resten av innholdet Figur 1 Trinnene i løypa for å lage en produktspesifikasjon
3 De enkelte trinnene i arbeidet med en produktspesifikasjon Trinnene i produksjonsløypa er angitt på figur 1. Her følger en litt mer utfyllende forklaring på hvert av trinnene. Hvert av punktene under, vil ha referanse til kapitler i Norsk profil av NS-EN ISO19131. 3.1 Forberedelse Første trinn i å lage en produktspesifikasjon er å forsikre seg om at en kjenner til det området produktspesifikasjonen skal dekke. Dette gjelder både det faglige innholdet (være domene-ekspert) og kjenne til nødvendig bakgrunns-informasjon: Prinsippene for å lage produktspesifikasjoner Hva SOSI Del 2 Generell objektkatalog inneholder og som er relevant for produktspesifikasjonen?? mer??? 3.2 Beskrive hensikten/bruken av produktet 6.3 Sammendrag 6.4 Formål Et produkt har ofte (alltid?) en spesiell hensikt. Hensikten er i de aller fleste tilfeller styrende for hvilke data (se Datainnhold og Applikasjonsskjema) produktet må inneholde. Hensikten bør beskrives mest mulig presist. En presist formulert hensikt vil hjelpe de som senere vurderer om produktet kan passe en tiltenkt bruk. Det kan godt hende at et produkt som er laget med en bestemt hensikt, kan passe perfekt til oppgaver som ikke ble tenkt på av den som spesifiserte produktet. Dokumentasjon av hensikten med et produkt lages derfor ikke for å hindre bruk utenfor hensikten, men for å forklare hva produsenten planla av bruk. 3.3 Faglig introduksjon 4.1.5 Hovedtema for dataproduktet 4.2 Definisjoner og forklaringer 4.3 Forkortelser En produktspesifikasjon skal være primær-kilden til informasjon om produktet. For å forstå bakgrunnen og anvendelsen til produktet, kan det derfor være hensiktsmessig å ha en faglig introduksjon til produktet. Her kan faguttrykk og fagprinsipp forklares. Forklaringen bør være tilstrekkelig for brukerne, og kan gjerne inneholde referanser til mer utfyllende stoff for de med spesielle interesser. 3.4 Datainnhold 4.4 Beskrivelse av produktet 7.1.1 Detaljert beskrivelse Dette er en beskrivelse av datainnholdet ved bruk av vanlig språk. Her kan en forklare hvilke objekttyper, egenskaper og assosiasjoner som er med i datasettet.
3.5 Applikasjonsskjema 7.1.3 Applikasjonsskjema Applikasjonsskjemaet er en formell definisjon av datainnholdet. Den skal følge klare regler for det språket som benyttes. Et applikasjons-skjema skal beskrives i UML (Unified Modelling Language). Det er utarbeidet en frittstående veileder for dette. I den veilederen forklares hvordan en henter fagområdemodeller fra SOSI Del 2 sammen med forklaringer til de verktøy som anbefales brukt. 3.6 Datakvalitet 9 Data kvalitet Annex A For at et produkt skal kunne brukes til det som er hensikten med produktet, må visse kvalitetskrav være oppfylt. Kvalitets-kravene skal settes opp etter reglene i ISO19113/ISO19114 og ISO19115. Det er rimelig at ulike deler av innholdet har ulike kvalitets-krav. Kvalitets-elementene i ISO19115:2005 er laget for å dekke ulike aspekter av kvalitetskrav: Fullstendighet: samsvar mellom det som finnes i datasettet og det som burde ha vært der. Stedfestingsnøyaktighet: samsvar mellom de posisjonsangivelsene som finnes i datasettet, og fasitverdiene for de samme. Egenskapsnøyaktighet: samsvar mellom de egenskapsverdiene som finnes i datasettet, og fasitverdiene for de samme. For egenskaper som er angitt med tall, kan en beregne forskjeller numerisk. For kodeverdier angis klassifikasjonsnøyaktighet Tidfestingsnøyaktighet: Nlyaktigheten på tidsangivelser Logisk konsistens: Hvor godt dataene samsvarer med regler som er gitt i produktspesifikasjonen (og underliggende dokumentasjon). Eksempel: At phverdier for et vann er mellom 0 og 14, at kodeverdier er plukka fra korrekt kodeliste. Kvalitets-elementene i ISO19115 er underinndelt i kvalitets-del-elementer. For hvert kvalitets-del-element er det definert opp kvalitets-mål. Kvalitets-målene er metoder for å tallfeste kvaliteten knytta til et kvalitets-element på en entydig måte. Eksempel: For kvalitets-element Stedfestingsnøyaktighet, kvalitets-del-element Absolutt grunnrissnøyaktighet finnes kvalitets-målene Standardavvik, og Prosentandel grove feil. De to kvalitets-målene angir den absolutte stedfestingsnøyaktigheten på to ulike måter. Kvalitets-kravene i en produktspesifikasjon settes opp ved å velge et passende kvalitets-mål og beskrive grenseverdier (maks tillatt verdi).
Figur 2 Eksempel på kvalitets-krav (Kilde: FKB) 3.7 Referansesystem 8 Referansesysteminformasjon 3.8 Leveranseinformasjon 13 Leveranseinformasjon Leveranseinformasjonen skal fortelle hvordan produktet skal leveres ut til de som skal bruke produktet. 3.9 Datafangst (frivillig) 10 Datafangst Dersom et produkt har spesielle krav til hvordan produktet skal produseres (for eksempel datainnsamlingsmetoder) skal dette beskrives. Dersom en mener at alle produktsjonsmetoder er ok, bare en oppfyller kravet til innhold og kvalitet, trenger en ikke si noe spesielt om datafangst. 3.10 Vedlikehold (frivillig) 11 Vedlikehold For produkter det er det legges opp til vedlikehold/oppdatering av produktet, skal dette beskrives. De produktene som har mer karakter av engangsleveranse trenger ikke noe informasjon om vedlikehold. NS-EN ISO19131 krever kun at vedlikeholdsrutinene beskrives med fritekst.
3.11 Presentasjon (frivillig) 12 Presentasjonsinformasjon Applikasjonsskjemaet for produktet sier noe om den interne datastrukturen i datasettet. Dersom det ansees viktig at produkt basert på produktspesifikasjonen skal presenteres /tegnes på en bestemt måte, skal dette beskrives. Merknad: NS-EN ISO19131 krever at presentasjonsinformasjonen struktureres/defineres iht ISO19117 Portrayal, og at produktspesifikasjonen kun har en peker til en slik presentasjonskatalog. Dette er en standard vi i Norge har svært liten erfaring med. I mangel på erfaring. I mangel på erfaringer med dette, tillates det at det refereres også til anna form for presentasjons-regler. Eksempel på presentasjonsregler som er laget for å standardisere presentasjoner av data er Miljøverndepartemenetets tegneregler for arealplaner, se Nasjonal Produktspesifikasjon for arealplan og digitalt planregister, del 2 Spesifikasjon for tegneregler, tilgjengelig på http://www.regjeringen.no/kartforskriften. 3.12 Tillegg (frivillig) 14 Tilleggsinformasjon Dersom det finnes noe viktig å si om produktet som ikke passer inn noen andre steder, kan dette legges i kapittelet Tillegg. 3.13 Metadata 15 Metadata Et produkt skal dokumenteres med et sett av metadata-elementer. Den norske profilen av ISO19115, har ei liste med påkrevde metadata-elementer. Alle disse skal være i metadata-settet til alle produkt. Det at denne lista med påkrevde metadataelement skal være med, trenger ikke noen egne utsagn. Dersom det for produktet kreves metadata-elementer ut over de generelt påkrevde, skal disse tilleggs-metadata-elementene angis 3.14 Avsluttende arbeid Ved å gå gjennom løypepunktene over, er ryggraden i produktspesifikasjonen klarlagt. Noe av dette skal imidlertid legges inn flere plasser. I det etterfølgende nevnes kun påkrevde deler. For å finneut hva mer som kan legges inn, anbefales å lese gjennom hele NS-EN ISO 19131. De påkrevde delene som ikke er dekket lenger oppe, er: 3.14.1 Tildele produktspesifikasjonen en unik ID 4.1 Identifisering.. 6.1 Referansenavn
3.14.2 Temakategori 6.5 Temakategori Produktspesifikasjonen skal tildeles en temakategori. Dette gjøres ved å plukke fra ei kodeliste.
Vedlegg 1 Kapittelinndeling til en produktspesifikasjon I dette vedlegget er kapitlene i produktspesifikasjonen angitt.