Työeläkejärjestelmän XML-ohjeisto

Versio 2009-05-28

Viimeisin versio löytyy osoitteesta http://ws.tyoelake.fi/ohjeisto/.

Sisällys

• Johdanto
• Standardit
• WSDL-kuvausten ja SOAP-sanomien rakenne
  • WSDL-kuvausten rakenne
  • SOAP-sanomien rakenne
• Elementtien ja attribuuttien nimeäminen
• Yleiset tyypit
  • Perustyypit
  • Vakio-osa
  • Hälytysten yleistietoryhmä
  • Poikkeustiedot
• Omien tyyppien käyttö
  • Rahamäärät
  • Päivämäärät ja kellonajat
• Versiointi
• Tietoturva
  • SOAP-autentikointi
  • Eräajojen autentikointi
• SOAP-sanomien välitys
  • Merkistö ja pakkaus
  • Aikavyöhyketieto
  • Tyhjän tiedon välittäminen
  • Validointi
  • Esimerkki
• Erätiedostojen välitys
  • Esimerkki
• Tämän ohjeiston muutokset

Johdanto

Tämä ohjeisto määrittelee, miten XML-teknologioita hyödynnetään eläkevakuuttajien, Arekin ja Eläketurvakeskuksen järjestelmien välisissä yhteyksissä. Ohjeiston ensisijaisena tavoitteena on paras mahdollinen yhteensopivuus eri tietojärjestelmien välillä. Muita tavoitteita ovat tietojen vaihdon hyvä suorituskyky ja implementoinnin helppous.

Työeläkejärjestelmässä ei olla kuvattu kattavaa joukkoa yhteisiä ydintyyppejä, joissa määriteltäisiin esimerkiksi henkilön tai vakuutuksen kaikki ominaisuudet ja tietojen rakenne XML-sanomilla. Lähtökohtana on ollut, että kukin palvelu määrittelee omille kutsu- ja vastaussanomilleen tarvitsemansa tiedot.

XML-rajapintojen ei ole tarkoitus kuvata esim. sanomilla sallittuja arvoja tai niiden muotoja mahdollisimman tarkasti. XML-sanomilla pyritään käyttämään yksinkertaisia perustyyppejä ja tietojen oikeellisuustarkistukset tehdään sovelluslogiikassa.

Tässä ohjeistossa esitetään XML:n käyttöön liittyviä vaatimuksia, suosituksia ja vinkkejä.

Esimerkki vaatimuksesta:

Palveluille ja niihin liittyville skeemoille tulee määritellä nimiavaruudet.

Esimerkki suosituksesta:

Elementtien nimien tulisi olla korkeintaan 32 merkin pituisia.

Esimerkki vinkistä:

Yhteensopivuuden varmistamiseksi ja virheiden ehkäisemiseksi XML-sanoman muodostava osapuoli voi validoida muodostamansa sanoman.

Standardit

Työeläkejärjestelmän XML-ohjeisto pohjautuu pääosin W3C:n suosituksiin. XML-toteutusten on oltava yhteensopivia alla mainittujen suositusten kanssa.

• XML: Extensible Markup Language (XML) 1.0 (Third Edition)
• Schema 0: XML Schema Part 0: Primer Second Edition
• Schema 1: XML Schema Part 1: Structures Second Edition
• Schema 2: XML Schema Part 2: Datatypes Second Edition
• SOAP: Simple Object Access Protocol (SOAP) 1.1
• WS-I: Web Services Interoperability Basic Profile Version 1.0

Seuraavista Oasiksen ja WS-I:n standardeista hyödynnetään osia, jotka määritellään tässä dokumentissa.

• WS-S: Web Services Security v1.0 (WS-Security 2004)
  • Web Services Security UsernameToken Profile 1.0
  • Web Service Security X.509 Certificate Token Profile
• WS-IS: WS-I Basic Security Profile Version 1.0

Lisäksi on hyvä tuntea seuraavat standardit:

• WS-gloss: Web Services Glossary
• WS-i18n: Web Services Internationalization (WS-I18N)

WSDL-kuvausten ja SOAP-sanomien rakenne

WSDL-kuvausten rakenne

