Koodistot - Yhteentoimivuusmenetelmän mukainen toimintamalli

 LUONNOS

1 Taustaksi

Tällä sivulla kuvataan yhteentoimivuusmenetelmän mukainen tapa määritellä ja kuvata koodistoja Koodistot-työkalulla, kun organisaatio (eli sisällöntuottaja) haluaa julkaista koodistojaan myös muiden organisaatioiden tietoon ja hyödynnettäväksi.

• Näitä kuvauksia tarkennetaan myöhemmin, kun eri yhteistyöryhmien toiminta on käynnistynyt ja toimintamallin soveltuvuudesta on saatu enemmän käytännön kokemusta.
• Tämä sivusto ei kuvaa Koodistot-työkalun käyttöä, vaan sen käyttöohje on oma dokumenttinsa.

Kansallisella tasolla Ydinkoodistoryhmän (YKR) on tarkoitus koodinoida julkishallinnossa tehtävää koodistotyötä. Tavoitteena on edistää eri tahojen tekemää koodistotyötä, välttää päällekkäinen työ ja auttaa eri osapuolia käyttämään Yhteentoimivuusalustan työkaluja sovittujen periaatteiden mukaisesti. Yhteentoimivuusalustan tuki auttaa Ydinkoodistoryhmää tässä työssä mm. antamalla tukea Koodistot-työkalun käytössä ja tekemällä Ydinkoodistoryhmän käsittelyyn tuleville koodistoille teknisluontoiset tarkastukset. Varsinainen sisällön ja substanssin arviointi on Ydinkoodistoryhmän tehtävä. Ydinkoodistoryhmä huolehtii myös siitä, että eri tahojen tarpeet ja näkökulmat otetaan riittävästi huomioon muun muassa kommentointikierrosten avulla. 

Tässä dokumentissa on kuvattu periaatteet, joilla Ydinkoodistoryhmä osallistuu koodistojen hyväksymiseen. Sen on tarkoitus toimia samalla periaatteella kuin Ydinsanastoryhmän sanastojen ja Käsitemalliryhmän tietomallien kansallisen tason määrittelytyössä. Tässä dokumentissa on kuvattu myös periaatteet, joilla tietoalueet osallistuvat koodistojen hyväksymiseen. Mikäli tietoaluetta ei vielä ole perustettu tai tietoalueen koodistotyöryhmä ei vielä ole toiminnassa, sen vastuulla olevan koodistojen arvioinnin ja hyväksymisen hoitaa Ydinkoodistoryhmä. Ydinkoodistoryhmän on kuitenkin ensisijaisesti tarkoitus olla julkishallinnon koodistotyötä ohjaava ja koordinoiva taho eikä varsinaista koodistotyötä tekevä taho, vaikka sillä koodistotyön asiantuntemusta onkin.

Alla koodistojen määrittelyn prosessi kokonaisuudessaan (versio 0.95; päivitetty 30.10.2018)

Huom. Selkeyden vuoksi tässä vuokaaviokuvauksessa ei ole mukana koodiston hylkäämistä eikä prosessin keskeytymistä tai päättymistä. (Sisällöntuottaja voi tarvittaessa keskeyttää prosessin missä vaiheessa tahansa.)

2 Käyttöoikeudet

Mikäli organisaatio haluaa tuoda koodistonsa Yhteentoimivuusalustalle, mutta ei vielä ole rekisteröitynyt sisällöntuottajaksi, on sen ensimmäiseksi haettava alustan käyttöoikeutta VRK:n Yhteentoimivuusalustan tuelta (katso myös Käytön aloittamisen ohjeet). 

Yhteentoimivuusalustan tuki antaa uudelle sisällöntuottajaorganisaatiolle ohjeistuksen Yhteentoimivuusalustan periaatteista ja yhteistyömallista (mm. tietoalueiden ja Ydinsanastotyöryhmän rooli kokonaisuudessa, hyväksymiskäytännöt yms.)

Tämän jälkeen Yhteentoimivuusalustan tuki antaa käyttöoikeudet sisällöntuottajaorganisaation pääkäyttäjälle, joka puolestaan antaa käyttöoikeuksia oman organisaationsa muille käyttäjille.

