Julkishallinnon XML-skeemat v0.5 JHS-suositus Keskustelutilaisuus 22.10.2008, Kansallismuseon auditorio Lasse Akselin TietoEnator lasse.akselin@tietoenator.com
Sisällys Johdanto Nimeämissäännöt Skeemojen tekemisen perusohjeita Nimiavaruudet Skeemojen modulaarisuus ja hierarkkisuus Versiointi ja merkistö Osasto 22.10.2008 22.10.2008 2
Johdanto
Työn päätavoitteet Julkisen hallinnon XML-skeemojen muodostamisen yhteiset periaatteet Alustava useille julkishallinnon toimijoille yhteinen skeemaluettelo Osasto 22.10.2008 22.10.2008 4
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 22.10.2008 22.10.2008 5
Suosituksen kohderyhmät Julkishallinnon tietojärjestelmien kehittäjät Järjestelmäkehityshankkeiden vetäjät ja asiantuntijat Osasto 22.10.2008 22.10.2008 6
Sanastotyön ja XML-skeemojen yhteys Sanasto XML-skeemakirjasto Osasto 22.10.2008 22.10.2008 7
Nimeämissäännöt
XML-rakenteiden nimeäminen Lähtökohta: ISO 11179-5 standardi Kolmitasoinen nimeämismalli Objektiluokka (Object class) Ominaisuustermi (Property term) Ilmentymä (Representation term) Esimerkkejä: KatuNimi, SukuNimi, HenkiloTunnus TuloVerotettavaMaara Objektiluokka Ominaisuustermi Ilmentymä Osasto 22.10.2008 22.10.2008 9
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 22.10.2008 22.10.2008 10
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 22.10.2008 22.10.2008 11
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 22.10.2008 22.10.2008 12
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 22.10.2008 22.10.2008 13
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 22.10.2008 22.10.2008 14
Ilmentymät (Representation Terms) Ilmentymä (Representation Term) on elementin nimen loppuun liitettävä termi, joka kuvaa elementin sisällön tyypin Osasto 22.10.2008 22.10.2008 15
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 22.10.2008 22.10.2008 16
Skeemojen tekemisen perusohjeita
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 22.10.2008 22.10.2008 18
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 22.10.2008 22.10.2008 19
Tyyppimäärittelyt Tyyppi Selite Esimerkki xs:string merkkijono Kotitaloustyö xs:integer kokonaisluku -123 xs:decimal desimaaliluku -2.54 xs:time kellonaika 12:00:00 xs:date päivämäärä 2006-06-14 xs:datetime ajankohta 2006-06-14T12:00:00 xs:boolean totuusarvo (true/false) true Osasto 22.10.2008 22.10.2008 20
Ilmentymien ja tietotyyppien vastaavuudet XML-skeemassa elementtien tietotyypit esitetään W3C:n XML Schema -suosituksen perustyyppeinä Osasto 22.10.2008 22.10.2008 21
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 22.10.2008 22.10.2008 22
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 22.10.2008 22.10.2008 23
Nimiavaruudet
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 http://www.w3.org/2001/xmlschema Lyhenne xs Nimiavaruuden nimen perusrakenne: perusosa/kohdealue/tarkenne/vuosi/kuukausi/päivä/ Julkishallinnon XML-skeemojen perusnimiavaruus (perusosa) on: http://skeemat.jhs-suositukset.fi/ [Huom! Nimiavaruudesta ei ole vielä tehty päätöstä.] Osasto 22.10.2008 22.10.2008 25
Nimiavaruuden muodostuminen - esimerkki perusosa/kohdealue/tarkenne/vuosi/kuukausi/päivä http://skeemat.jhs-suositukset.fi/yhteiset/osoite/2008/08/21 Osasto 22.10.2008 22.10.2008 26
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 22.10.2008 22.10.2008 27
Skeemojen modulaarisuus ja hierarkkisuus
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 22.10.2008 22.10.2008 29
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 22.10.2008 22.10.2008 30
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 22.10.2008 22.10.2008 31
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 22.10.2008 22.10.2008 32
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 22.10.2008 22.10.2008 33
Skeemojen xs:import-määritykset Alemman tason skeemat sisällytetään osaksi ylemmän tason skeemaa xs:import-määrityksillä Esimerkiksi: <xs:import namespace= "http://skeemat.jhssuositukset.fi/yhteiset/ Osoite/2008/08/21" schemalocation="jhs_osoite_20080821.xsd"/> Osasto 22.10.2008 22.10.2008 34
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>111111-1111</HenkiloTunnus> </Henkilo> Osasto 22.10.2008 22.10.2008 35
Versiointi ja merkistö
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 22.10.2008 22.10.2008 37
Merkistö XML-skeemoissa ja -sanomissa käytettävä merkkien koodaus (encoding) on UTF-8 Osasto 22.10.2008 22.10.2008 38
Lasse Akselin lasse.akselin@tietoenator.com GSM: 040-7280374 Osasto 22.10.2008 22.10.2008 39