Yhdessä WSDL-kuvauksessa tulisi kuvata yksi palvelu. Palvelu koostuu tyypillisesti yhden kutsu- ja yhden vastaussanoman muodostamasta operaatiosta, mutta operaatioita voi myös olla useita. Jokaisen sanoman rakenne kannattaa kuvata omassa skeemassaan. Nämä erilliset skeemat liitetään WSDL-kuvaukseen XML Schema -suosituksen import-elementin avulla.

WSDL-kuvauksia ei ainakaan toistaiseksi julkaista UDDI-palvelussa vaan jokainen organisaatio julkaisee rajapintakuvaukset valitsemallaan tavalla. Kaikille palveluille yhteiset skeemat julkaistaan sivustolla ws.tyoelake.fi.

Esimerkki WSDL-palvelukuvauksesta

SOAP-sanomien rakenne

SOAP-sanomat muodostuvat SOAP-standardin mukaisesta Header- ja Body-osasta. Työeläkejärjestelmän XML-sanomilla Body-osaan sijoitetaan kaikille yhteinen vakio-osa, vastaussanomille mahdollisia poikkeustietoja sekä sanomakohtainen liiketoimintaosa. Vakio-osan ja poikkeustietojen rakenne on määritelty yleisissä skeemoissa ja ne on esitelty tämän ohjeiston kappaleessa Yleiset tyypit. Tässä suosituksessa on erillinen kappale SOAP-sanomien välittämisestä.

Erätiedostojen rakenne

Palveluntarjoaja voi tarjota palvelulleen myös eräkäsittelyrajapintaa. Eräkäsittelyssä koko erälle muodostetaan juurielementti, jonka sisään tulevat yleiset erän tiedot sekä yksittäiset sanomat peräkkäin. Jokaisella kutsusanomalla on oma vakio-osansa. Eräajorajapinnoille ei ole pakko määrittää vastaussanomia, mutta jos vastauserän rakenne määritetään, jokaisen vastaussanoman tulee sisältää vakio-osa ja mahdolliset poikkeustiedot. Koko erää koskevia poikkeustietoja ei ole määritetty. Eräajorajapintojen tulee pystyä muodostamaan vastauserä, jolla on yleiset erän tiedot ja yhtä monta vastaussanomaa kuin pyyntöerällä oli pyyntösanomia.

Eräajojen vastaustiedostoon voidaan määrittää yleisten erän tietojen lisäksi kokooma, jossa kerrotaan esimerkiksi onnistuneiden sanomien lukumäärä.

Esimerkki pyyntöerätiedoston rakenteen kuvaavasta skeemasta - sisältää myös autentikointitiedot. Katso myös Erätiedostojen välitys.

Elementtien ja attribuuttien nimeäminen

Elementtien ja attribuuttien nimien tulee perustusa suomen kieleen. Ä- ja ö-kirjaimista jätetään pisteet pois. Välilyönnit ja yhdysviivat jätetään nimistä pois, nimissä ei käytetä alaviivoja. Elementtien nimissä käytetään ns. UpperCamelCase-kirjoitustapaa (kaikki sanat alkavat isolla alkukirjaimella) ja attribuuttien nimissä lowerCamelCase-tapaa (ensimmäinen sana alkaa pienellä kirjaimella, muut sanat isoilla).

Palveluun kuuluvan operaation kutsu- ja vastaussanomien SOAP Body -osaan sijoitettavien juurielementtien tulisi kuvata kyseisen operaation toiminta mahdollisimman selväkielisesti. Kutsusanomaan liitetään lisäksi sana Pyynto ja vastaussanomaan Vastaus. Lisäksi kummallekin sanomalle määritetään pakollinen palvelutunnus-attribuutti, joka sisältää lyhyemmän, operaation yksilöivän koodin.

Elementtien nimien tulisi olla kuvaavia ja ymmärrettäviä. Lyhenteitä tulisi välttää, lukuunottamatta vakiintuneita, kaikille tuttuja lyhenteitä kuten esimerkiksi Pvm. Elementtien nimien tulisi olla korkeintaan 32 merkin pituisia.

Attribuuttien ja elementtien arvojen, jotka muodostavat sanoman sisällön, ei tarvitse noudattaa näitä nimeämissääntöjä.

