Julkishallinnon XML-skeemat v0.5 JHS-suositus

Transkriptio

1 Julkishallinnon XML-skeemat v0.5 JHS-suositus Keskustelutilaisuus , Kansallismuseon auditorio Lasse Akselin TietoEnator

2 Sisällys Johdanto Nimeämissäännöt Skeemojen tekemisen perusohjeita Nimiavaruudet Skeemojen modulaarisuus ja hierarkkisuus Versiointi ja merkistö Osasto

3 Johdanto

4 Työn päätavoitteet Julkisen hallinnon XML-skeemojen muodostamisen yhteiset periaatteet Alustava useille julkishallinnon toimijoille yhteinen skeemaluettelo Osasto

5 Suosituksen lähtökohtia Pyrkimyksenä yksinkertaisuus ja käytännönläheisyys Tukeudutaan soveltuvin osin kansainvälisiin standardeihin sekä tunnettuihin referenssisuosituksiin Kansainvälisistä standardeista pyritään löytämään Suomen julkishallinnon kannalta parhaiten soveltuvia käytäntöjä Tavoitteena on varmistaa mahdollisimman hyvä yhteensopivuus kansainvälisiin standardeihin XML-skeemojen tuottamisella on läheinen yhteys sanastotyöhön Osasto

6 Suosituksen kohderyhmät Julkishallinnon tietojärjestelmien kehittäjät Järjestelmäkehityshankkeiden vetäjät ja asiantuntijat Osasto

7 Sanastotyön ja XML-skeemojen yhteys Sanasto XML-skeemakirjasto Osasto

8 Nimeämissäännöt

9 XML-rakenteiden nimeäminen Lähtökohta: ISO standardi Kolmitasoinen nimeämismalli Objektiluokka (Object class) Ominaisuustermi (Property term) Ilmentymä (Representation term) Esimerkkejä: KatuNimi, SukuNimi, HenkiloTunnus TuloVerotettavaMaara Objektiluokka Ominaisuustermi Ilmentymä Osasto

10 Yleisiä nimeämissääntöjä Elementtien ja attribuuttien nimet ovat ensisijaisesti suomenkielisiä Nimistä voidaan tehdä englanninkieliset käännökset Samassa skeemassa ei suositella käytettäväksi sekä suomen- että englanninkielisiä nimiä Nimet ovat kirjakielen muotoisia substantiiveja, verbejä ja adjektiiveja Substantiivit ovat lähtökohtaisesti yksikkömuodossa, ellei käsite itsessään ole monikkomuotoinen Skandinaaviset merkit EIVÄT ole sallittuja XMLsanomien elementti-, attribuutti- ja tyyppinimissä Osasto

11 Nimeämissääntöjä Elementtien nimeäminen Upper Camel Case Esim. KatuNimi Attribuuttien nimeäminen Lower Camel Case Esim. kielikoodi Tyyppien nimeäminen Upper Camel Case Nimen loppuun lisätään pääte Tyyppi Esim. HenkiloTunnusTyyppi Nimissä ei pidä käyttää alaviivaa ( _ ), pistettä (. ), väliviivaa ( - ) eikä muita aakkosten ulkopuolisia merkkejä. Nimissä saa käyttää numeroita ( 0-9 ). Osasto

12 Nimeämisesimerkkejä Käsite/termi Elementin nimi Attribuutin nimi Katuosoite KatuOsoiteTeksti katuosoiteteksti Henkilötunnus HenkiloTunnus henkilotunnus Pinta-ala PintaAlaMitta pintaalamitta maa- ja metsätalous MaaJaMetsatalous maajametsatalous (henkilön) verotettava tulo TuloVerotettavaMaara tuloverotettavamaara Osasto

13 Yleiset lyhenteet Yleisesti käytetyt tai tunnetut lyhennemerkinnät, joilla alkuperäistä sanaa lyhennetään merkittävästi Voi periaatteessa esiintyä missä kohdassa nimeä hyvänsä Lyhenteet kirjoitetaan isoilla tai pienillä kirjaimilla niiden tyypillisen käyttötavan mukaan. Lyhenne alkaa aina isolla kirjaimella. Jos sanastossa käytetään lyhennettä, samaa lyhennettä käytetään myös XML-skeemassa Osasto

14 Esimerkkejä lyhenteistä Lyhenne ALV ATK BKT CV db Dnro EU ICT ISBN Selite arvonlisävero automaattinen tietojenkäsittely bruttokansantuote lat. curriculum vitae, elämänvaiheet, elämäkerta; ansioluettelo desibeli(ä) diaarinumero Euroopan unioni engl. information ja communication technology, informaatio- ja kommunikaatioteknologia engl. International Standard Book Number, kirjan kansainvälinen standardinumero Osasto

15 Ilmentymät (Representation Terms) Ilmentymä (Representation Term) on elementin nimen loppuun liitettävä termi, joka kuvaa elementin sisällön tyypin Osasto

