JHS XXX Julkishallinnon XML-skeemat Versio: 0.6 Julkaistu: Voimassaoloaika: Sisällys 1 Johdanto... 2 2 Soveltamisala... 2 3 Termit ja määritelmät... 2 4 Sanastotyön ja XML-skeemojen yhteys... 2 5 XML-rakenteiden nimeäminen... 3 5.1 Yleisiä nimeämissääntöjä... 3 5.2 Elementtien nimeäminen... 4 5.3 Attribuuttien nimeäminen... 4 5.4 Tyyppien nimeäminen... 4 5.5 Yleiset lyhenteet... 4 5.6 Ilmentymät (Representation Terms)... 6 6 Skeemojen tekemisen perusohjeistus... 7 6.1 Elementtejä vai attribuutteja... 7 6.2 Globaalit elementit... 7 6.3 Tyyppimäärittelyt... 7 6.4 Ilmentymien ja tietotyyppien vastaavuudet... 8 6.5 Koodistot... 8 7 Nimiavaruuksien nimeäminen... 9 8 Skeemojen modulaarisuus ja hierarkkisuus... 9 8.1 Skeemojen modulaarisuuden perusmalli... 9 8.2 Atomaaristen elementtien skeemat...10 8.3 Koosteskeemat...11 8.4 Rajapintaskeemat...11 8.5 Skeemojen xs:import-määritykset...11 8.6 Hierarkkiset XML-puurakenteet...11 9 Skeemojen versiointi...11 9.1 Julkishallinnon yhteisten skeemojen versiointi...12 9.2 Organisaatiokohtaisten skeemojen versiointi...12 10 Merkistö...12 11 Opastavat tiedot...12 11.1 Liitteet...12 1/12
1 Johdanto Tämä JHS-suositus ohjeistaa XML-skeemojen tuottamista ja hallintaa julkishallinnossa. Suosituksessa kuvataan julkisen hallinnon XML-skeemojen muodostamisen yhteisiä periaatteita. Lisäksi laaditaan 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 tulee noudattaa johdettaessa teknikkaan 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]). http://www.ietf.org/rfc/rfc2119.txt. PITÄÄ(MUST) EI SAA (MUST NOT) PAKOLLINEN (REQUIRED) PITÄISI (SHOULD) EI PITÄISI (SHOULD NOT) SAA (MAY) SALLITTU (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/12
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 11179-5 standardi (Information technology Specification for standardization and registration of data elements and associated metadata Part 5: Naming and identification principles). Nimeäminen perustuu ISO 11179-5: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, Representation term.). Lisäksi jokaista osaa tarkentamaan SAA käyttää Määreitä (Qualifier). Esimerkkejä mallin mukaisesta nimeämisestä ovat: KatuNimi SukuNimi HenkiloTunnus TuloVerotettavaMaara Mallin mukainen nimeäminen PITÄISI tehdä jo sanastossa, josta XML-elementtien ja muiden rakenteiden nimet voitaisiin johtaa. 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ä. Kaikki elementtien, tyyppien ja attribuuttien nimet PITÄÄ kirjoittaa yhteen. Alla on esimerkkejä nimien muodostamisesta: 3/12
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 5.2 Elementtien nimeäminen Elementtinimien PITÄÄ noudattaa ns. Upper Camel Case -tyyliä. Nimen kaikkien sanojen alkukirjaimet kirjoitetaan isolla kirjaimella. Sanat kirjoitetaan yhteen. Esimerkiksi: KatuNimi Elementtien nimissä EI SAA käyttää alaviivaa ( _ ), pistettä (. ), väliviivaa ( - ) eikä muita aakkosten ulkopuolisia merkkejä. Nimissä SAA käyttää numeroita ( 0-9 ). 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 Attribuuttien nimissä EI SAA käyttää alaviivaa ( _ ), pistettä (. ), väliviivaa ( - ) eikä muita aakkosten ulkopuolisia merkkejä. Nimissä SAA käyttää numeroita ( 0-9 ). 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 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 (http://www.kotus.fi/index.phtml?s=2149). 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. 4/12
Lyhenne ALV ATK BKT CV db Dnro EU ICT ISBN ISSN JNro Km Kv Max Min Nro Oy Oyj Puh Pvm Srk Tmi URL Vrk 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 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 toiminimi engl. uniform resource locator, Internetissä olevan tiedoston tai hakemiston sekä sen käyttöön tarvittavan yhteyskäytännön yksilöivä tunnus (esim. http://www.jhs-suositukset.fi) vuorokausi, vuorokautta Organisaatioiden nimilyhenteitä PITÄÄ ylläpitää keskitetysti. Niitä ei ole kuvattu ylläolevassa taulukossa kaikkein yleisimpiä organisaatiolyhenteitä (esim. EU) lukuunottamatta. 5/12
5.6 Ilmentymät (Representation Terms) Ilmentymä (Representation Term) on elementin nimen loppuun liitettävä termi, joka kuvaa elementin sisällön tyypin. Alla olevassa luettelossa olevia termejä PITÄÄ käyttää XML-nimissä. 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. 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) Suhde Rate Aste numeerisena arvo 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/12
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 (EtuNimi) <xs:element name="etunimi" type xs:string/> <xs:complextype name= HenkiloTiedotTyyppi > <xs:sequence> <xs:element ref="etunimi"/>... </xs:sequence> </xs:complextype> 6.3 Tyyppimäärittelyt Elementtien tyyppimäärittelyissä (SimpleType) PITÄÄ pääsääntöisesti käyttää W3C:n XML Schema - suosituksen perustyyppejä. Määrittelyissa PITÄISI käyttää alla olevassa taulukossa lueteltuja perustyyppejä. Tyyppi Selite Esimerkki xs:string merkkijono Kotitaloustyö xs:integer kokonaisluku -123 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 XML Schema -suositus sisältää lisäksi muita perustyyppejä, joita EI SAA käyttää kuin poikkeustapauksissa. Poikkeukseen on oltava painava syy. 7/12
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 tietotyypit 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 Nro Prosentti Pvm PvmAika Suhde Teksti Tunnus Tietotyyppi xs:time xs:binary xs:string xs:binary xs:string, xs:boolean xs:string xs:date xs:datetime 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 8/12
Mikäli XML-skeemamuotoisia koodistoja käytettää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 http://www.w3.org/2001/xmlschema. Sen lyhyenä nimenä PITÄÄ käyttää lyhennettäxs. Nimiavaruuden nimen perusrakenne on seuraava: perusosa/kohdealue/tarkenne/vuosi/kuukausi/päivä/ Julkishallinnon yhteisten XML-skeemojen perusnimiavaruus (perusosa) on: http://skeemat.jhs-suositukset.fi/ [Huom! Nimiavaruudesta ei ole vielä tehty päätöstä.] Kunkin organisaation PITÄÄ määritellä organisaatiokohtaisten XML-skeemojen nimiavaruuksien perusosa itse. Kohdealue voi olla esim.yhteiset. Kohdealue Yhteiset kattaa yhteiset uudelleenkäytettävät elementtimääritykset. Tarkenne ilmaisee skeeman tarkan käyttökohteen, esim. Osoite. 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). Esimerkki nimiavaruudesta on: http://skeemat.jhs-suositukset.fi/yhteiset/osoite/2008/08/21 URL-osoitteen käyttö nimiavaruuden nimenä mahdollistaa nimiavaruuden käyttämisen fyysisessä skeemaviittauksessa. URL-osoitetta SAA käyttää suoraan fyysiseen osoittamiseen. On kuitenkin SALLITTUA, että URL-osoitteeseen ei ole tallennettu skeemaa. 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 elementtimääritykset voidaan johtaa suoraan sanaston käsitteistä 9/12
Joustava skeemojen muodostaminen edellyttää, että tiukkoja ja monimutkaisia rakenteita ei pyritä kiinnittämään omiksi aliskeemoikseen. Tyypillisesti esimerkiksi elementtien järjestys ja pakollisuus tietyn skeeman sisällä 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 elementtimäärityksiä sisältäviä skeemoja. 8.2 Atomaaristen elementtien skeemat Atomaarinen elementtimääritys muodostuu yhdestä elementin määrittelystä, esimerkiksi: <xs:element name="henkilotunnus" type="xs:string"/> Yksi fyysinen skeematiedosto SAA sisältää yhden tai useamman atomaarisen elementtimäärityksen. Samaan skeematiedostoon koottujen atomaaristen elementtimääritysten PITÄÄ jakaa yhteinen versiohistoria. Jos yhden tiedostoon kuuluvan elementin määritys muuttuu, PITÄÄ kaikkien tiedostossa olevien elementtimääritysten version vaihtua. Ainoastaan yhden elementtimäärityksen sisältävät aliskeemat tarjoavat joustavan mahdollisuuden versioida skeemoja yksittäisten elementtimääritysten tasolla. Skeemojen ja sanaston käsitteiden välinen yhteys muodostuu siten, että yhtä atomaarista elementtimäärittelyä PITÄÄ vastata yksi sanaston käsite. 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 elementtimäärittelynä. 10/12
8.3 Koosteskeemat JUHTA - Julkisen hallinnon tietohallinnon neuvottelukunta 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ä. Koosteskeemassa voidaan määritellä elementtien järjestys ja pakollisuus. Voi olla tarkoituksenmukaista, että esimerkiksi jokin organisaatio määrittelee 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ä. 8.4 Rajapintaskeemat Rajapintaskeema on jonkin organisaation palvelun tai järjestelmän edustalle kehitetyn rajapinnan tekninen sanomakuvaus. Rajapintaskeemat muodostavat tyypillisesti kysely-vastaus-pareja. Rajapintaskeemoista PITÄISI viitata pääsääntöisesti atomaarisiin elementtimää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. Isoissa rajapintaskeemoissa tämä voi tarkoittaa jopa kymmenien xs:import-määritysten tekemistä. Kehittäjien työtä tukemaan PITÄISI rakentaa joko valmiita skeemapohjia tai automatiikkaa, jolla xs:importmäärityksiä voidaan generoida tarpeen mukaan. 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= "http://skeemat.jhs-suositukset.fi/yhteiset/ Osoite/2008/08/21" schemalocation="jhs_osoite_20080821.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> <EtuNimi>Matti</EtuNimi> <SukuNimi>Meikäläinen</SukuNimi> <HenkiloTunnus>111111-1111</HenkiloTunnus> </Henkilo> 9 Skeemojen versiointi Skeemojen eri tasojen versiointi asettaa haasteita XML-rajapintaratkaisuille. Rajapintojen PITÄÄ toimia myös skeemamuutosten jälkeen. 11/12
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. 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 xs: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 xs:version-attribuutissa. Skeeman ensimmäiseksi aliversioksi PITÄÄ asettaa 1.0. 10 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: http://www.jhs-suositukset.fi/ 11.1 Liitteet Liite 1: Julkishallinnon yhteisiä XML-skeemoja (kesken) Liite 2: Esimerkki XML-skeemojen muodostamisesta (kesken) 12/12