Esimerkiksi palvelu HaeHenkilonAnsaintatiedot sisältää yhden operaation, jonka kutsusanoma on HaeHenkilonAnsaintatiedotPyynto ja vastaussanoma HaeHenkilonAnsaintatiedotVastaus.

Esimerkkitiedostossa EsimerkkipalveluVastaus.xsd on esimerkki vastaussanoman skeemasta, jossa juurielementti sisältää vakio-osan, poikkeustiedot ja liiketoimintaosan. Juurielementille on määritelty palvelutunnus-attribuutti. Elementille EsimerkkipalveluVastaus on määritelty oma tyyppi EsimerkkipalveluVastausTyyppi, koska kaikki ohjelmistot eivät hallitse elementin sisällä määriteltyjä anonyymejä complexType-määrityksiä. Vastaussanoman liiketoimintaosa on määritelty erillisessä skeemassa Vastaus.xsd. Skeemalle on määritelty ominaisuus elementFormDefault="qualified", eli skeeman mukaisissa XML-sanomissa elementtien on esiinnyttävä nimiavaruuksien kanssa.

Yleiset tyypit

Perustyypit

Työeläkejärjestelmän XML-sanomille on määritelty vain muutamia, koko järjestelmälle yhteisiä perustyyppejä. Ne on määritelty omassa skeemassaan Perustyypit.xsd. Näitä tyyppejä tulisi käyttää skeemoissa omien tyyppien tai XML Schema -tyyppien sijaan perustyyppien mukaisten tietojen tyyppeinä. Yhteiset tyypit ovat:

ElakejarjestelynumeroTyyppi

Eläkejärjestelynumeron muodon määrittävä tyyppi, jonka rajoite on määritelty säännöllisellä lausekkeella (regular expression). Tyypin mukainen eläkejärjestelynumero on periaatteessa muodoltaan oikea, mutta esimerkiksi tarkistusmerkin oikeellisuutta ei lasketa.

ElakevakuuttajaTyyppi

Eläketurvakeskuksen ylläpitämien eläkevakuuttajanumeroiden (laitosnumeroiden) muodon määrittävä tyypi. Vaikka eläkevakuuttajanumerot koostuvat käytännössä 2 tai 5 numerosta, niitä on perinteisesti välitetty 5-merkkisinä merkkijonoina, mistä syystä niiden tyyppinä XML-sanomilla on 2 - 5-merkkinen merkkijono.

HenkilotunnusTyyppi

Suomalaisen henkilötunnuksen muodon määrittävä tyyppi, jonka rajoite on määritelty säännöllisellä lausekkeella. Tyypin mukainen henkilötunnus on periaatteessa muodoltaan oikea, mutta esimerkiksi tarkistusmerkin oikeellisuutta ei lasketa.

SukupuoliTyyppi

Arvojoukko eli enumeraatio, jonka arvona voi olla joko M tai N. (M = mies, N = nainen.)

YTunnusTyyppi

Suomalaisen yritystunnuksen muodon määrittävä tyyppi, jonka rajoite on määritelty säännöllisellä lausekkeella. Tyypin mukainen Y-tunnus on periaatteessa muodoltaan oikea, mutta esimerkiksi tarkistusmerkin oikeellisuutta ei lasketa.

Vakio-osa

Kaikille työeläkejärjestelmän XML-sanomille liitettävän vakio-osan rakenne on määritelty omassa skeemassaan VakioOsa.xsd. Vakio-osan tietoja käytetään sanomilla seuraavasti:

Aikaleima

Aikaleima-elementin arvon tulee olla XML-sanoman muodostamisajankohta. Pyyntö- ja vastaussanomalla tulee olla omat aikaleimansa. Aikaleimaa käytetään lähinnä ongelmien selvittelyyn, mutta sitä voidaan hyödyntää myös tietojenantokirjauksissa tai esimerkiksi silloin, kun halutaan varmistaa sanomien käsittelyn tapahtuvan tietyssä järjestyksessä. Aikaleima on xs:dateTime-tyyppinen ja se tulisi asettaa mahdollisimman tarkasti - mielellään millisekunnin tarkkuudella.

AlkuperainenLahettaja