Käyttöoikeudet saatuaan sisällöntuottajaorganisaatio pääsee tuottamaan sisältöjä Koodistot-työkalulla, mutta halutessaan myös muilla Yhteentoimivuusalustan työkaluilla (Tietomallit ja Sanastot).

3 Koodistojen määrittelyosaamisen hankkiminen

Yleensä sisällöntuottajilla on jo valmis koodisto, joka halutaan tuoda Koodistot-työkaluun, mutta koodistoon ehkä halutaan tehdä muokkauksia ja täydennyksiä ennen kuin se julkaistaan Yhteentoimivuusalustalla. Tai usean organisaation yhteenliittymä voi haluta yhdenmukaistaa (harmonisoida) aineistojaan ennen kuin niitä tuodaan Koodistot-työkaluun. Tässä tapauksessa koodistojen määrittelyyn voidaan tarvita apua ennen kuin koodistot teknisesti viedään ja tallennetaan Koodistot-työkaluun.

Mikäli sisällöntuottajaorganisaatiolla ei ole kokemusta koodistojen määrittelystä tai Koodistot-työkalun käytöstä, sen kannattaa ottaa yhteyttä ja pyytää opastusta VRK:n Yhteentoimivuusalustan tuelta.

• Tarvittaessa Yhteentoimivuusalustan tuki auttaa sisällöntuottajaa löytämään sopivia koodistotyön osaajia (mm. kuvaa, minkä tyyppistä osaamista näiltä edellytetään).
• Yhteentoimivuusalustan tuki auttaa käyttäjiä Koodistot-työkalun käyttöönotossa ja antaa teknistä tukea sen käytössä.

Eri tietoalueille (domain) nimetään koodistotyöryhmiä (intressiryhmiä), joiden tehtävänä on tukea oman aihealueensa koodistojen tekemistä ja oman tietoalueensa organisaatioiden yhteistyötä. Koodistotyön opastus ja tuki siirtyy enemmän tietoalueiden vastuulle, kun ne ovat saaneet toimintansa käyntiin.

• Koodistotyöryhmän tehtävänä on pitää huolta siitä, että eri toimijat tuottavat tietoalueelle koodistoja yhteentoimivuusmenetelmän mukaisesti (ns. sisältötyön tuki).

4 Koodistomäärittelyjen käynnistäminen

Yhteentoimivuusalustassa koodistot on kytketty johonkin rekisteriin: rekisteri on looginen kokonaisuus, joka sisältää tiettyyn asiayhteyteen liittyviä koodistoja.  Ensimmäiseksi sisällöntuottaja tarkistaa, onko Koodistot-työkalussa jo olemassa sopiva rekisteri. Mikäli sopivaa rekisteriä ei löydy, sisällöntuottajan pitää pyytää Yhteentoimivuusalustan tukea perustamaan uusi rekisteri.

Mikäli koodistoon tarvitaan muutoksia tai koodistoa aletaan määritellä alusta alkaen, varsinainen määrittelytyö alkaa aihealueen eli substanssin asiantuntijoiden nimeämisellä. Nämä asiantuntijat kootaan työpajaan, jossa yhdessä kuvataan koodiston ja siihen kuuluvien koodien ominaisuudet. Työpajoja pidetään tarvittaessa useampikin, eli niin monta kuin tarvitaan koodiston ja siihen sisältyvien koodi(arvoj)en tuottamiseen.

Tarvittaessa myös tietoalueen koodistoryhmän asiantuntijoita voi sisällöntuottajien itsensä lisäksi osallistua mallinnussessioon. On tärkeää varmistaa määrittelyjen yhdenmukaisuus aiempien koodistojen kanssa ja Yhteentoimivuusalustan tietojen uudelleenkäyttöperiaatteen mukaisesti. Laajoja koodistoja määriteltäessä on aiheellista sopia välitarkistuspisteitä asiantuntijoiden kanssa, jotta voidaan varmistaa työn eteneminen sovittujen periaatteiden mukaisesti.

Yhteentoimivuusmenetelmän mukaisessa määrittelytyössä pyritään hyödyntämään (uudelleenkäyttämään) aiemmin määriteltyjä koodistoja mahdollisimman paljon. Näin samoja tietomäärityksiä ei tarvitse tehdä moneen kertaan, vaan voidaan tehdä viittauksia jo aiemmin tehtyihin koodistoihin. Ensimmäinen vaihe siis on tarkistaa, onko jossain jo aiemmin tehty omaan käyttötarpeeseen sopiva koodisto ja hyödyntää sitä sellaisenaan. 

