JHS XXX Julkishallinnon XML-skeemat

Transkriptio

1 JHS XXX Julkishallinnon XML-skeemat Versio: 0.99 Julkaistu: Voimassaoloaika asti Sisällys 1 Johdanto Soveltamisala Termit ja määritelmät Sanastotyön ja XML-skeemojen yhteys XML-rakenteiden nimeäminen Yleisiä nimeämissääntöjä Elementtien nimeäminen Attribuuttien nimeäminen Tyyppien nimeäminen Yleiset lyhenteet Ilmentymät (Representation Terms) Skeemojen tekemisen perusohjeistus Elementtejä vai attribuutteja Globaalit elementit Tyyppimäärittelyt Ilmentymien ja tietotyyppien vastaavuudet Koodistot Nimiavaruuksien nimeäminen Skeemojen modulaarisuus ja hierarkkisuus Skeemojen modulaarisuuden perusmalli Atomaaristen elementti- ja tyyppimääritysten JHS-skeema Koosteskeemat Rajapintaskeemat Skeemojen xs:import-määritykset Hierarkkiset XML-puurakenteet Skeemojen versiointi Julkishallinnon yhteisten skeemojen versiointi Organisaatiokohtaisten skeemojen versiointi Merkistö Opastavat tiedot Liitteet /23

2 1 Johdanto Tämä JHS-suositus ohjeistaa XML-skeemojen tuottamista ja hallintaa julkishallinnossa. Suosituksessa kuvataan julkisen hallinnon XML-skeemojen muodostamisen yhteisiä periaatteita. Lisäksi on laadittu alustava useille julkishallinnon toimijoille yhteinen skeemaluettelo. Suosituksessa tukeudutaan soveltuvin osin kansainvälisiin standardeihin sekä tunnettuihin referenssisuosituksiin. Suosituksen keskeisinä lähtökohtina on pidetty yksinkertaisuutta ja käytännönläheisyyttä. Kansainvälisiä standardeja ei suositella käyttöön sellaisenaan, vaan niistä on pyritty löytämään Suomen julkishallinnon kannalta parhaiten soveltuvia käytäntöjä. Samanaikaisesti tavoitteena on varmistaa mahdollisimman hyvä yhteensopivuus kansainvälisiin standardeihin. XML-skeemojen tuottamisella on läheinen yhteys sanastotyöhön. Tätä suositusta PITÄÄ noudattaa johdettaessa tekniikkaan sitomattomista sanastojen käsitteistä XML-rakenteita. Tässä suosituksessa käytetään seuraavia termejä niin kuin ne on määritelty IETF:n (Internet Engineering Task Force) toimesta (RFC 2119 [3]). PITÄÄ(MUST) EI SAA (MUST NOT) PAKOLLINEN (REQUIRED) PITÄISI (SHOULD) EI PITÄISI (SHOULD NOT) SAA (MAY) VAPAAEHTOINEN (OPTIONAL) Jos organisaatio haluaa, että sen XML-skeemat ovat tämän JHS-suosituksen mukaisia, niin suosituksessa esitetyt vaatimukset PITÄÄ täyttää. Järjestelmien yhteentoimivuus edellyttää, että pidemmällä aikavälillä useat organisaatiot laativat XML-skeemoja suosituksen vaatimusten mukaan. 2 Soveltamisala Suositus esittelee julkisen hallinnon yhteisten XML-skeemojen muodostamisen periaatteet ja sisältää alustavan useille julkishallinnon toimijoille yhteisen skeemaluettelon. Suosituksen kohderyhmiä ovat: julkishallinnon tietojärjestelmien kehittäjät järjestelmäkehityshankkeiden vetäjät ja asiantuntijat 3 Termit ja määritelmät XML W3C:n suositus rakenteisen tiedon esittämiseen sähköisessä muodossa. XML-skeema W3C:n suositus XML-dokumenttien rakenteen ja sisällön määrittelyyn. 4 Sanastotyön ja XML-skeemojen yhteys Sanastotyöllä tarkoitetaan niitä menetelmiä ja käytännön työtä, joilla kehitetään semanttista 2/23