Tapahtuman käynnistäneen toimijan tunniste; yleensä laitosnumero tai Y-tunnus, mutta voi olla myös henkilötunnus tai vakuutusnumero. Tiedolle on tarvetta lähinnä silloin, kun lähettäjä ei suoraan kutsu kutsuttavaa palvelua. Esimerkiksi eläkevakuuttajan käyttäessä Arekin ansaintajärjestelmän palveluja, käytöstä seuraa yleensä ETK:n järjestelmiin tehtäviä palvelupyyntöjä. Arek voi liittää näihin pyyntöihin tiedon alkuperäisestä lähettäjästä, joka on lähettänyt pyynnön Arekin ansaintajärjestelmään.

Laskutustieto

Laskutustietoa voidaan käyttää yksilöimään tietystä palvelukutsusta aiheutuneet kustannukset tietylle taholle kutsuneen organisaation sisällä. Laskutustieto voi olla esimerkiksi kustannuspaikan koodi. Laskutustieto on korkeintaan 20 merkin mittainen.

LahettavaElakevakuuttaja

Kutsusanoman lähettävän eläkevakuuttajan eläkevakuuttajanumero (laitosnumero). Tätä tietoa voidaan hyödyntää esimerkiksi

• tarkistettaessa, onko pyytäjällä oikeus nähdä pyytämänsä tieto
• palvelun laskutustiedon keräämiseen (palvelun käytöstä laskutetaan lähettävää eläkevakuuttajaa)
• tietojenantokirjausten muodostamiseen.

LahettajanHoitavaToimija

Lähettävän eläkevakuuttajan hoitavan toimijan eläkevakuuttajanumero (laitosnumero). Tämä tieto esiintyy vakio-osalla, jos lähettävä eläkevakuuttaja ei ole itse muodostanut XML-sanomaa vaan joku toinen eläkevakuuttaja hoitaa lähettävän eläkevakuuttajan asioita. Eläketurvakeskuksen YELA-järjestelmästä voidaan tarkistaa, onko lähettävän eläkevakuuttajan ja lähettäjän hoitavan toimijan välillä voimassa oleva hoitosuhde. Lähettäjän hoitava toimija ei tarkoita järjestelmien teknisestä ylläpidosta tai kehityksestä vastaavaa ohjelmistotaloa tai palvelukeskusta.

LahettajanOhjelma

Tietoa kutsusanoman lähettäjän ohjelmasta käytetään lähinnä ongelmatilanteiden selvittelyssä. Tieto on korkeintaan 40 merkin mittainen ja se voi olla ohjelman tekninen koodi tai selväkielinen, ohjelman käyttötarkoitusta kuvaava nimi.

LahettajanKayttajatunnus

Tietoa kutsusanoman lähettäjän käyttäjätunnuksesta käytetään lähinnä ongelmatilanteiden selvittelyssä, mutta se voi toimia myös suuntaa-antavana vihjeenä käyttäjän henkilöllisyydestä tietojenantokirjauksissa. Työeläkejärjestelmän yhteistä käyttövaltuushallintaa hyödyntävät järjestelmät (www-käyttöliittymät) voivat laittaa tähän käyttäjän KVH-uid:n. Keskuskonejärjestelmistä syntyville kutsusanomille voidaan laittaa käyttäjän RACF-tunnus. Eräajoissa voidaan käyttää eräohjelman nimeä (sama kuin LahettajanOhjelma) tai jotakin eräohjelman suoritukseen liittyvää tarkentavaa tietoa. Käyttäjätunnus on korkeintaan 64 merkin pituinen.

LahettajanViite

Lähettäjän tulee antaa jokaiselle lähettämälleen kutsusanomalle sanoman yksilöivä tunniste, lähettäjän viite. Elementtien LahettavaElakevakuuttaja ja LahettajanViite tulee olla uniikki yhdistelmä. Lähettäjän viitteeseen kannattaa varmuuden ja selkeyden vuoksi laittaa tieto, josta lähettäjä voidaan tunnistaa. (Esimerkiksi Arekin viitteet alkavat aina A-kirjaimella.) Viite on korkeintaan 30 merkin mittainen.

VastaanottavaElakevakuuttaja

