Työeläkealan XML-ohjeisto

Versio 2011-06-15

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

Sisällys

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äkealalla 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äkealan XML-ohjeisto pohjautuu pääosin W3C:n suosituksiin. XML-toteutusten on oltava yhteensopivia alla mainittujen suositusten kanssa.

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

Lisäksi on hyvä tuntea seuraavat standardit:

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-kuvauksiin on hyvä liittää tieto WS Security -ominaisuuksien käytöstä.

WSDL-kuvauksiin ei tarvitse kuvata palvelun julkaisuosoitetta (soap:address-elementin location-attribuutti) tai sidoksia käytettäviin kuljetustapoihin (soap:binding-elementin transport-attribuutti). WSDL-kuvaus voi sisältää näiden tietojen osalta mitä tahansa; oikeat eri ympäristöissä käytettävät osoitteet ja kuljetustavat dokumentoidaan muualla.

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

Sanomakuvausten rakenne

Työeläkealan XML-sanomat sisältävät yhteisen vakio-osan ja sanomakohtaisen liiketoimintaosan. Vastaussanomat voivat lisäksi sisältää poikkeustietoja. 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 Sanomien välittämisestä.

Palveluille, joita voi kutsua sanomajonojen kautta, ei tehdä erillisiä kuvauksia, vaan hyödynnetään yllä kuvatun rakenteen mukaisia skeemoja. Sanomajonoissa välitettävät kutsu- ja vastaussanomat vastaavat WSDL-kuvauksessa määriteltyjä SOAP-sanomia. Katso esimerkki sanomajonon kautta välitetystä kutsusanomasta ja vastaussanomasta.

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. Eräajorajapintojen tulee pystyä muodostamaan vastauserä, jolla on yleiset erän tiedot ja yhtä monta vastaussanomaa kuin pyyntöerällä oli pyyntösanomia.

Erätiedostoon sijoitettavan sanoman tulisi olla täsmälleen samanlainen kuin SOAP-sanomalla SOAP Bodyn sisältö (sanoman juurielementti, joka sisältää vakio-osan, mahdolliset poikkeustiedot ja liiketoimintaosan). Näin eränä ja ajantasaisesti välitettäviä sanomia voidaan käsitellä samoilla ohjelmilla.

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

Yleisiä koko erää koskevia poikkeustietoja ei ole määritetty, mutta eräajorajapintoja kuvattaessa voidaan rajapintakuvauksen juuritasolle määritellä erillinen poikkeustietoryhmä, joka kertoo erän käsittelyssä muodostuineista poikkeuksista. Tällaisen poikkeustietoryhmän rakenne voidaan suunnitella palvelukohtaisesti ja siihen sijoittaa semanttisesti merkityksellisiä tietoja ja rakenteita (esimerkiksi vakuutusnumerot, joiden käsittelyyn liittyi virheitä tai henkilötunnukset, joihin liittyi huomautuksia).

Esimerkki vastauserätiedoston rakenteen kuvaavasta skeemasta - sisältää myös erälle määritellyt poikkeustiedot sekä autentikointitiedot. Katso myös sanomien ja 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). Yhdysmerkin pois jättämisen jälkeen esiintyvä kirjain on iso, esim. sanasta vakio-osa johdettu elementtinimi on VakioOsa.

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ää, lukuun ottamatta 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äkealan XML-sanomille on määritelty vain muutamia, koko toimialalle 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äkealan 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
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. Yhteisestä eläkelaitosrekisteristä (Yela) 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äkealan 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, 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

Poikkeustiedot

XML-vastaussanomalla voi vakio-osan ja liiketoimintaosan lisäksi esiintyä poikkeustietoja. Poikkeustietojen palvelu voi palauttaa virhe- ja huomautustietoja odottamattomista tilanteista. Poikkeustietoelementin rakenne on määritelty omassa skeemassaan Poikkeustiedot.xsd. 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).
elementit
Mikäli poikkeukseen liittyvillä vastaussanoman elementeillä on yksilöivät attribuutit (tyyppiä xs:ID), ne voidaan kertoa poikkeuksen elementit-attribuutissa. Tämä auttaa poikkeustiedon tulkitsijaa paikantamaan poikkeuksen syyn. Yhteen poikkeukseen voi liittyä yksi tai useita elementtejä. Mikäli poikkeus ei liity mihinkään vastaussanoman elementtiin, elementit-attribuutti jätetään pois Poikkeus-elementiltä.

Poikkeustiedot-elementti tulisi määritellä vastaussanomalle vakio-osan ja liiketoimintaosan väliin. Sanomia käsittelevien ohjelmien tulee kuitenkin varautua käsittelemään myös muussa kohdassa esiintyvät poikkeustiedot.

Katso myös erätiedostojen poikkeustiedot.

Omien tyyppien käyttö