3 yhteentoimivuutta edistäviä sanastoja. Sanastolla tarkoitetaan luetteloa jossain kielessä sallituista sanoista luokitteluineen, määritelmineen, kuvauksineen ja esimerkkeineen. Sanastoilla kuvataan käsitteiden merkityksiä siten, että eri tietojärjestelmät voivat ymmärtää käsittelemäänsä tietoa. Sanastot ovat lähtökohtaisesti teknologiariippumattomia. Sanastoista voidaan johtaa erilaisia teknisiä kuvaustapoja kuten XML-skeemat. XML-skeemojen tuottamisen PITÄISI alkaa sanaston käsitteiden määrittelemisestä tai jo määriteltyjen käsitteiden hyödyntämisestä. Sanastojen ja XML-skeemojen hallinnointi ja tekniset varastointiratkaisut PITÄISI kehittää siten, että ne tukevat sanaston käsitteistä lähtevää skeemojen tuottamista. Tässä suosituksessa ei ohjeisteta sanastojen määrittelyä. Sanastojen laatijoiden PITÄISI huomioida tämän suosituksen linjaukset siltä osin kuin ne koskevat XML-skeemojen johtamista sanaston käsitteistä. 5 XML-rakenteiden nimeäminen XML-rakenteiden nimeämisessä tukeudutaan soveltuvin osin kansainvälisiin standardeihin. Nimeämisohjeen lähtökohta on ISO standardi (Information technology Specification for standardization and registration of data elements and associated metadata Part 5: Naming and identification principles). Nimeäminen perustuu ISO :n sisältämään kolmitasoiseen nimeämismalliin. Standardin mukaisesti nimetyn tietoelementin yksilöivä nimi on kolmiosainen ja muodostuu Objektiluokasta, Ominaisuustermistä ja Ominaisuustermin tietotyyppiin viittaavasta Ilmentymästä. (Vastaavat englanninkieliset termit ovat Object class, Property term ja Representation term.) Objektiluokka yksilöi jonkin objektin tai toiminnan jossain asiayhteydessä. Luokka- tai oliomalleissa Objektiluokat kuvautuisivat nimensä mukaisesti luokiksi. Ominaisuustermi yksilöi objektin yhden ominaisuuden. Luokka- tai oliomalleissa Ominaisuustermit kuvautuisivat luokkien attribuuteiksi. Ilmentymä määrittelee ominaisuuden tietotyypin ilmentymistavan. Lisäksi jokaista osaa tarkentamaan SAA käyttää Määreitä (Qualifier). Alla on esitetty esimerkki nimen muodostumisesta. Nimen osien erottamiseen on käytetty pistettä.. Yllä esitetty muoto on käsitteestä käytettävä sanaston tekninen termi, joka kuvataan sanastossa. Kun sanaston teknisestä termistä muodostetaan XML-skeemassa käytettävä JHS-elementtinimi, siitä rajataan pois Objektiluokka, minkä jälkeen Ominaisuustermi ja Ilmentymä yhdistetään toisiinsa. Jos ominaisuustermin lopussa oleva sana on sama kuin Ilmentymä, voidaan päällekkäinen sana poistaa. Muodostettava nimi päättyy tällöin isolla kirjaimella alkavaan Ilmentymään. Yllä olevasta sanaston teknisestä termistä johdettu JHS-elementtinimi on siten: SukuNimi Määreen käyttöä selventää esimerkkikäsite Henkilön edellinen sukunimi. Käsitettä vastaava sanaston tekninen termi olisi: 3/23

4 Henkilo. Edellinen_ Sukunimi. Nimi Yllä olevassa teknisessä termissä Edellinen on Määre, joka tarkentaa Ominaisuustermiä Sukunimi. Määreen erotinmerkkinä käytetään alaviivaa _. Vastaava JHS-elementtinimi olisi tällöin: EdellinenSukuNimi Alla olevassa taulukossa on esimerkkejä, joissa on kuvattu käsite, sitä vastaava sanaston tekninen termi ja siitä johdettu JHS-elementtinimi. Käsitteen nimi ja tekninen termi voivat poiketa taivutusmuodoltaan. Esimerkiksi taulukon käsitteestä Kuolinpäivä muodostettu tekninen termi on Henkilo. Kuolema. Pvm. Käsite Sanaston tekninen termi JHS-elementtinimi Henkilötunnus Henkilo. Henkilotunnus. Tunnus HenkiloTunnus Etunimet Henkilo. Etunimet. Nimi EtunimetNimi Sukunimi Henkilo. Sukunimi. Nimi SukuNimi Turvakielto Henkilo. Turvakielto. Kytkin TurvakieltoKytkin Kuolinpäivä Henkilo. Kuolema. Pvm KuolemaPvm Kadun nimi Osoite. Katu. Nimi KatuNimi Postinumero Osoite. Postinumero. Koodi PostinumeroKoodi Sanaston teknisestä termistä rajatun Objektiluokan PITÄISI olla JHS-elementtien isäelementti XMLskeemaa vastaavassa XML-rakenteessa. Alla on esimerkki XML-rakenteista, joissa JHS-elementit on sisällytetty Objektiluokkia vastaaviin isäelementteihin. <Henkilo> <SukuNimi>Meikäläinen</SukuNimi> <EtunimetNimi>Matti Juhani</EtunimetNimi> <HenkiloTunnus> </HenkiloTunnus> <TurvakieltoKytkin>False</TurvakieltoKytkin>... <!- Muita Henkilo-elementin lapsielementtejä -->... </Henkilo> <Osoite> <KatuNimi>Kotikatu</KatuNimi> <PostinumeroKoodi>99999</PostinumeroKoodi>... <!- Muita Osoite-elementin lapsielementtejä -->... </Osoite> 4/23