Kutsusanoman vastaanottavan eläkevakuuttajan eläkevakuuttajanumero (laitosnumero). Tätä tietoa voidaan käyttää esimerkiksi organisaation sisäisessä reitityksessä kertomaan, mille eläkevakuuttajalle kutsusanoma tulee toimittaa tai pääteltäessä, miltä eläkevakuuttajalta vastaussanoma on peräisin. (Organisaatioiden välisessä tietoliikenteessä ei ainakaan toistaiseksi ole mitään sanoman sisältöön perustuvaa reititystä vaan kukin palvelun käyttäjä kutsuu itse suoraan palvelun tarjoajan palvelua.)

VastaanottajanHoitavaToimija

Vastaanottavan eläkevakuuttajan hoitavan toimijan eläkevakuuttajanumero (laitosnumero). Jätetään pois sanomalta, jos arvoa ei ole. Tietoa voidaan hyödyntää sisäisessä reitityksessä samaan tapaan kuin vastaanottavaa eläkevakuuttajaa.

VastaanottajanViite

Tieto esiintyy vain vastaussanomalla. (Skeema sallii sen asettamisen myös pyyntösanomalle, mutta palvelun ei tarvitse käsitellä kutsusanomalle asetettua vastaanottajan viitettä millään tavalla.) Vastaussanomalle tulee asettaa tunniste, joka yksilöi sanoman yhdessä elementin VastaanottavaElakevakuuttaja sisällön kanssa. Viite on korkeintaan 30 merkin mittainen.

Huomaa! Elementtien AlkuperainenLahettaja ja Laskutustieto ei ole välttämätöntä esiintyä vastaussanomalla. Mikäli elementit esiintyvät vastaussanomalla, niiden arvojen on oltava samat kuin kutsusanomalla. Elementit LahettajanOhjelma ja LahettajanKayttajatunnus voivat esiintyä tyhjinä, vaikka kutsusanomalla niillä olisikin ollut arvot. Jos elementit eivät ole vastaussanomalla tyhjiä, niiden arvon on oltava kutsusanomalla esiintynyt arvo.

Huomaa myös! Vastaussanomalla esiintyvä LahettavaElakevakuuttaja on kutsusanoman lähettäjä eli vastaussanoman vastaanottaja. Sama koskee elementtejä LahettajanHoitavaToimija, LahettajanViite, LahettajanOhjelma, LahettajanKayttajatunnus, VastaanottavaElakevakuuttaja ja VastaanottajanHoitavaToimija, eli näiden arvot ovat aina vastaussanomalla samat kuin pyynnöllä. Sen sijaan elementtien Aikaleima ja VastaanottajanViite tulisi saada vastaussanomalla eri arvot kuin pyynnöllä.

Esimerkkejä vakio-osan käytöstä eri tilanteissa

Hälytystietojen yleistietoryhmä

Kaikille Arekin muodostamille XML- muotoisille hälytyssanomille liitettävän yleistieto-osan rakenne on määritelty omassa skeemassaan HalytystenYleistietoryhma.xsd. Tietoja käytetään sanomilla seuraavasti:

HalytyksenSyyt

Palautetaan elementissä hälytyksen syyt. Tietojen määrää ei ole rajoitettu. Elementti ei ole pakollinen. Hälytyksen syyt saavat arvokseen hälytyksen nimen esim. Elakehakemus, Elakepaatos, TsTelLel, TyosuhdeMuut, SitoAsia, YelVakuutushakemus, Elakesuhde. Uusia syitä voi lisätä skeemaa muuttamatta.

Halytyskoodi

Hälytyksen koodi 6 merkkiä pitkänä. Pakollinen elementti.

Halytysteksti

Hälytyksen koodin selväkielinen selitys. Pakollinen elementti.

OsapuolenTyyppi

Osapuolen tyyppiä kuvaava koodi. Hälytyksen osapuolena voi olla henkilö, työnantaja yms. taho. Ei pakollinen elementti.

OsapuolenTunnus

Osapuolen yksilöivä tunnus. Esim. henkilötunnus, y-tunnus tai vastaava. Ei pakollinen elementti.

Rekisterointihetki

Hälytyksen aiheuttaneen eläkepäätöksen rekisteröintihetki mahdollisimman tarkasti (millisekuntien tarkkuudella). Ei pakollinen elementti.

Poikkeustiedot

XML-vastaussanomalla voi vakio-osan ja liiketoimintaosan lisäksi esiintyä poikkeustietoja. Poikkeustietojen palvelu voi palauttaa virhe- ja huomautustietoja odottamattomista tilanteista.

