I SKYRIUS
BENDROSIOS NUOSTATOS
1. Duomenų teikimo formatų ir standartų rekomendacijose (toliau – Rekomendacijos) nustatomi duomenų ir duomenų teikimo sąsajų formatai, standartai ir jų taikymas steigiant, kuriant ir (arba) tvarkant valstybės informacines sistemas ir registrus (toliau – Ištekliai). Rekomendacijos skirtos plėtoti efektyvią valstybės duomenų mainų ekosistemą ir minimizuoti išlaidas įgyvendinant Išteklių sąveiką per atvirus duomenų formatus.
2. Rekomendacijos parengtos vadovaujantis Lietuvos Respublikos valstybės informacinių išteklių valdymo įstatymu (toliau – Informacinių išteklių įstatymas), Lietuvos Respublikos teisės gauti informaciją ir duomenų pakartotinio naudojimo įstatymu (toliau – Teisės gauti informaciją įstatymas), Valstybės informacinių sistemų gyvavimo ciklo valdymo metodika ir kitais teisės aktais.
3. Rekomendacijos taikomos institucijoms, valdančioms ir (arba) tvarkančioms Informacinių išteklių įstatymo 1 straipsnio trečiojoje dalyje nurodytus valstybės registrus (kadastrus), žinybinius registrus, valstybės informacines sistemas ir kitas informacines sistemas, skelbiant ir teikiant duomenis pagal Teisės gauti informaciją įstatymo nuostatas.
4. Rekomendacijos skirtos informacinių sistemų ir registrų kūrimo, eksploatavimo bei modernizavimo stadijoms.
5. Pagrindinės rekomendacijose vartojamos sąvokos:
5.1. Duomenų teikimo sąsaja – Ištekliaus aplikacijų programavimo sąsaja (angl. Application Programming Interface, toliau – API), paremta standartiniais protokolais ir skirta automatizuotam duomenų nuskaitymui ir (arba) keitimui siekiant užtikrinti tiesioginę ir betarpišką Išteklių integraciją.
5.2. Universalioji duomenų teikimo sąsaja (toliau – UDTS) – universali duomenų teikimo sąsaja, suteikianti prieigą prie duomenų iki pirmo poreikio ir atitinkanti visus Rekomendacijų IV skyriuje išdėstytus reikalavimus.
5.3. UDTS specifikacija – struktūrizuotas (mašininiam skaitymui skirtas) dokumentas, aprašantis UDTS struktūrą, logiką, semantiką bei kitus aspektus, reikalingus siekiant visavertiškai pasinaudoti sąsaja.
6. Kitos Rekomendacijose vartojamos sąvokos atitinka Informacinių išteklių įstatyme, Teisės gauti informaciją įstatyme ir kituose teisės aktuose apibrėžtas sąvokas.
II SKYRIUS
DUOMENŲ TEIKIMO REŽIMAI IR BŪDAI
7. Duomenys pirminiam ir (arba) pakartotiniam naudojimui gali būti teikiami šiais režimais:
7.1. sinchroniniu – duomenų užklausimo metu nedelsiant prasideda duomenų gavėjo pateiktos užklausos parametrų apdorojimas, kuriam pasibaigus yra suformuojamas atsakymas ir iš karto pateikiamas duomenų gavėjui;
7.2. asinchroniniu užklausos/atsakymo – duomenų užklausimo metu duomenų gavėjo pateikti užklausos parametrai perduodami apdorojimui (arba talpinami į eilę vėlesniam apdorojimui), o duomenų gavėjui pateikiamas unikalus užklausos identifikatorius ar kiti atributai, nurodantys ar užklausa priimta sėkmingai bei atributai, kuriais remiantis vėliau duomenų gavėjui bus pateiktas suformuotas atsakymas;
7.3. asinchronine prenumerata – duomenys gavėjui teikiami periodiškai arba įvykus duomenų pasikeitimams.
8. Duomenys gali būti teikiami šiais būdais:
8.1. leidžiamosios kreipties būdu – duomenys duomenų gavėjui teikiami internetu ar kitais elektroninių ryšių tinklais pagal konkrečias užklausas, naudojant apibrėžtą duomenų teikimo sąsają;
8.2. paketiniu duomenų teikimo būdu – duomenų gavėjas sutartyse nustatytomis sąlygomis gauna didelės apimties duomenis, pavyzdžiui, momentines kopijas (angl. snapshot);
8.3. interaktyviuoju duomenų teikimo būdu – duomenų gavėjas duomenis gauna naudodamasis specialiomis naudotojo aplinkomis prieinamomis per interneto naršyklę;
8.4. viešai internete paskelbta duomenų rinkmena, kuri gali būti perduodama gavėjui interneto naršyklės priemonėmis;
8.5. kitais elektroniniais informacijos perdavimo būdais, pavyzdžiui, elektroniniu paštu, FTP, SFTP, SCP;
8.6. mišriuoju būdu – užklausos ir duomenys pateikiami skirtingais Rekomendacijų 8.1–8.5 papunkčiuose nurodytais būdais.
9. Duomenų teikimo sąsajos gali būti:
9.1. universalios – įgyvendina įvairius poreikius, skirtos vienam arba daugiau duomenų gavėjų, yra sukuriamos sistemos kūrimo metu, dar nesant konkretiems duomenų gavimo poreikiams.
9.2. specifinės – skirtos konkrečiam duomenų gavėjui, skirtos specifiniam duomenų teikimo scenarijui, gali būti optimizuojamos greitaveikai, pralaidumui, saugumui.
III SKYRIUS
DUOMENŲ TEIKIMO FORMATAI IR STANDARTAI
10. Duomenims teikti leidžiamosios kreipties būdu rekomenduojama naudoti UDTS.
11. Jeigu dėl technologinių ir (arba) ekonominių priežasčių neįmanoma naudoti UDTS, duomenims teikti gali būti naudojami alternatyvūs metodai, pavyzdžiui:
11.1. REST/JSON, SOAP, REST/XML, gRPC, GraphQL;
11.2. tiesioginės duomenų bazių sąsajos (angl. DB Link, Foreign Data Wrapper);
11.3. pranešimų eilės (angl. message queue);
11.4. standartinės, OGC standartus atitinkančios erdvinių duomenų teikimo sąsajos (WMS, WFS, WCS, WMTS, WPS, WCPS);
11.5. industrijos standartus atitinkančios erdvinių duomenų teikimo sąsajos, pvz. GeoJSON, ESRI GeoServices REST.
12. Duomenims teikti paketiniu duomenų teikimo būdu rekomenduojami šie duomenų teikimo formatai ir standartai:
12.1. perduodamų duomenų paketas parengiamas struktūrizuotu, mašininiu būdu skaitomu formatu – JSON, XML ar kitais formatais, taip pat ir JSON Schema arba XSD schemomis, užtikrinančiais duomenų atitikimą nustatytai struktūrai;
12.2. tais atvejais, kai struktūrizuotas duomenų paketo parengimas yra technologiškai ar ekonomiškai nenaudingas, gali būti naudojami specializuoti paketiniai duomenų mainai (pvz. SQL, CSV failai);
12.3. perduodamų duomenų paketas gali būti rengiamas kaip pilna perduodamų duomenų kopija arba kaip pokyčiai, įvykę po paskutinio duomenų perdavimo. Perduodamame pakete turi būti pakankamai duomenų, kad duomenų gavėjas galėtų atkurti integralią gaunamų duomenų kopiją.
13. Nepriklausomai nuo teikimo būdo, duomenims teikti rekomenduojami šie duomenų teikimo formatai ir standartai:
13.1. tekstinei informacijai:
13.1.1. text/plain – paprastam tekstui;
13.1.2. text/html – hipertekstui;
13.1.3. CSV, TSV, JSON – struktūrizuotiems duomenims;
13.1.4. visais atvejais rekomenduojama naudoti UTF-8 (little endian) koduotę be baitų tvarkos žymės (angl. Byte Order Mark).
13.2. dokumentams :
13.2.1. Lietuvos vyriausiojo archyvaro patvirtinti elektroninių dokumentų formatai – oficialiesiems elektroniniams dokumentams;
13.2.2. PDF (ISO 32000-1) – tekstui ir (arba) grafikai;
13.2.3. XML 1.1 (kartu pateikiant atvaizdavimo taisykles, pavyzdžiui, XSL transformavimo aprašą) – struktūrizuotam dokumentui;
13.2.4. EPUB – suglaudintų failų talpyklos formatas (toliau – konteinerio formatas) skirtas elektroninėms knygoms;
13.3. grafikai:
13.3.1. JPEG (ISO/IEC 10918) arba PNG (ISO/IEC 15948) – statiniam vaizdui;
13.3.2. TIFF (ISO/IEC 12639) – statiniam vaizdui;
13.3.3. GeoTIFF – georeferenciniam rastriniam vaizdui;
13.3.4. CGM (ISO/IEC 8632) – georeferenciniam vektoriniui vaizdui;
13.3.5. DICOM – medicininiams vaizdams;
13.4. garsui:
13.4.1. MP3 arba AAC – su kokybės praradimu;
13.4.2. FLAC arba WAV – be kokybės praradimo;
13.5. vaizdo ir garso įrašams:
13.5.1. MPEG-2 (ISO/IEC 13818) – nedidelės skiriamosios gebos;
13.5.2. WebM arba MPEG-4 (ISO/IEC 14496) – didelės skiriamosios gebos;
13.6. ZIP (ISO/IEC 21320-1) – įvairių formatų duomenų suglaudinimui;
13.7. erdviniams duomenims:
IV SKYRIUS
REIKALAVIMAI UNIVERSALIAJAI DUOMENŲ TEIKIMO SĄSAJAI
14. Kuriant arba modernizuojant Išteklius, rekomenduojama sprendimo architektūrą grįsti „pirmiausia API“ (angl. API-first) principu, kuris apibrėžia du sluoksnius: aplikacijų programavimo sąsajos (angl. backend) bei naudotojo sąsajos (naršyklės kliento, programėlių ar kt.) (angl. frontend). Rekomenduojama naudoti UDTS kaip pagrindinę Ištekliaus aplikacijų programavimo sąsają, o naudotojo sąsają laikyti su kitais Ištekliais lygiaverčiu duomenų gavėju.
15. UDTS tikslai yra:
15.1. įgalinti duomenų mainus ateities integraciniams poreikiams dar nesant konkretaus duomenų gavėjo, tačiau iš anksto pateikiant universalią programavimo sąsają, įgalinančią tokius duomenų mainus;
15.2. skatinti Išteklių informacinės struktūros skaidrumą, moduliarumą, išplečiamumą, pakeičiamumą pereinant nuo specifinių prie universalių duomenų teikimo sąsajų;
15.3. palengvinti Išteklių duomenų modelio prieinamumą, suprantamumą;
15.4. sudaryti prielaidas efektyviam duomenų mainų centralizavimui.
16. UDTS turi būti paremta REST/JSON standartu. Rekomenduojama remtis JSON-API standartu (https://jsonapi.org/):
16.1. objektams pateikti unikalius identifikatorius ir tipo atributus (JSON-API „id“ ir „type“ laukai);
16.2. esant numatomam poreikiui – pateikti paskutinio pokyčio datą ir laiką arba kitą identifikatorių, leidžiantį inkrementiškai gauti naujus duomenis ir užtikrinti korektiškas duomenų keitimo operacijas.
17. UDTS specifikacija turi būti parengta remiantis OpenAPI 3.0 arba aukštesnės versijos standartu. UDTS specifikacija turi būti pateikta JSON arba YAML formatu ir parengta publikavimui Valstybės informacinių išteklių sąveikumo platformos duomenų teikimo sąsajų kataloge.
18. UDTS specifikacijoje turi būti aprašomas teikiamų duomenų formatas, nustatant teikiamų duomenų laukų tipus, reikšmių patikros taisykles, statines klasifikatorių reikšmes ir kitus tipus. Taip pat, turi būti aprašomi duomenų semantikos, visumos, kokybės, esamų arba potencialių duomenų klaidų, netikslumų arba trūkumo, istorinių duomenų netikslumo arba trūkumo, realaus laiko delsos, klaidų kodų, versijavimo, teisėtų duomenų panaudojimo būdų bei kiti aspektai, kurie yra svarbūs norint korektiškai panaudoti teikiamus duomenis.
19. Reikalavimai UDTS turiniui:
19.1. UDTS, vadovaujantis principu „iki pirmo poreikio“, turi sudaryti galimybę iš Ištekliaus gauti visus jame tvarkomus duomenis, įskaitant:
19.1.1. pirminius duomenis;
19.1.2. išvestinius duomenis, kuriems egzistuoja vidinis arba yra numanomas išorinis poreikis;
19.1.3. Ištekliaus nuostatų informaciniame modelyje aprašytus duomenis;
19.1.4. duomenų bazės metaduomenis (schemą);
19.1.5. duomenis, kurie yra atvaizduojami Ištekliaus naudotojo sąsajoje, jei tokia yra;
19.2. į reikalavimus, nurodytus 19.1 punkte, neįtraukiami vidiniai arba tarpiniai duomenys, tokie kaip:
19.2.1. podėlis (angl. cache);
19.2.2. iš kitų Išteklių gaunami duomenys, jei juos iš minimų Išteklių galima gauti tiesiogiai;
19.2.3. Ištekliaus vidiniai administraciniai arba operatyviniai duomenys, pavyzdžiui, vidinių naudotojų rolės, veiksmų žurnalas, sisteminė konfigūracija, sertifikatai ir pan.;
19.2.4. duomenys, kurių dėl technologinių arba teisinių priežasčių neįmanoma pateikti iki pirmo poreikio, pavyzdžiui, nesamos standartinės programinės įrangos (angl. Commercial Off the Shelf) duomenų teikimo sąsajos, specializuota duomenų schema, didelė duomenų failų apimtis, istorinių duomenų archyvavimas atskiroje saugykloje ir pan.;
19.3. UDTS turi suteikti prieigą prie svarbiausių rašymo, keitimo ir trynimo veiksmų, kurie yra prieinami pagrindinėje Ištekliaus naudotojo sąsajoje (jei tokia yra), arba integracinių taškų, kuriems yra numanomas poreikis. Pavyzdžiui, dokumentų valdymo sistemoje – „sukurti dokumentą“, „pakeisti dokumento statusą“; užduočių valdymo sistemoje – „sukurti užduotį“; leidimų išdavimo sistemoje – „išduoti leidimą“;
19.4. perduodant koduojamus duomenis turi būti perduodami tiek tokių duomenų kodai, tiek jų reikšmė, o taip pat – turi būti atskirai pateikiamas reikšmių klasifikatorius;
19.5. visų klasifikuojamų ar koduojamų duomenų reikšmėms nustatyti teikiami ir atnaujinami reikšmių klasifikatoriai, kuriuose reikšmės pateikiamos bent dviem – lietuvių ir anglų – kalbomis;
19.6. įvykus klaidai turi būti grąžinamas struktūrizuotas pranešimas, nurodantis klaidos kodą, tipą, kitus techninius atributus, bei atskiru atributu perduodamas žmogui suprantamas klaidos aprašymas – klaidos tekstas, klaidos teksto pateikimo kalba. Klaidos tekstas turi būti grąžinamas bent dviem – lietuvių ir anglų – kalbomis. Kiek įmanoma, turi būti stengiamasi panaudoti standartinius HTTP protokolo klaidų kodus.
20. UDTS turi pateikti išorinio testavimo aplinką (angl. production sandbox) ir suteikti potencialiems duomenų gavėjams galimybę ja laisvai naudotis.
21. Vystant Išteklių ir jo duomenų modelį, atitinkami pokyčiai nuolat turi būti diegiami ir UDTS. Keičiantis Ištekliaus duomenų modeliui ir (arba) semantikai turi būti maksimaliai stengiamasi išlaikyti esamos UDTS versijos veikimą (angl. backwards compatibility), o nepavykus to padaryti, nesuderinami pakeitimai turi būti publikuojami nauja, aukštesne versija. Išimtis taikoma atvejams, kai dėl teisės aktų ar veiklos pokyčių iš esmės keičiasi duomenų modelis ir nebėra galimybės teikti duomenis senuoju formatu. Tokiais atvejais rekomenduojama iš anksto informuoti sąsajos naudotojus (duomenų gavėjus ir Valstybės informacinių išteklių sąveikumo platformos tvarkytoją), kad būtų laiku pasirengta pokyčiams ir išvengta integracinių sutrikimų.
22. UDTS keliami pasiekiamumo, korektiškumo, greitaveikos ir kiti nefunkciniai reikalavimai, įvardinti duomenų teikimo paslaugos susitarime (angl. Service-Level Agreement), turi būti ne žemesni kaip pagrindinės Ištekliaus naudotojo sąsajos (jei tokia yra) veikimo reikalavimai.
23. UDTS turi būti paruošta naudojimui taip, kad iškilus naujiems poreikiams nereikėtų atlikti užsakomųjų ar kitų sistemos modifikavimo darbų.
24. UDTS turi būti pritaikyta tiek tiesioginiam kreipimuisi internetu arba kitais elektroninių ryšių kanalais, tiek netiesioginiam kreipimuisi per Valstybės informacinių išteklių sąveikumo platformos duomenų mainų paslauga (toliau – DMP).
25. UDTS turi numatyti galimybę galutinio naudotojo (asmens arba sistemos) autentifikaciją (atpažintį) bei autorizaciją (teisės gauti konkrečius duomenis ar atlikti veiksmą patikrinimą) vykdyti DMP bent vienu iš šių būdų:
25.1. suteikiant galimybę DMP gauti neribotą prieigą prie UDTS su bendru aplikacijos arba tinklo lygio saugumo mechanizmu (pvz., mutual TLS, VPN). Šiuo atveju DMP užtikrina, kad duomenys galutinį duomenų gavėją pasiekia saugiai ir teisėtai;
25.2. valdant duomenų prieigos teises remiantis OAuth 2.0, OpenID Connect, JSON Web Tokens (JWT) standartais. Šiuo atveju UDTS turi būti suintegruota su DMP autorizacijos serveriu bei pasikliauti iš autorizacijos serverio gaunamais naudotojo atributais (identifikaciniais duomenimis, leidimais (scopes), grupėmis ir pan.).
26. Projektuojant UDTS, rekomenduojama remtis Informacinės visuomenės plėtros komiteto internetinėje svetainėje pateikiamais UDTS specifikacijų pavyzdžiais: https://ivpk.lrv.lt/lt/veiklos-sritys-1/duomenu-teikimo-formatai-ir-standartai.
V SKYRIUS
BAIGIAMOSIOS NUOSTATOS
27. Jei duomenų gavėjas dėl technologinių ar kitokių objektyvių aplinkybių negali gauti duomenis naudojant UDTS, susitarus su duomenų teikėju galima naudoti kitokius duomenų teikimo formatus ir standartus, tačiau toks susitarimas turi būti suderintas su Informacinės visuomenės plėtros komitetu, o sukurto sprendimo specifikacija pateikta publikavimui Valstybės informacinių išteklių sąveikumo platformos duomenų teikimo sąsajų kataloge. Duomenų gavėjo prašymu sukurtas duomenų teikimo sprendimo įdiegimas neatleidžia duomenų teikėjo nuo įpareigojimo naudoti UDTS teikiant duomenis kitiems duomenų gavėjams.
28. Rekomendacijos turi būti peržiūrimos ir prireikus atnaujinamos ne rečiau kaip kartą per metus.
29. Pasiūlymai dėl Rekomendacijų tobulinimo gali būti teikiami el. paštu (info@ivpk.lt), internetu (https://ivpk.lrv.lt/lt/veiklos-sritys-1/duomenu-teikimo-formatai-ir-standartai) ir kitomis priemonėmis.