5 5.1 Yleisiä nimeämissääntöjä Elementtien ja attribuuttien nimien PITÄISI olla ensisijaisesti suomenkielisiä. Tarvittaessa nimistä SAA tehdä englanninkieliset käännökset, joita voidaan käyttää englanninkielisissä skeemoissa. Samassa skeemassa EI PITÄISI käyttää sekä suomen- että englanninkielisiä nimiä. Nimien PITÄÄ olla kirjakielen muotoisia substantiiveja, verbejä ja adjektiiveja. Substantiivien PITÄÄ olla lähtökohtaisesti yksikkömuodossa, ellei käsite itsessään ole monikkomuotoinen. XML:ssä sekä isot että pienet kirjaimet ovat merkitseviä (case-sensitive). Tämä tarkoittaa, että esimerkiksi seuraavat nimet eivät ole samoja: KATUNIMI, katunimi, KatuNimi, katunimi Skandinaavisia merkkejä EI SAA käyttää XML-sanomien elementti-, attribuutti- ja tyyppinimissä. XMLsanomien sisällössä SAA käyttää skandinaavisia merkkejä. Elementtien, attribuuttien ja tyyppien nimissä EI SAA käyttää alaviivaa ( _ ), pistettä (. ), väliviivaa ( - ) eikä muita aakkosten ulkopuolisia merkkejä. Nimissä SAA käyttää numeroita ( 0-9 ). Kaikki elementtien, tyyppien ja attribuuttien nimet PITÄÄ kirjoittaa yhteen. 5.2 Elementtien nimeäminen Elementtinimien PITÄÄ noudattaa ns. Upper Camel Case -tyyliä. Nimen kaikkien sanojen alkukirjaimet kirjoitetaan isolla kirjaimella. Sanat kirjoitetaan yhteen. Esimerkiksi: HenkiloTunnus KatuNimi 5.3 Attribuuttien nimeäminen Attribuuttinimien PITÄÄ noudattaa ns. lower Camel Case -tyyliä. Muiden paitsi nimen ensimmäisen sanan alkukirjaimet kirjoitetaan isolla kirjaimella. Sanat kirjoitetaan yhteen. Esimerkiksi: kielikoodi 5.4 Tyyppien nimeäminen Käyttäjien määrittelemien johdettujen tietotyyppien PITÄÄ noudattaa ns. Upper Camel Case -tyyliä. Nimen kaikkien sanojen alkukirjaimet kirjoitetaan isolla kirjaimella. Sanat kirjoitetaan yhteen. Tyypin nimen loppuun PITÄÄ lisätä pääte Tyyppi. Esimerkiksi: HenkiloTunnusTyyppi Englanninkielisissä skeemoissa tyypin nimen loppuun PITÄÄ lisätä pääte Type. 5.5 Yleiset lyhenteet Lyhenteitä ovat yleisesti käytetyt tai tunnetut lyhennemerkinnät, joilla alkuperäistä sanaa lyhennetään merkittävästi. Lyhenne voi periaatteessa esiintyä missä kohdassa nimeä hyvänsä. Lyhenteet PITÄÄ kirjoittaa isoilla tai pienillä kirjaimilla niiden tyypillisen käyttötavan mukaan. Alla olevassa lyhenneluettelossa on esitetty yleisimpiä lyhenteitä kirjoitusasussaan. Luettelon lähteenä on käytetty Suomen kielitoimiston julkaisemaa lyhenneluetteloa ( 5/23

6 Tavoitetilassa XML-elementtinimet PITÄISI johtaa sanaston käsitteistä. Elementtien nimien PITÄISI olla pääsääntöisesti samoja kuin vastaavien käsitteiden nimet sanastossa. Jos sanastossa käytetään lyhennettä, PITÄÄ samaa lyhennettä käyttää myös XML-skeemassa. Seuraavia lyhenteitä PITÄÄ käyttää nimissä sellaisissa kohdissa, joissa kyseinen sana esiintyy. Lyhenne ALV ATK BKT CV db Dnro EU ICT ISBN ISSN JNro Km Kv Max Min Nro Oy Oyj Puh Pvm Srk Selite arvonlisävero automaattinen tietojenkäsittely bruttokansantuote lat. curriculum vitae, elämänvaiheet, elämäkerta; ansioluettelo desibeli(ä) diaarinumero Euroopan unioni engl. information and communication technology, informaatio- ja kommunikaatioteknologia engl. International Standard Book Number, kirjan kansainvälinen standardinumero engl. International Standard Serial Number, aikakausjulkaisun kansainvälinen standardinumero järjestysnumero kilometri(ä) kansainvälinen maksimi, korkeintaan, enintään minimi, vähintään numero osakeyhtiö julkinen osakeyhtiö puhelin päivämäärä seurakunta 6/23

7 Tmi URL Vrk toiminimi engl. uniform resource locator, Internetissä olevan tiedoston tai hakemiston sekä sen käyttöön tarvittavan yhteyskäytännön yksilöivä tunnus (esim. vuorokausi, vuorokautta Organisaatioiden nimilyhenteitä PITÄISI ylläpitää keskitetysti. Niitä ei ole kuvattu ylläolevassa taulukossa kaikkein yleisimpiä organisaatiolyhenteitä (esim. EU) lukuun ottamatta. Tässä suosituksessa ei linjata organisaatioiden nimilyhenteiden vastuutahoja. 5.6 Ilmentymät (Representation Terms) Ilmentymä (Representation Term) on elementin nimen loppuun liitettävä termi, joka kuvaa elementin sisällön tyypin. Ilmentymä PITÄÄ liittää sellaisen elementin nimen loppuun, joka voi sisältää dataa. Termi Termi englanniksi Käyttötarkoitus Aika Time Kellonaika, ajankohta (ISO 8601) Arvo Value Numeerinen 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. Numero Number Numero Prosentti Percent Prosenttilukuna esitettävä numeroarvo Pvm Date Päivä kalenterissa, ajankohta (ISO 8601) Hetki DateTime Päivä kalenterissa ja kellonaika, ajankohta (ISO 8601) 7/23

8 Suhde Rate Suhde numeerisena arvona 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 6 Skeemojen tekemisen perusohjeistus 6.1 Elementtejä vai attribuutteja XML-muotoisen tiedon ensisijaisena esitysrakenteena PITÄÄ käyttää elementtejä. Attribuuttien PITÄISI sisältää pääasiassa elementin sisällön arvoa kuvaavaa metatietoa. 6.2 Globaalit elementit Kaikki elementit PITÄÄ määritellä globaaleina. Tämä tarkoittaa, että elementit PITÄÄ määritellä skeeman ylimmällä tasolla xs:schema-elementin lapsielementteinä. Globaaliin elementtiin viitataan xs:elementmäärityksen ref-attribuutilla. Globaalit elementtimääritykset ovat uudelleenkäytettäviä. Muutokset elementin määritykseen heijastuvat kaikkiin elementtiin viittaaviin kohtiin. Lisäksi globaalit elementtimääritykset löytyvät paremmin skeemoista, koska niitä ei ole upotettu muiden määritysten sisään. Alla on esimerkki viittauksesta globaaliin elementtiin (EtunimetNimi) <xs:element name="etunimetnimi" type= xs:etunimetnimityyppi /> <xs:complextype name= Henkilo > <xs:sequence> <xs:element ref="etunimetnimi"/>... </xs:sequence> </xs:complextype> 6.3 Tyyppimäärittelyt Elementtien yksinkertaisissa tyyppimäärittelyissä (SimpleType) PITÄÄ pääsääntöisesti käyttää W3C:n XML Schema -suosituksen perustyyppejä. Määrittelyissä PITÄISI käyttää alla olevassa taulukossa lueteltuja perustyyppejä. Tyyppi Selite Esimerkki xs:string merkkijono Kotitaloustyö xs:integer kokonaisluku -123 xs:decimal desimaaliluku xs:time kellonaika 12:00:00 8/23

9 xs:date päivämäärä xs:datetime ajankohta T12:00:00 xs:boolean totuusarvo (true/false) true xs:base64binary binäärityyppi Ks. XML Schema -suositus sisältää lisäksi muita perustyyppejä, joita EI SAA käyttää kuin poikkeustapauksissa. Poikkeukseen on oltava painava syy. Jos perustyyppiin tehdään lisärajoitteita, se PITÄÄ nimetä omaksi tietotyypikseen (ks. 5.4 tyyppien nimeäminen). 6.4 Ilmentymien ja tietotyyppien vastaavuudet XML-skeemassa elementtien yksinkertaiset tietotyypit (simpletype) PITÄÄ esittää W3C:n XML Schema - suosituksen perustyyppeinä. Alla on kuvattu vastaavuudet ilmentymien ja perustyyppien välillä. Ilmentymä Aika Arvo Binaari Koodi Kuva Kytkin Lkm Mitta Maara Nimi Numero Prosentti Pvm Hetki Suhde Tietotyyppi xs:time xs:decimal xs:base64binary xs:string xs:base64binary xs:string, xs:boolean xs:decimal xs:decimal xs:decimal xs:string xs:decimal xs:decimal xs:date xs:datetime xs:decimal 9/23

10 Teksti Tunnus xs:string xs:string 6.5 Koodistot Koodistot ovat standardoituja, vakiintuneita tai virallistettuja koodiluetteloita. Koodistoa ylläpitää tavallisesti jokin nimetty taho. XML-skeemoissa koodistoja käytetään rajaamaan elementtien sallittuja arvoja. Esimerkkejä yleisistä koodistoista ovat: Postinumerot Maakoodit Kielikoodit Mikäli yleisiä importoitavia XML-skeemamuotoisia koodistoja käytetään, PITÄÄ niiden ylläpito vastuuttaa. 7 Nimiavaruuksien nimeäminen XML nimiavaruudet on määritelty W3C:n nimiavaruussuosituksessa (Namespaces in XML). Nimiavaruuksien avulla elementit ja attribuutit kiinnitetään yksiselitteisesti nimettyyn asiayhteyteen. Jos kahdella elementillä tai attribuutilla on sama nimi, ne voidaan erottaa toisistaan kiinnittämällä ne omiin nimiavaruuksiinsa. Nimiavaruus kuvataan URI-viittauksena. Jokaisessa skeemassa PITÄÄ nimetä kohdenimiavaruus (targetnamespace). XML Schema -määritykseen kuuluvat osat tarkennetaan nimiavaruudella Sen lyhyenä nimenä PITÄÄ käyttää lyhennettä xs. Nimiavaruuden nimen perusrakenne on seuraava: perusosa/<organisaatiokohtainen rakenne>/vuosi/kuukausi/päivä/ Julkishallinnon yhteisten XML-skeemojen perusnimiavaruus (perusosa) on: Kunkin organisaation PITÄÄ määritellä organisaatiokohtaisten XML-skeemojen nimiavaruuksien perusosa itse. Nimiavaruuden osan <organisaatiokohtainen rakenne> organisaatio SAA muodostaa itse, koska kohdealueet ja käyttökohteet riippuvat voimakkaasti toimialasta ja organisaatiosta. <organisaatiokohtainen rakenne> SAA sisältää useita hierarkkisia tasoja tilanteen mukaan. Julkishallinnon yhteisen skeemaluettelon organisaatiokohtainen osa on yhteiset. Nimiavaruuden nimen loppuun PITÄÄ merkitä skeeman julkaisemisen päivämäärä. Nimiavaruus ilmaisee päivämäärän avulla skeeman version (ks. luku 9 Skeemojen versiointi). Esimerkiksi julkaistun julkishallinnon yhteisen skeemaluettelon nimiavaruus on: 10/23

11 URL-osoitteen käyttö nimiavaruuden nimenä mahdollistaa nimiavaruuden käyttämisen fyysisessä skeemaviittauksessa. URL-osoitetta SAA käyttää suoraan fyysiseen osoittamiseen. Skeeman tallentaminen URL-osoitteeseen on kuitenkin VAPAAEHTOISTA. URL-linkin takaa PITÄISI löytyä vähintään skeemaa kuvaavaa dokumentaatiota. 8 Skeemojen modulaarisuus ja hierarkkisuus 8.1 Skeemojen modulaarisuuden perusmalli Skeemojen modulaarisuudella pyritään tehokkaaseen uudelleenkäyttöön. Kerran määriteltyjä skeemojen osia voidaan käyttää useissa ylemmän tason skeemoissa. Skeemojen modulaarisuuden perusmallin tavoitteita ovat: 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 elementti- ja tyyppimääritykset voidaan johtaa suoraan sanaston käsitteistä Joustava skeemojen muodostaminen edellyttää, että tiukkoja ja monimutkaisia rakenteita ei pyritä kiinnittämään omiksi aliskeemoikseen. Tyypillisesti esimerkiksi tiettyyn skeemaan kuuluvien elementtien järjestys ja pakollisuus vaihtelevat organisaatioittain. Tällaisten skeemamääritysten uudelleenkäyttö johtaa usein organisaatio- ja kohdealuekohtaisiin muutoksiin ja epäviralliseen versiointiin. Alla on esitetty kaaviokuvana esimerkki skeemojen modularisoinnista. Ylimmällä tasolla ovat Rajapintaskeemat. Rajapintaskeemoihin voidaan sisällyttää uudelleenkäytettäviä koosteskeemoja. Rajapintaskeemoihin ja koosteskeemoihin voidaan sisällyttää atomaarisia elementti- tai tyyppimäärityksiä sisältäviä skeemoja. Kuvassa on esitetty yksi atomaaristen elementti- ja tyyppimääritysten skeema (JHSYdin.xsd), joka sisältää koko julkishallinnolle yhteiset elementti- ja tyyppimäärittelyt. Pääsääntöisesti organisaatioiden PITÄÄ importoida nämä yhteiset atomaariset määrittelyt omiin skeemoihinsa. Kukin organisaatio SAA määritellä myös omia kohdealuekohtaisia elementti- ja tyyppimäärityksiään vastaaviksi atomaariskeemoiksi. Organisaatiokohtaiset atomaariskeemat voivat tarvittaessa periä (importoida) JHS-skeeman määrityksiä ja erikoistaa niitä organisaation tarpeita vastaaviksi. 11/23

12 8.2 Atomaaristen elementti- ja tyyppimääritysten JHS-skeema Atomaaristen elementti- ja tyyppimääritysten JHS-skeema sisältää julkishallinnon yhteiset skeemamääritykset. Atomaarinen elementtimääritys muodostuu yhdestä elementin määrittelystä, esimerkiksi: <xs:element name="henkilotunnus" type="jhs:henkilotunnustyyppi"/> Jokaista atomaarista elementtimääritystä vastaa skeemassa yksinkertainen tyyppimääritys (simpletype), esimerkiksi: <xs:simpletype name="henkilotunnustyyppi"> Skeemojen ja sanaston käsitteiden välinen yhteys muodostuu siten, että yhden sanaston käsitteen PITÄÄ vastata joko yhtä atomaarista elementtimäärittelyä tai sitä vastaavaa tyyppimäärittelyä. Näin pyritään varmistamaan yhteisten käsitteiden käyttö sekä yhtenäinen skeemanimeäminen kaikilla kohdealueilla. Sanasto SAA sisältää myös sellaisia käsitteitä, joilla ei ole vastinetta atomaarisena elementti- ja tyyppimäärittelynä. Jokaista atomaarista elementti- ja tyyppimäärittelyä PITÄISI vastata sanaston käsite. Pääsääntöisesti organisaation omissa skeemoissa PITÄISI viitata atomaariseen elementtimääritykseen. Atomaarisen määrittelyn muuttaminen organisaation tarpeita vastaavaksi on helpompaa viittaamalla vastaavaan tyyppimääritykseen. Tämän vuoksi organisaatio SAA omissa skeemoissaan viitata tyyppimääritykseen. Esimerkiksi sukunimen tyyppimääritys on atomaaristen määritysten JHS-skeemassa: <xs:simpletype name="sukunimityyppi"> Organisaatio voi viitata JHS-skeeman tyyppimääritykseen ja muuttaa sitä esimerkiksi rajoittamalla elementin pituutta: <xs:simpletype name="sukunimityyppi"> <xs:restriction base="jhs:sukunimityyppi"> <xs:maxlength value="50"/> </xs:restriction> Tällainen määritys SAA sisältyä organisaation omaan atomaaristen elementti- ja tyyppimäärittelyjen skeemaan. Jos uuden muodostetun tyypin nimi on sama kuin JHS-tyypin nimi, erotetaan muodostettu tyyppi alkuperäisestä JHS-tyypistä kiinnittämällä se organisaation itse määrittämään nimiavaruuteen. 8.3 Koosteskeemat Koosteskeema sisältää tietyn organisaation, kohdealueen, projektin tms. määrittelemän täsmällisen rakenteen jollekin elementtien joukolle. Koosteskeema PITÄISI koota atomaarisista elementtimäärityksistä tai viittaamalla niitä vastaaviin tyyppimäärityksiin. Koosteskeemassa voidaan määritellä elementtien järjestys ja pakollisuus. Joissakin tapauksissa voi olla tarkoituksenmukaista, että jokin organisaatio määrittelee esimerkiksi täsmällisen osoitteen rakenteen. Useat organisaation rajapintaskeemat voivat uudelleenkäyttää tällaista osoiteskeemaa. Organisaatio voi julkaista uudelleenkäytettävän koosteskeeman julkiseen skeemahakemistoon, josta muutkin organisaatiot voivat hyödyntää sitä. 12/23

13 8.4 Rajapintaskeemat Rajapintaskeema on jonkin organisaation palvelun tai järjestelmän edustalle kehitetyn rajapinnan tekninen sanomakuvaus. Rajapintaskeemojen joukko muodostuu tyypillisesti kysely-vastaus-pareista. Tietty skeema kuvaa palvelukyselyä vastaavan sanoman ja toinen skeema kyseistä kyselyä vastaavan vastaussanoman. Rajapintaskeemoista PITÄISI viitata pääsääntöisesti atomaarisiin elementtimäärityksiin tai niitä vastaaviin tyyppimäärityksiin. Rajapintaskeemoista SAA myös viitata uudelleenkäytettäviin koosteskeemoihin. Jos rajapintaskeemasta viitataan koosteskeemaan, viittaukset atomaarisiin elementtimäärityksiin PITÄÄ tehdä näistä koosteskeemoista. Rajapintaskeemoissa kiinnitetään muun muassa elementtien järjestys ja pakollisuus. Rajapintaskeemassa PITÄÄ atomaariset elementtimääritykset sisällyttää xs:import-määrityksin osaksi skeemaa. 8.5 Skeemojen xs:import-määritykset Alemman tason skeemat PITÄÄ sisällyttää osaksi ylemmän tason skeemaa xs:import-määrityksillä. Esimerkiksi: <xs:import namespace= " 2009/03/04" schemalocation="jhsydin xsd"/> 8.6 Hierarkkiset XML-puurakenteet Sanomaskeemojen XML-rakenteissa PITÄISI pyrkiä mahdollisimman mataliin hierarkioihin. Turhia välitasoja PITÄÄ välttää. Sallittujen hierarkiatasojen lukumäärää ei kuitenkaan täsmällisesti rajoiteta. Tasojen määrä riippuu vaatimuksista ja tietomallin monimutkaisuudesta. Loogiset kokonaisuudet PITÄISI sisällyttää isä-elementin sisään. Alla olevassa esimerkissä hierarkiaa havainnollistetaan XML-instanssin avulla. <Henkilo> <EtunimetNimi>Matti Juhani</EtunimetNimi> <SukuNimi>Meikäläinen</SukuNimi> <HenkiloTunnus> </HenkiloTunnus> </Henkilo> 9 Skeemojen versiointi Skeemojen eri tasojen versiointi asettaa haasteita XML-rajapintaratkaisuille. Rajapintojen PITÄÄ toimia myös skeemamuutosten jälkeen. 9.1 Julkishallinnon yhteisten skeemojen versiointi Julkishallinnon yhteisten skeemojen versiointiin PITÄÄ käyttää nimiavaruudessa ilmaistua versiota. Nimiavaruuksien nimeäminen on esitetty luvussa 7. Jokaisen skeemaan kohdistuvan muutoksen yhteydessä versiota PITÄÄ päivittää vastaamaan muutoksen julkaisupäivää. 9.2 Organisaatiokohtaisten skeemojen versiointi Organisaatiokohtaisten skeemojen versiointia edellyttävät muutokset voidaan jakaa kahteen luokkaan: 1. Muutos vaikuttaa skeeman aikaisemman version mukaisten XML-instanssien validointiin Jos muutos vaikuttaa skeeman aikaisemman version mukaisten XML-instanssien validointiin, uusi versio PITÄÄ ilmaista nimiavaruuden nimessä. Nimiavaruuksien nimeäminen on esitetty luvussa 7. 13/23

14 Tyypillinen esimerkki luokkaan 1 kuuluvasta muutoksesta on, että skeemaan lisätään yksi tai useampi elementtimääritys, jossa elementti määritellään pakolliseksi. Muutos vaikuttaa skeeman aikaisemman version mukaisten XML-instanssien validointiin, koska sellaiset XML-instanssit, joista kyseinen elementti puuttuu, ovat uuden skeeman mukaan virheellisiä. Tällöin skeeman pääversiota (nimiavaruuden nimi) pitää muuttaa. 2. Muutos ei vaikuta skeeman aikaisemman version mukaisten XML-instanssien validointiin Jos muutos ei vaikuta skeeman aikaisemman version mukaisten XML-instanssien validointiin, muutos PITÄÄ ilmaista xs:schema-elementin :version-attribuutissa. Numerointi aloitetaan aliversiosta 1.0. Tyypillinen esimerkki luokkaan 2 kuuluvasta muutoksesta on, että skeemaan lisätään yksi tai useampi elementtimääritys, jossa elementti määritellään vapaaehtoiseksi. Tämä muutos ei vaikuta skeeman aikaisemman version mukaisten XML-instanssien validointiin, sillä kaikki XML-istanssit ovat myös uuden skeeman mukaan valideja. Tällöin skeeman pääversiota ei tarvitse vaihtaa, vaan riittää että ilmaistaan sen aliversio numerolla. Kun skeema luodaan ensimmäisen kerran, se saa sekä pääversion nimiavaruuden nimessä että aliversion xs:schema-elementin version-attribuutissa. Skeeman ensimmäiseksi aliversioksi PITÄÄ asettaa Merkistö XML-skeemoissa ja -sanomissa PITÄÄ käyttää UTF-8 koodausta ja encoding-attribuuttia, joka selkeästi ilmaisee käytetyn koodauksen. 11 Opastavat tiedot Tätä suositusta ylläpitää Julkisen hallinnon tietohallinnon neuvottelukunta JUHTA, puh (09) 16001, sähköposti: jhs-sihteeri@jhs-suositukset.fi JHS-järjestelmän verkkosivut: Liitteet Liite 1: Julkishallinnon yhteinen XML-ydinskeema 14/23

15 Liite 1 <?xml version="1.0" encoding="utf-8"?> <!--*************************************************************** JHS / Ydintyypit ja ydinelementit Versio: Viimeksi päivitetty: Tieto Oy / Lasse Akselin Muutoshistoria: : ensimmäinen versio : päivitetyn sanastotaulukon mukaiset muutokset : suositusluonnoksen kommentoinnin jälkeen tehdyt lisäykset : JHS-jaoston käsittelyyn lähetetty versio ******************************************************************** --> <xs:schema xmlns:xs=" xmlns:jhs=" targetnamespace=" elementformdefault="qualified"> <xs:element name="alayksikkonimi" type="jhs:alayksikkonimityyppi"/> <xs:simpletype name="alayksikkonimityyppi"> <xs:element name="alkuhetki" type="jhs:alkuhetkityyppi"/> <xs:simpletype name="alkuhetkityyppi"> <xs:restriction base="xs:datetime"/> <xs:element name="alkupvm" type="jhs:alkupvmtyyppi"/> <xs:simpletype name="alkupvmtyyppi"> <xs:restriction base="xs:date"/> <xs:element name="ammattikoodi" type="jhs:ammattikoodityyppi"/> <xs:simpletype name="ammattikoodityyppi"> 15/23

16 <xs:element name="bickoodi" type="jhs:bickoodityyppi"/> <xs:simpletype name="bickoodityyppi"> <xs:element name="careofteksti" type="jhs:careoftekstityyppi"/> <xs:simpletype name="careoftekstityyppi"> <xs:element name="edellinensukunimi" type="jhs:edellinensukunimityyppi"/> <xs:simpletype name="edellinensukunimityyppi"> <xs:element name="ensimmainenriviteksti" type="jhs:ensimmainenrivitekstityyppi"/> <xs:simpletype name="ensimmainenrivitekstityyppi"> <xs:element name="etunimetnimi" type="jhs:etunimetnimityyppi"/> <xs:simpletype name="etunimetnimityyppi"> <xs:element name="etunimi" type="jhs:etunimityyppi"/> <xs:simpletype name="etunimityyppi"> <xs:element name="faksinumeroteksti" type="jhs:faksinumerotekstityyppi"/> <xs:simpletype name="faksinumerotekstityyppi"> <xs:element name="henkilotunnus" type="jhs:henkilotunnustyyppi"/> <xs:simpletype name="henkilotunnustyyppi"> 16/23

17 <xs:element name="huoltosuhdeteksti" type="jhs:huoltosuhdetekstityyppi"/> <xs:simpletype name="huoltosuhdetekstityyppi"> <xs:element name="huoneistotunnistenumero" type="jhs:huoneistotunnistenumerotyyppi"/> <xs:simpletype name="huoneistotunnistenumerotyyppi"> <xs:restriction base="xs:decimal"/> <xs:element name="huoneistotunnistejakokirjainteksti" type="jhs:huoneistotunnistejakokirjaintekstityyppi"/> <xs:simpletype name="huoneistotunnistejakokirjaintekstityyppi"> <xs:element name="huoneistotunnistekirjainteksti" type="jhs:huoneistotunnistekirjaintekstityyppi"/> <xs:simpletype name="huoneistotunnistekirjaintekstityyppi"> <xs:element name="ibantunnus" type="jhs:ibantunnustyyppi"/> <xs:simpletype name="ibantunnustyyppi"> <xs:element name="ikaluokkateksti" type="jhs:ikaluokkatekstityyppi"/> <xs:simpletype name="ikaluokkatekstityyppi"> <xs:element name="kansalaisuuskoodi" type="jhs:kansalaisuuskoodityyppi"/> <xs:simpletype name="kansalaisuuskoodityyppi"> 17/23

18 <xs:element name="katunimi" type="jhs:katunimityyppi"/> <xs:simpletype name="katunimityyppi"> <xs:element name="kielikoodi" type="jhs:kielikoodityyppi"/> <xs:simpletype name="kielikoodityyppi"> <xs:element name="kolmasriviteksti" type="jhs:kolmasrivitekstityyppi"/> <xs:simpletype name="kolmasrivitekstityyppi"> <xs:element name="kuntakoodi" type="jhs:kuntakoodityyppi"/> <xs:simpletype name="kuntakoodityyppi"> <xs:element name="kuntanumero" type="jhs:kuntanumerotyyppi"/> <xs:simpletype name="kuntanumerotyyppi"> <xs:restriction base="xs:decimal"/> <xs:element name="kuolemapvm" type="jhs:kuolemapvmtyyppi"/> <xs:simpletype name="kuolemapvmtyyppi"> <xs:restriction base="xs:date"/> <xs:element name="kutsumanimi" type="jhs:kutsumanimityyppi"/> <xs:simpletype name="kutsumanimityyppi"> 18/23

19 <xs:element name="kuudesriviteksti" type="jhs:kuudesrivitekstityyppi"/> <xs:simpletype name="kuudesrivitekstityyppi"> <xs:element name="kuvausteksti" type="jhs:kuvaustekstityyppi"/> <xs:simpletype name="kuvaustekstityyppi"> <xs:element name="lajikoodi" type="jhs:lajikoodityyppi"/> <xs:simpletype name="lajikoodityyppi"> <xs:element name="lajiteksti" type="jhs:lajitekstityyppi"/> <xs:simpletype name="lajitekstityyppi"> <xs:element name="loppuhetki" type="jhs:loppuhetkityyppi"/> <xs:simpletype name="loppuhetkityyppi"> <xs:restriction base="xs:datetime"/> <xs:element name="loppupvm" type="jhs:loppupvmtyyppi"/> <xs:simpletype name="loppupvmtyyppi"> <xs:restriction base="xs:date"/> <xs:element name="maatunnuskoodi" type="jhs:maatunnuskoodityyppi"/> <xs:simpletype name="maatunnuskoodityyppi"> <xs:element name="neljasriviteksti" type="jhs:neljasrivitekstityyppi"/> <xs:simpletype name="neljasrivitekstityyppi"> 19/23

20 <xs:element name="nimilajikoodi" type="jhs:nimilajikoodityyppi"/> <xs:simpletype name="nimilajikoodityyppi"> <xs:element name="nimiteksti" type="jhs:nimitekstityyppi"/> <xs:simpletype name="nimitekstityyppi"> <xs:element name="osoitenumero" type="jhs:osoitenumerotyyppi"/> <xs:simpletype name="osoitenumerotyyppi"> <xs:restriction base="xs:decimal"/> <xs:element name="paayksikkonimi" type="jhs:paayksikkonimityyppi"/> <xs:simpletype name="paayksikkonimityyppi"> <xs:element name="pankkitilitunnus" type="jhs:pankkitilitunnustyyppi"/> <xs:simpletype name="pankkitilitunnustyyppi"> <xs:element name="postilokerolyhenneteksti" type="jhs:postilokerolyhennetekstityyppi"/> <xs:simpletype name="postilokerolyhennetekstityyppi"> <xs:element name="postilokeroteksti" type="jhs:postilokerotekstityyppi"/> <xs:simpletype name="postilokerotekstityyppi"> 20/23

21 <xs:element name="postinumerokoodi" type="jhs:postinumerokoodityyppi"/> <xs:simpletype name="postinumerokoodityyppi"> <xs:element name="postitoimipaikkanimi" type="jhs:postitoimipaikkanimityyppi"/> <xs:simpletype name="postitoimipaikkanimityyppi"> <xs:element name="puhelinnumeroteksti" type="jhs:puhelinnumerotekstityyppi"/> <xs:simpletype name="puhelinnumerotekstityyppi"> <xs:element name="sahkoinenasiointitunnus" type="jhs:sahkoinenasiointitunnustyyppi"/> <xs:simpletype name="sahkoinenasiointitunnustyyppi"> <xs:element name="sahkopostiosoiteteksti" type="jhs:sahkopostiosoitetekstityyppi"/> <xs:simpletype name="sahkopostiosoitetekstityyppi"> <xs:element name="siviilisaatyteksti" type="jhs:siviilisaatytekstityyppi"/> <xs:simpletype name="siviilisaatytekstityyppi"> <xs:element name="statusryhmateksti" type="jhs:statusryhmatekstityyppi"/> <xs:simpletype name="statusryhmatekstityyppi"> <xs:element name="sukunimi" type="jhs:sukunimityyppi"/> 21/23

22 <xs:simpletype name="sukunimityyppi"> <xs:element name="sukupuolikoodi" type="jhs:sukupuolikoodityyppi"/> <xs:simpletype name="sukupuolikoodityyppi"> <xs:element name="syntymapvm" type="jhs:syntymapvmtyyppi"/> <xs:simpletype name="syntymapvmtyyppi"> <xs:restriction base="xs:date"/> <xs:element name="toinenriviteksti" type="jhs:toinenrivitekstityyppi"/> <xs:simpletype name="toinenrivitekstityyppi"> <xs:element name="turvakieltokytkin" type="jhs:turvakieltokytkintyyppi"/> <xs:simpletype name="turvakieltokytkintyyppi"> <xs:restriction base="xs:boolean"/> <xs:element name="ulkomaahenkilotunnus" type="jhs:ulkomaahenkilotunnustyyppi"/> <xs:simpletype name="ulkomaahenkilotunnustyyppi"> <xs:element name="ulkomaapostitoimipaikkanimi" type="jhs:ulkomaapostitoimipaikkanimityyppi"/> <xs:simpletype name="ulkomaapostitoimipaikkanimityyppi"> <xs:element name="vakinainenkytkin" type="jhs:vakinainenkytkintyyppi"/> <xs:simpletype name="vakinainenkytkintyyppi"> 22/23

23 <xs:restriction base="xs:boolean"/> <xs:element name="valiaikainenhenkilotunnus" type="jhs:valiaikainenhenkilotunnustyyppi"/> </xs:schema> <xs:simpletype name="valiaikainenhenkilotunnustyyppi"> <xs:element name="valtiotunnuskoodi" type="jhs:valtiotunnuskoodityyppi"/> <xs:simpletype name="valtiotunnuskoodityyppi"> <xs:element name="viidesriviteksti" type="jhs:viidesrivitekstityyppi"/> <xs:simpletype name="viidesrivitekstityyppi"> <xs:element name="voimassaolokytkin" type="jhs:voimassaolokytkintyyppi"/> <xs:simpletype name="voimassaolokytkintyyppi"> <xs:restriction base="xs:boolean"/> <xs:element name="yritystunnus" type="jhs:yritystunnustyyppi"/> <xs:simpletype name="yritystunnustyyppi"> 23/23