Poikkeustiedoista on kaksi skeemaversiota. Vanhempi (2005\02\23) Poikkeustiedot.xsd sekä uudempi (2009\05\06)Poikkeustiedot.xsd. Jäljempänä uuden skeeman lisäominaisuudet on lisätty versiomerkinnän perään.

Kyseisessä skeemassa määrittellään elementti Poikkeustiedot, joka tulee asettaa vastaussanomalle valinnaiseksi elementiksi (ks. EsimerkkipalveluVastaus.xsd). Poikkeustiedot-elementti voi sisältää useita Poikkeus-elementtejä, joista jokainen sisältää seuraavat tiedot:

Taso

Tasolla on 3 sallittua arvoa. Sallitut arvot ja niiden merkitykset ovat:

Virhe	Kutsuttua palvelua ei pystytty suorittamaan
Varoitus	Palvelu suoritettiin, mutta tulokseen sisältyy varoituksia, joihin liittyvät ongelmat ovat palvelun kutsujan vastuulla
Huomautus	Palvelu suoritettiin, mutta tulokseen sisältyy huomautuksia, joihin liittyvät ongelmat ovat palvelun tarjoajan vastuulla

Koodi

Palvelun palauttama virhe-, varoitus- tai huomautuskoodi. Palvelun tarjoaja voi määritellä palvelujensa koodit vapaasti, kunhan ne ovat korkeintaan 20 merkin mittaisia. Koodien merkitykset tulee dokumentoida samalla tavoin kuin esimerkiksi palvelun syöte- ja vastaustiedoissa välitettävien koodien sallitut arvot.

Selite

Selite voi sisältää tarkentavaa tietoa virheestä. Selitteen ei ole tarkoitus olla virhekoodin kuvaus (esim. Virheellinen henkilötunnus) vaan sen tulisi antaa tapauskohtaista lisätietoa (Henkilötunnuksen 010101-010X tarkistusmerkki X on väärä. Pitäisi olla 1).

Kohde

Mikäli poikkeukseen liittyvällä elementillä on elementin yksilöivä id-attribuutti, se voidaan kertoa poikkeuksen Kohde-elementissä. Tämä auttaa poikkeustiedon tulkitsijaa paikantamaan poikkeuksen syyn.

2009\05\06 Skeemaversio: Kohde elementtejä on sallittu 0-n kappaletta ja sille on lisätty attribuutti "tyyppi". Kohde -elementin ja tyyppi -attribuutin yhteiskäytöllä yhden poikkeuksen tiedot voidaan kohdentaa tarvittaessa useaan eri liiketoiminnan kohteeseen.

Esimerkki. Poikkeustiedot -elementissä halutaan välittää yksilöivät tiedot vakuutuksesta ja siihen liittyvistä henkilöistä, joilla huomautettavaa:
<Poikkeus>
  <Taso>Huomautus</Taso>
  <Koodi>ANS12345</Koodi>
  <Selite>Vakuutuksen henkilöillä huomautettavaa tiedossa XXX</Selite>
  <Kohde tyyppi="vakuutus(numero)">12-34567890</Kohde>
  <Kohde tyyppi="henkilö(tunnus)">230467-8901</Kohde>
  <Kohde tyyppi="henkilö(tunnus)">120344-1101</Kohde>
  <Kohde tyyppi="henkilö(tunnus)">-110801-9777</Kohde>
</Poikkeus> 

Huomioitavaa:

Kohde -elementin ja tyyppi -attribuutin yhteiskäyttö on dokumentoitava palvelukuvaus -dokumenttiin ja myös palvelun juurielementin skeemaan, jotta palvelua käyttävä järjestelmä saa tiedon.

Omien tyyppien käyttö

XML Schema -suositus määrittelee laajan joukon perustyyppejä (string, int, boolean jne.), joita XML-skeemoissa voi hyödyntää. Työeläkejärjestelmän XML-sanomia varten on kehitetty muutamia perustyyppejä. Näiden lisäksi kukin palvelun tarjoaja voi määritellä uusia tyyppejä omia palvelujaan varten. Omat tyypit voivat olla organisaatio-, palvelu- tai sanomakohtaisia. Tyyppien nimien tulee päättyä sanaan Tyyppi.