Jos sopivaa aiempaa koodistoa ei ole, niin riittääkö entisen oman koodiston päivittäminen? Mikäli tämä sopii, sisällöntuottaja tekee omasta koodistostaan uuden version.

• Versio on yksittäisen koodiston uusi tai vanha versio. Esim. koodisto "Kunnat 2017" ja "Kunnat 2018" ovat eri koodistoversioita. Niiden voimassaolon alkamis- ja päättymispäivämäärät poikkeavat toisistaan. Tyypillisesti uusi versio korvaa vanhan version. (Vanha versio jää edelleen talteen, jotta esimerkiksi tilastoinnissa voidaan tarkistaa tiettynä ajanhetkenä voimassa olleen koodiston tietoja, mutta vanhan version tilakoodi ilmaisee, että se ei enää ole aktiivisessa käytössä. Periaatteessa Koodistot-työkalusta ei koskaan poisteta kerran Voimassa oleva -tilassa ollutta koodistoa.)
• Yksittäisenkin koodin muuttaminen valmiista koodistosta merkitsee, että koodistosta syntyy uusi versio.

Mikäli Koodistot-työkalusta löytyy lähes tarvetta vastaava koodisto, sisällöntuottaja voi tehdä tämän aiemman koodiston pohjalta uuden koodiston eli variantin. 

• Variantti on jonkin koodiston muokattu versio toiseen käyttötarkoitukseen. Variantissa koodeja voi olla esimerkiksi enemmän tai vähemmän kuin alkuperäisessä koodistossa, jonka variantti se on. Esimerkkejä varianteista ovat Pääkaupunkiseudun kunnat (variantti Kunnat 2018 -koodistolle) ja 5-vuotisikäryhmät työttömyysturvassa (variantti 1-vuotisikäryhmät-koodistolle).

Mikäli mikään aiempi koodisto ei sovellu sisällöntuottajan tarpeisiin, tuotetaan kokonaan uusi koodisto koodeineen ja koodiarvoineen. Tarvittaessa koodin ja/tai koodiston nimi voidaan linkittää sopivaan Sanastot-työkalun käsitteeseen. Ja jos tarvittava käsite puuttuu, sen voi ehdottaa lisättäväksi sanastoon

• Esimerkiksi liikennevälineiden koodistosta voi puuttua mopoauton koodi. Jos sanastosta löytyy tätä vastaava käsite, sen voi linkittää koodiin. Tai jos käsitettä ei ole sanastossa, sisällöntuottaja voi tehdä ehdotuksen lisätä tämä käsite (johonkin tieliikenne)sanastoon ja ehdottaa myös käsitteelle määritelmää.

Kun koodisto on valmis hyväksyttäväksi, sen tilaksi muutetaan Odottaa hyväksyntää. 

Tämän jälkeen Yhteentoimivuusalustan tuki arvioi, onko koodisto teknisesti valmis.

• Mikäli kaikki on kunnossa, koodisto lisätään Ydinkoodistoryhmän työjonoon. 
• Mikäli koodistossa on jotain korjattavaa, Yhteentoimivuusalustan tuki muuttaa koodiston takaisin tilaan Luonnos ja ottaa yhteyttä sisällöntuottajaan, jotta tämä voi tehdä tarvittavat korjaukset. Kun ne on tehty, sisällöntuottaja palauttaa koodiston taas takaisin käsittelyyn vaihtamalla tilaksi Odottaa hyväksyntää.

5 Ydinkoodistoryhmän (YKR) käsittely

Koko julkishallinnon yhteinen ydinkoodistoryhmä YKR koordinoi kokonaisuutta ja käy läpi sille hyväksyttäväksi toimitetut koodistoehdotukset.

1. Aluksi YKR tarkistaa onko koodiston kuvaus ohjeiden ja linjausten mukainen.
   1. Mikäli koodiston määrittelyssä on korjattavaa, se lähetetään takaisin laatijalleen korjausohjeiden kera, ja koodiston määrittelyprosessi käynnistyy alusta -> katso edellä luku 3.