16 Termi Termi englanniksi Käyttötarkoitus Aika Time Kellonaika, ajankohta (ISO 8601) Arvo Value Numeerinen arvo Aste Rate Aste numeerisena arvo Binaari BinaryObject Binäärimuotoinen tieto Koodi Code Sallittujen arvojen luettelo, jonka jokainen yksittäinen arvo on merkkijono, jota käytetään korvaamaan tai edustamaan tiettyä koodatun tiedon arvoa tai määritelmää Kuva Graphic Kuvien tallennustyyppi Kytkin Indicator Kahdesta arvosta koostuva pari, joka ilmaisee tilaa on/off, true/false jne. (synonyymi: Boolean ) Lkm Quantity Muiden kuin rahayksikköjen lukumäärä Mitta Measure Numeerinen arvo, joka on määritelty mittaamalla jokin objekti. Mitta tarkennetaan mittayksiköllä. Maara Amount Rahallinen arvo valuuttayksikköinä Nimi Name Jonkin objektin identifiointiin käytettävä merkkijono. Toisin kuin tunnuksen, nimen ei tarvitse olla yksiselitteinen. Nro Number Numero Prosentti Percent Prosenttilukuna esitettävä numeroarvo Pvm Date Päivä kalenterissa, ajankohta (ISO 8601) PvmAika DateTime Päivä kalenterissa ja kellonaika, ajankohta (ISO 8601) Teksti Text Jonkin luonnollisen kielen merkkijono Tunnus ID, Identifier Merkkijono, jota käytetään muodostamaan jollekin objektin esiintymälle identiteetti tai erottamaan se muista yksiselitteisellä tavalla Osasto

17 Skeemojen tekemisen perusohjeita

18 Skeemojen tekemisen perusohjeita Elementtejä vai attribuutteja Ensisijaisena esitysrakenteena käytetään elementtejä Attribuutit sisältävät pääasiassa elementin sisällön arvoa kuvaavaa metatietoa Globaalit elementit Kaikki elementit tulee määritellä globaaleina <xs:element name="etunimi" type xs:string/> <xs:complextype name= HenkiloTiedotTyyppi > <xs:sequence> <xs:element ref="etunimi"/>... </xs:sequence> </xs:complextype> Osasto

19 Tyyppimäärittelyt Elementtien tyyppimäärittelyissä (SimpleType) käytetään pääsääntöisesti W3C:n XML Schema - suosituksen perustyyppejä XML Schema -suositus sisältää lisäksi muita perustyyppejä, joita ei ole taulukossa (seuraava kalvo) esitelty Käyttö voi olla perusteltua poikkeustapauksissa Poikkeukseen on oltava painava syy Osasto

20 Tyyppimäärittelyt Tyyppi Selite Esimerkki xs:string merkkijono Kotitaloustyö xs:integer kokonaisluku -123 xs:decimal desimaaliluku xs:time kellonaika 12:00:00 xs:date päivämäärä xs:datetime ajankohta T12:00:00 xs:boolean totuusarvo (true/false) true Osasto

21 Ilmentymien ja tietotyyppien vastaavuudet XML-skeemassa elementtien tietotyypit esitetään W3C:n XML Schema -suosituksen perustyyppeinä Osasto

22 Ilmentymä Aika Arvo Aste Binaari Koodi Kuva Kytkin Lkm Mitta Maara Nimi Nro Prosentti Pvm PvmAika Teksti Tunnus Tietotyyppi xs:time xs:decimal xs:decimal xs:binary xs:string xs:binary xs:string, xs:boolean xs:decimal xs:decimal xs:decimal xs:string xs:decimal xs:decimal xs:date xs:datetime xs:string xs:string Osasto

23 Koodistot Koodistot ovat standardoituja, vakiintuneita tai virallistettuja koodiluetteloita Koodistoa ylläpitää tavallisesti jokin nimetty taho Esimerkkejä yleisistä koodistoista ovat: Postinumerot Maakoodit Kielikoodit XML-skeemoissa koodistoja käytetään rajaamaan elementtien sallittuja arvoja XML-skeemamuotoisten koodistojen ylläpito tulee vastuuttaa Osasto

24 Nimiavaruudet

25 Nimiavaruuksien nimeäminen Jokaisessa skeemassa tulee nimetä kohdenimiavaruus (targetnamespace) Skeeman oletusnimiavaruus (default namespace) on sama kuin sen kohdenimiavaruus (targetnamespace) XML Schema -määritykseen kuuluvat osat tarkennetaan nimiavaruudella Lyhenne xs Nimiavaruuden nimen perusrakenne: perusosa/kohdealue/tarkenne/vuosi/kuukausi/päivä/ Julkishallinnon XML-skeemojen perusnimiavaruus (perusosa) on: [Huom! Nimiavaruudesta ei ole vielä tehty päätöstä.] Osasto

26 Nimiavaruuden muodostuminen - esimerkki perusosa/kohdealue/tarkenne/vuosi/kuukausi/päivä Osasto