Skeeman tulisi kuvata tiedon rakenne, mutta ei liiketoimintalogiikan tarkistuksia. Merkkijonotyyppisten elementtien suurimmat sallitut arvot kannattaa merkitä määrittelemällä oma simpleType, joka lisää string-perustyypille maxLength-rajoitteen (restriction). Omia tyyppejä ei kannata käyttää tietyn tiedon sallittujen arvojen määrittelyyn. Arvojoukot kuvataan erillisessä dokumentaatiossa ja niiden oikeellisuus tarkistetaan sovelluslogiikassa. Näin esimerkiksi uuden arvon lisääminen sallittujen arvojen joukkoon ei edellytä skeeman muuttamista ja kaikkien sen perusteella generoitujen ohjelmakomponenttien päivitystä.

Koska sanomien kutsu- ja vastauselementeillä on omat rakenteensa, niillä on omat tyyppinsä. Elementin tyyppi voidaan määritellä elementtimäärityksen sisällä ns. anonyymina complexTypenä, mutta kaikki ympäristöt eivät tue näitä täysin. Parempaan yhteensopivuuteen päästään määrittelemällä nimetyt tyypit ja viittaamalla elementtimäärityksissä niihin.

Useilla sanomilla tai useissa palveluissa uudelleen käytettäväksi tarkoitetuista ydintyypeistä voi muodostaa omia ydintyyppikirjastojaan. Tällöin kannattaa kuitenkin pidättäytyä tyypeissä, joita käytetään kaikilla sanomilla täsmälleen samanlaisina. Tyyppejä muodostettaessa kannattaa välttää syviä rakenteita, koska syvät hierarkiat heikentävät ohjelmistojen suorituskykyä sanomaa muodostettaessa ja luettaessa.

XML Schema -perustyypeistä choice on toistaiseksi heikosti tuettu ja yhteensopivuuden vuoksi on suotavaa määritellä sen sijaan sequence, joka sisältää kaikki vaihtoehdot valinnaisina elementteinä (minOccurs="0"). Tällöin palvelun liiketoimintalogiikan on tarkistettava, että sanomalla elementeistä esiintyy täsmälleen yksi.

Rahamäärät

Rahamäärät ilmoitetaan työeläkejärjestelmän XML-sanomilla sentteinä. Rahamäärän ilmaisemiseen soveltuvat XML Schema -perustyypit int ja long. Skeemaan kannattaa erikseen laittaa huomautus siitä, että tiedon yksikkö on sentti eikä euro.

Päivämäärät ja kellonajat

Päivämäärät kannattaa määritellä XML Schema -perustyypillä date ja kellonajan sisältävät tiedot tyypillä dateTime. XML-sanomilla tiedot esitetään aikavyöhyketiedon kanssa.

Versiointi

Palveluille ja niihin liittyville skeemoille tulee määritellä nimiavaruudet. Nimiavaruudet ovat HTTP-osoitteita ja niissä tulee esiintyä palvelua tarjoavan organisaation tunniste, päivämäärä muodossa VVVV/KK/PV sekä palvelun tai skeeman nimi. Päivämäärä voi olla esimerkiksi skeeman luontiajankohta, palvelun suunniteltu tuotantoonsiirtopäivä tai skeemaan muutoksen aiheuttaneen lakimuutoksen päivä. Tärkeintä on, että samalla organisaatiolla voi olla samasta palvelusta useita eri versioita, joilla jokaisella on oma nimiavaruutensa.

Nimiavaruuksiin perustuvan versioinnin lisäksi pieniä muutoksia, jotka eivät riko rajapinnan taaksepäin yhteensopivuutta voidaan ilmaista asettamalla palvelun juurielementille string-tyyppinen attribuutti sanomaversio, joka voi olla muotoa X.y. Tämän attribuutin avulla palvelua kutsuva asiakasohjelma voi kertoa, mitä sanomaversiota se käyttää.

Tietoturva

Työeläkejärjestelmän XML-sanomilla noudatetaan WS Security -standardin mukaisia allekirjoituksia tietojen muuttumattomuuden ja lähettäjän varmentamiseksi. Tietoja ei kryptata. Toistaiseksi allekirjoituksiin käytetään UsernameToken-profiilin mukaista tunnusta ja salasanaa, mutta jatkossa on tarkoitus siirtyä X.509 Certificate Token -profiilin käyttöön.

