Tässä ohjeessa käydään läpi esimerkkien avulla Finton sanastojen käyttöä kuvitteellisessa kuvailujärjestelmässä. Jos olet kiinnostunut rajapinnan teknisestä dokumentaatiosta voit tutustua API-dokumentaatioon GitHubissa.

Finton sanastot on mahdollista ottaa käyttöön sekä rajapinnan kautta että paikallisena kopiona. Rajapinnan kautta käytettynä sanastot ovat ajantasaisia, mutta paikallinen kopio on syytä päivittää esimerkiksi kerran kuukaudessa. Toki on myös mahdollista että rajapinnan kautta haettuihin käsitteisiin tulee muutoksia, joten kuvailutietueetkin on hyvä ajoittain tarkistaa automaattisesti.

Kuvailuesimerkki Fintoa hyödyntävästä järjestelmästä

Esimerkissämme kuvailija käyttää YSOa suomen kielellä kuvaillessaan äänitallennetta. Käyttäjä hakee YSOsta käsitettä hakusanalla: kissa ja saa nähdäkseen listan käsitteitä joiden termeihin hakuehto on osunut. Hän valitsee sen jälkeen listalta sopivimman käsitteen, joka tässä tapauksessa on kissaeläimet. Tässä vaiheessa järjestelmän on syytä ottaa talteen käsitteen päätermi (skos:prefLabel) kaikilla kolmella YSOn tukemalla kielellä. Termien lisäksi kuvailutietueeseen on tärkeää päivittää myös käsitteen URI (yksilöllinen tunniste). Tämän tunnisteen avulla käsitteen tiedot voidaan myöhemmin tarkistaa mahdollisten muutosten varalta.

Toteutus Finto-rajapinnan kautta:

Käyttäjän syötettyä hakusanan hakulaatikkoon tehdään rajapinnan search-metodiin kutsu:

http://api.finto.fi/rest/v1/yso/search?query=kissa*&lang=fi

Jonka vastauksista näytetään hänelle lista mahdollisista käsitteistä.

Kun hän valitsee listasta käsitteen kissaeläimet tallennetaan käsitteen URI järjestelmään ja tehdään sen jälkeen kutsu rajapinnan data-metodille:

http://api.finto.fi/rest/v1/yso/data?uri=http://www.yso.fi/onto/yso/p864

Tämän kutsun vastauksesta poimitaan järjestelmästän tarpeista riippuen sopivat kentät eli vähintään käytettävä termi (skos:prefLabel) kolmella eri kielellä. Nämä tiedot talletetaan myös kuvailujärjestelmään siten, että kuvailun kohde on mahdollista löytää riippumatta siitä minkä kieliseen termiin tiedonhakijan termihaku kohdistuu.

Voit rajoittaa rajapinnan palauttamat käsitteet esimerkiksi skos:Concepteihin ja individualConcepteihin, jolloin saat vain kuvailussa sallitut käsitteet, etkä esimerkiksi ryhmiä.

http://api.finto.fi/rest/v1/yso/search?query=*filosofia&lang=fi&type=skos:Concept

Toteutus tuomalla koko sanasto ohjelmistoon:

Vaiheet ovat käytännössä identtiset, mutta vastuu sanastotiedon hyödyntämisestä on järjestelmän kehittäjällä. Järjestelmän tulee mielellään lukea termit suoraan RDF-datasta, mutta vähintään talteen on otettava URIt, käsitteen käytettävät termit (prefLabelit) eri kielillä ja mahdollisesti myös ohjaustermit (altLabelit). Nämä on talletettava järjestelmässä siten, että mahdolliset muutokset termeihin tai muihin käsitteen ominaisuuksiin voidaan päivittää helposti. Huomioitavaa on myös, että mahdolliset muutokset käsitteiden termeihin on vietävä myös järjestelmän kuvailutietoihin.

Finton sanastojen etusivuilla (tässä YSO) on alalaidassa latauslinkit joista koko sanaston voi ladata joko RDF/XML tai TURTLE -serialisoituna. Näiden käsittelyyn kannattaa käyttää jotain valmista RDF-kirjastoa. Esimerkkeinä mainittakoon EasyRdf PHPlle, RDFLib Pythonille ja Apache Jena Javalle.

Toteutuksessa huomioitavat erityistapaukset

Joissakin tilanteissa käsite voidaan korvata toisella käsitteellä. Korvatut käsitteet eivät näy hakutuloksissa, mutta kuvailutietueisiin niitä on saattanut jäädä ajalta ennen deprekointia. Näin on käynyt esimerkiksi YSOn (Yleinen suomalainen ontologia) käsitteelle tunteminen joka on korvatttu käsitteellä tunteet. Rajapinnassa tämä voidaan huomata ominaisuudesta (owl:deprecated true), käsitteen tyypistä (rdf:type skosext:DeprecatedConcept) ja suhteesta (yso:p307 dc:isReplacedBy p3485). Kun järjestelmä huomaa käytetyn käsitteen deprekoidun, tulee sen vaihtaa kuvailutietuiden tunteminen-käsitteen viittaukset tunteet-käsitteeseen.

http://api.finto.fi/rest/v1/yso/data?uri=http://www.yso.fi/onto/yso/p307

Hakuesimerkki Fintoa hyödyntävästä järjestelmästä

Jatkamme edellisen esimerkin järjestelmän käyttöä. Nyt kuitenkin vuorossa on tiedonhakija joka etsii järjestelmästä aineistoa. Käyttäjä tekee järjestelmään haun: kattdjur. Vaikka järjestelmän kuvailutieto syötettiin edellisessä esimerkissä suomen kielellä, on teos kuitenkin löydettävillä myös ruotsinkielisellä termillä YSOn kolmikielisyyden ansiosta.