27 Nimiavaruuksien nimeäminen URL-osoitteen käyttö nimiavaruuden nimenä mahdollistaa nimiavaruuden käyttämisen fyysisessä skeemaviittauksessa URL-osoitetta saa käyttää suoraan fyysiseen osoittamiseen On sallittua, että URL-osoitteeseen ei ole tallennettu skeemaa On suositeltavaa, että URL-linkin takaa löytyy vähintään skeemaa kuvaavaa dokumentaatiota Osasto

28 Skeemojen modulaarisuus ja hierarkkisuus

29 Skeemojen modulaarisuuden perusmalli Mallin tavoitteet: 1. Malli on tarpeeksi yksinkertainen, jotta sitä voidaan soveltaa käytännössä 2. Malli on riittävän monipuolinen, jotta se vähentää kehittäjien työtä skeemojen määrittelyssä 3. Kerran määritellyt skeemamääritykset ovat uudelleenkäytettäviä 4. Skeemojen elementtimääritykset voidaan johtaa suoraan sanaston käsitteistä Osasto

30 Skeemojen modularisoinnin perusmalli Organisaatio X Organisaatio Y Rajapintaskeemat Rajapinta_X1.xsd Rajapinta_X2.xsd Rajapinta_Y1.xsd Koosteskeemat Kooste_OrgX_ Henkilo.xsd Kooste_OrgX_ Osoite.xsd Kooste_OrgY_ Henkilo.xsd Kooste_OrgY_ Osoite.xsd Atomaaristen elementtien skeemat Yhteinen_ Henkilo.xsd Yhteinen_ Osoite.xsd Yhteinen_ KuntaNro.xsd... Yhteinen_ Yhteinen_ Xxx.xsd Yyy.xsd Osasto

31 Atomaaristen elementtien skeemat Atomaarinen elementtimääritys muodostuu yhdestä elementin määrittelystä, esimerkiksi: <xs:element name= HenkiloTunnus" type="xs:string"/> Yksi fyysinen skeematiedosto voi sisältää yhden tai useamman atomaarisen elementtimäärityksen Samassa tiedostossa olevilla määrityksillä yhteinen versiohistoria Skeemojen ja sanaston käsitteiden välinen yhteys Yhtä atomaarista elementtimäärittelyä vastaa yksi sanaston käsite Tavoitteena yhteisten käsitteiden käyttö sekä yhtenäinen skeemanimeäminen kaikilla kohdealueilla Osasto

32 Koosteskeemat Koosteskeema sisältää tietyn organisaation, kohdealueen, projektin tms. määrittelemän täsmällisen rakenteen jollekin elementtien joukolle Koosteskeema kootaan atomaarisista elementtimäärityksistä Koosteskeemassa voidaan määritellä elementtien järjestys ja pakollisuus Organisaatio voi julkaista uudelleenkäytettävän koosteskeeman julkiseen skeemahakemistoon, josta muutkin organisaatiot voivat hyödyntää sitä Osasto

33 Rajapintaskeemat Rajapintaskeema on jonkin organisaation palvelun tai järjestelmän edustalle kehitetyn rajapinnan tekninen sanomakuvaus Rajapintaskeemat muodostavat tyypillisesti kyselyvastaus-pareja Rajapintaskeemoista viitataan (xs:import) pääsääntöisesti atomaarisiin elementtimäärityksiin. Rajapintaskeemoista voidaan myös viitata uudelleenkäytettäviin koosteskeemoihin Rajapintaskeemoissa kiinnitetään muun muassa elementtien järjestys ja pakollisuus Isoissa rajapintaskeemoissa voidaan joutua tekemään jopa kymmeniä xs:import-määrityksiä Osasto

34 Skeemojen xs:import-määritykset Alemman tason skeemat sisällytetään osaksi ylemmän tason skeemaa xs:import-määrityksillä Esimerkiksi: <xs:import namespace= " Osoite/2008/08/21" schemalocation="jhs_osoite_ xsd"/> Osasto

35 Hierarkkiset XML-puurakenteet Sanomaskeemojen XML-rakenteissa pyritään mahdollisimman mataliin hierarkioihin Sallittujen hierarkiatasojen lukumäärää ei kuitenkaan täsmällisesti rajoiteta Pääsääntöisesti loogiset kokonaisuudet sisällytetään isä-elementin sisään. Esim. <Henkilo> <EtuNimi>Matti</EtuNimi> <SukuNimi>Meikäläinen</SukuNimi> <HenkiloTunnus> </HenkiloTunnus> </Henkilo> Osasto

36 Versiointi ja merkistö

37 Skeemojen versiointi Kaksitasoinen versiointi 1. Pääversio 2. Aliversio 1. Muutos vaikuttaa skeeman aikaisemman version mukaisten XML-instanssien validointiin Uusi versio ilmaistaan nimiavaruuden nimessä 2. Muutos ei vaikuta skeeman aikaisemman version mukaisten XML-instanssien validointiin Muutos ilmaistaan xs:schema-elementin xs:versionattribuutissa Numerointi aloitetaan aliversiosta 1.0. Osasto

38 Merkistö XML-skeemoissa ja -sanomissa käytettävä merkkien koodaus (encoding) on UTF-8 Osasto

39 Lasse Akselin GSM: Osasto