XML Schema -suositus määrittelee laajan joukon perustyyppejä (string, int, boolean jne.), joita XML-skeemoissa voi hyödyntää. Työeläkealan 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 pituudet 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.

Tämän ohjeiston määrittelemien kaikilla sanomilla esiintyvien tietojen lisäksi toimijat voivat määritellä omia, usein toistuvia tietorakenteitaan. Esimerkiksi Arekin hälytyssanomille on määritelty hälytysten yleistietoryhmä. Toimijakohtaiset rakenteet tulisi sijoittaa toimijan omaan nimiavaruuteen, ei työeläkealan yhteiseen ws.tyoelake.fi-nimiavaruuteen.

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äkealan 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 (X ja y ovat numeroita). Tämän attribuutin avulla palvelua kutsuva asiakasohjelma voi kertoa, mitä sanomaversiota se käyttää.

Sanomien ja erätiedostojen välitys

XML-ominaisuudet

Sanomat ja tiedostot eivät saa sisältää Document Type Declaration - tai Processing Instruction -määreitä. SOAP-määrittelyyn kirjattu vaatimus koskee myös erätiedostoja ja sanomajonoissa välitettäviä sanomia.

Sanoman ja tiedoston alkuun tulisi lisätä XML declaration, mutta palvelujen on voitava käsitellä sanomat ja tiedostot, joista se puuttuu. Mikäli XML declaration sisältää encoding-attribuutin, sen arvon on oltava UTF-8.

Tietoturva

Työeläkealan XML-sanomilla käytetään WS Security -standardia. Toistaiseksi palvelun kutsujan tunnistamiseen käytetään UsernameToken-profiilin mukaista tunnusta ja salasanaa, mutta jatkossa on tarkoitus siirtyä X.509 Certificate Token -profiilin käyttöön ja sanomien allekirjoituksiin muuttumattomuuden varmistamiseksi. Tietoja ei kryptata.

Merkistö ja pakkaus

XML-sanomilla ja -erätiedostoissa 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äkealan XML-sanomilla ja työkalujen tuki UTF-8:lle on huomattavasti parempi.

Nimiavaruuksien määrittely

Jotta sanomat olisivat hyödynnettävissä sellaisenaan SOAP-kirjekuoresta tai eräajotiedostosta irroitettuna, itse sanoman sisältöön liittyvät nimiavaruusprefiksien määritykset tulisi tehdä SOAP Bodyn tai eräajotiedoston sisältämän sanoman juurielementissä, ei SOAP-kirjekuoren tasolla tai erätiedoston juurielementissä.

Sanomien koko yleensä pienenee, jos nimiavaruuksille ei määritetä lainkaan prefiksejä vaan vaihdetaan vain oletusnimiavaruutta tarvittaessa, kuten esimerkkierätiedostossa.

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ä.

SOAP-sanomien välitys

SOAP-sanomat muodostuvat SOAP-standardin mukaisesta Header- ja Body-osasta.

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

Esimerkki SOAP-kutsusta

Sanomien välitys sanomajonoissa

Käytettäessä toimijoiden välillä sanomien siirtotapana sanomajonoja sanoman sisällön (vakio-osa, poikkeustiedot, liiketoimintaosa) tulee olla samanlainen kuin saman palvelun HTTP-rajapinnan kautta välitetyn SOAP-sanoman. Sanomaan liitetään SOAP/JMS-määrityksen mukaiset otsikkotiedot.

Esimerkki sanomajonon kautta välitettävästä kutsusanomasta

Erätiedostojen välitys

Erätiedostot välitetään FTP:llä. Palvelun tarjoaja määrittelee tiedostojen nimeämiseen, ftp-palvelimen osoitteeseen yms. liittyvät asiat.

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

Esimerkit

Tallenna kaikki esimerkkitiedostot ZIP-pakettina (noin 24 kt).

Esimerkkipalvelun WSDL-kuvaus

Esimerkkisanomat

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

Muutokset 18.9.2005 jälkeen

Jatkossa muutokset merkitään seuraavaan taulukkoon.

PäivämääräMitä muutettu
18.9.2005 Ensimmäinen uuden mallin mukainen versio.
29.9.2005
2.11.2005
28.05.2008
10.11.2009
15.6.2011
  • Lisätty asiaa sanomien välityksen ja tietoturvan osalta.
  • Laajennettu DTD- ja PI-kielto koskemaan myös erätiedostoja ja sanomajonoissa välitettäviä sanomia.
  • Vaihdettu otsikoiden järjestystä, eriytetty rakenteiden määrittelyä sanomien ja tiedostojen välityksestä, jaettu autentikointitavat eri välitystapojen sisään.
  • Koottu kaikki esimerkkitiedostot oman otsikon alle.
  • Pieniä muutoksia tekstin muotoiluihin.