SOAP-autentikointi

WS Securityn mukainen tunnus ja salasana sijoitetaan SOAP-sanoman header-osaan.

Esimerkki SOAP-kutsusta

Eräajojen autentikointi

WS Securityn mukainen tunnus ja salasana sijoitetaan erätiedoston alkuun.

Huomaa, että jos erätiedoston rakenne on määritelty omassa skeemassaan, kyseiseen skeemaan pitäisi määritellä myös Security-elementti, jotta autentikointitiedot sisältävän erätiedoston voi validoida skeemaa vasten.

Esimerkki erätiedostosta

SOAP-sanomien välitys

Merkistö ja pakkaus

SOAP-sanomilla sisällön merkistöpakkauksena tulee käyttää UTF-8:aa. Kaikkien XML-jäsentimien tulee osata käsitellä UTF-8:aa ja UTF-16:tta. UTF-16:lle ei ole tarvetta työeläkejärjestelmän XML-sanomilla ja työkalujen tuki UTF-8:lle on huomattavasti parempi.

Aikavyöhyketieto

XML Schema -tyyppien date ja dateTime sekä näistä johdettujen tyyppien mukaiset tiedot on välitettävä sanomilla aikavyöhyketiedon kanssa.

Suositeltava tapa liittää kellonaikaan aikavyöhyketieto on muuntaa tieto UTC-aikaan ja merkitä aikavyöhykkeeksi Z.

Oman ympäristön aikavyöhykkeen käsittelyä voi testata esimerkkitiedostolla aikaleimatesti.xml. (Testin suorittamiseen tarvitaan myös skeema aikaleimatesti.xsd.)

W3C:n työryhmä on julkaissut muistion aikavyöhyketiedon käytöstä ja käsittelystä.

Tyhjän tiedon välittäminen

Mikäli elementin esiintyminen sanomalla on skeeman mukaan valinnaista (minOccurs="0") ja elementillä ei ole arvoa, koko elementti alku- ja lopputageineen tulisi jättää pois sanomalta.

Validointi

Yhteensopivuuden varmistamiseksi ja virheiden ehkäisemiseksi XML-sanoman muodostava osapuoli voi validoida muodostamansa sanoman. Myös vastaanottava osapuoli voi validoida sanomat. Testiympäristöissä validointi on suotavaa tehdä kummassakin päässä, mutta suorituskykysyistä tuotantoympäristössä validointi voidaan kytkeä pois päältä.

Esimerkki

Esimerkki SOAP-kutsusta

Erätiedostojen välitys

Eräajorajapinnoille määritetään omat skeemansa, joihin liitetään yleiset erän tiedot. Erätiedostot välitetään FTP:llä. Palvelun tarjoaja määrittelee tiedostojen nimeämiseen, ftp-palvelimen osoitteeseen yms. liittyvät asiat.

Erätiedostoihin voidaan lisätä WS Security -suosituksen mukaiset autentikointitiedot.

Esimerkki

Esimerkki erätiedostosta

Tämän ohjeiston muutokset

Tämä ohjeisto korvaa edellisen XML-ohjeiston, joka on edelleen luettavissa osoitteessa ws.tyoelake.fi/2005/01/10/tel-xml.pdf. Tämä versio on kirjoitettu kokonaan uudelleen alusta alkaen.

Muutokset versiosta 10.1.2005 versioon 18.9.2005

• Rahamäärien merkitsemiseen suositellaan tyyppejä xs:int ja xs:long (aiemmin xs:integer)
• Päivitetty vakio-osan tietojen maksimipituudet vakio-osan version 2005/02/23 mukaisiksi
• Lisätty vaatimus aikavyöhykkeestä sanomilla tyyppien xs:date ja xs:dateTime yhteydessä
• Vaihdettu esimerkit ajantasaisempiin versioihin; esimerkkeinä käytetään erillisiä, linkitettyjä tiedostoja
• Uudistettu rakenne, tiivistetty tekstiä

Muutokset 18.9.2005 jälkeen

Jatkossa muutokset merkitään seuraavaan taulukkoon.