2. YKR arvioi, kannattaako koodisto ottaa koko julkishallinnon yhteiseen käyttöön (käyttöalue = koko julkishallinto). Mikäli näin on, arvioidaan seuraavaksi, tarvitseeko koodiston tai sen yksittäisen koodin tietoja vielä muokata ennen kuin koodisto on valmis julkaistavaksi. Ydinkoodistoryhmä tekee tarvittavat muokkaukset. 
3. Koodisto lähetetään kommenttikierrokselle. 
   Saatujen kommenttien perusteella YKR tekee mahdollisesti tarvittavat muutokset koodistoon. 
4. YKR hyväksyy koodiston ja muuttaa sen tilaksi ”Voimassa oleva”. 
5. Sisällöntuottajalle lähetetään ilmoitus koodiston hyväksymisestä.

5 Yksittäisten koodimäärittelyjen tekeminen

Tässä luvussa kuvataan yksittäisen koodin määrittelyprosessi. Kun kaikki koodien määrittelyt on tehty, ne kootaan yhteen koodistoksi, joka lähetetään ydinkoodistoryhmän käsittelyyn (luku 6). 

Koodin määrittelyssä toistuvat seuraavat vaiheet:

1. Löytyykö koodin tietosisällön kuvaamiseen sopiva käsite jossain Sanastot-työkalun sanastossa?
   1. Mikäli sopiva käsite löytyy, se voidaan ottaa koodin määrittelyn pohjaksi. 
      Esimerkki: tarvitaan koodisto, jolla ilmaistaan henkilön äidinkieli. Julkisen hallinnon yhteisestä sanastosta löytyy käsite Äidinkieli, jonka määritelmä on seuraava: kieli, joka on merkitty väestötietojärjestelmään henkilön kieleksi.
      Mikäli tämä valmis määritelmä sopii määrittelijöiden käyttötarkoitukseen, siihen voidaan viitata koodin kuvauksessa. 
   2. Mikäli sopivaa aiemmin määriteltyä käsitettä ei löydy, sisällöntuottaja määrittelee koodin itse ilman viittausta sanaston käsitteeseen.
      Esimerkki: halutaan määritellä koodisto eri ajoneuvoille, mutta mopoauto-käsitettä ei löydy sanastoista. Sisällöntuottaja voi 
      • joko ehdottaa lisättäväksi mopoauto-käsitteen (johonkin tieliikenne)sanastoon ja tässä yhteydessä antaa oman ehdotuksensa määritelmästä
      • tai suoraan tekee vain oman määritelmänsä koodille (koodin kuvauksessa ei ole viittausta mihinkään sanastoon)
2. Koodin kuvaukseen lisätään muut tarvittavat metatiedot (voimassaoloaika, viittaukset kansainvälisiin referenssikoodistoihin, mikäli näitä on yms).
3. Kun kaikki koodit/koodiarvot (1 - n kpl) on määritelty tällä tavalla ja koodisto on sisällöntuottajan mielestä valmis, hän merkitsee koodiston tilaksi "Odottaa hyväksyntää".  
4. Yhteentoimivuusalustan tuki saa tiedon koodiston valmistumisesta ja käy läpi sen läpi. Se tarkistaa, onko koodiston kuvaus laadittu ohjeiden ja linjausten mukaisesti.
   1. Mikäli koodisto on muodollisesti oikein laadittu, se siirtyy hyväksymiskäsittelyyn
   2. Mikäli koodiston määrittelyssä on korjattavaa, se lähetetään takaisin laatijalleen korjausohjeiden kera, ja koodiston määrittelyprosessi käynnistyy alusta.
5. Hyväksymiskäsittelyssä Yhteentoimivuusalustan tuki arvioi, voidaanko koodisto hyväksyä sellaisenaan, vai onko se vielä lähetettävä Ydinkoodistoryhmän arvioitavaksi. Yhteentoimivuusalustan tuki 
   
   1. joko hyväksyy koodiston itse (tavallisesti silloin, kun on kyse jo vakiintuneesta ja laajasti käytössä olevasta koodistosta), muuttaa koodiston tilaksi "Voimassa oleva"  ja lähettää tästä hyväksynnästä tiedon sisällöntuottajalle tai 
   2. harkintansa mukaan lähettää sen Ydinkoodistoryhmän käsittelyyn -> katso alla luku 6