Commit 82d753a7 authored by Mantas Zimnickas's avatar Mantas Zimnickas

Update docs

parent 483d8a24
Pipeline #115700448 passed with stage
in 2 minutes and 47 seconds
......@@ -8,91 +8,165 @@
Atvirų duomenų manifestas
#########################
Kas yra manifestas?
===================
Atvirų duomenų manifestas yra visų Lietuvos duomenų rodyklė. Kitais žodžiais
tai yra metaduomenys (duomenys apie duomenis).
:term:`Manifestas` yra YAML failų rinkinys, kuriuose aprašomos duomenų struktūros.
Manifestas yra vidinis komunikacijos protokolas, skirtas susikalbėti duomenų
tiekėjams, duomenų naudotojams ir centriniam atvirų duomenų portalui.
Pavyzdžiui, jei visi Lietuvos duomenys būtų sukrauti į didelę spintą ir
didžioji dalis spintos turinio būtų skolinta iš kitų spintų, tai atvirų duomenų
manifestas būtų lapelis užkabintas ant spintos durų, kuriame surašyta kas, kur,
kada, iš ko pasiskolino, kada grąžinti ir pan.
:term:`Manifestas` turi pakankamai daug :term:`metaduomenų <metaduomenys>`
(metaduomenys yra duomenys apie duomenis) apie duomenų rinkinį jį sudarančias
duomenų struktūras. Tai leidžia automatizuoti duomenų importavimą į atvirų
duomenų portalą, duomenų kokybės patikrinimą, duomenų eksportavimą į kitus
formatus ir pan.
Metaduomenys leidžia automatizuoti duomenų valdymą įdarbinant robotus, kurie
automatizuotų didelę dalį veiklų susijusių su duomenų valdymu.
Pats savaime Manifestas nėra dar vienas standartas, tai yra vidinei
komunikacijai skirtas protokolas, kurio pagrindu sudaroma galimybė
tranformatuoti duomenis į įvairius formatus. Pats Manifestas yra aktualus tik
tiekėjams norintiems atverti duomenis.
.. image:: static/spinta.png
Į šio projekto apimtį įeina ne tik informacija kaip aprašyti metaduomenis, bet
teikiami įrankiai, kurie metaduomenų pagrindu automatizuoja daugelį duomenų
atvėrimo ir pateikimo naudojimui veiklų.
Kaip tai veikia?
================
Manifesto (lapelis ant spintos) sudarymo procesas vadinamas duomenų
`inventorizacija <inventorying>`_. Tarkime, kaip pavyzdį, galime panagrinėti
išgalvotos įstaigos „Duomenų centras“ sutrumpintai vadinamos DC duomenis. DC
duomenų bazėje yra lentelė techniniu pavadinimu `COUNTRIES`, lentelės
turinys atrodo taip:
Kad geriau suprasti, kaip visa tai veikia, pabandykime aprašyti CSV failo
duomenų struktūrą. Tarkime turime tokį CSV faile, kuris pasiekiamas adresu
`https://example.com/countries.csv`, šio CSV failo turinys atrodo taip::
======= ======== ===========
COUNTRIES
------------------------------
id code country
======= ======== ===========
1 lt Lietuva
2 lv Latvija
3 ee Estija
======= ======== ===========
code,country
lt,Lietuva
lv,Latvija
ee,Estija
Įstaiga „Duomenų centras“ nori atverti duomenis. Pirmas žingsnis būtų duomenų
inventorizacija. Duomenų inventorizacijos metu sudaromi įstaigoje esančių
duomenų laukų sąrašai, kurie atrodo taip:
Šiam CSV failui Manifesto duomenų struktūros aprašas atrodytų taip:
================ ============ ======== ===== =============== ==========
Atvirų duomenų manifestas Duomenų centro duomenų bazė
----------------------------------------------- ---------------------------
dataset model property title table column
================ ============ ======== ===== =============== ==========
gov/dc/countries COUNTRIES _id \ COUNTRIES id
gov/dc/countries COUNTRIES code \ COUNTRIES code
gov/dc/countries COUNTRIES country \ COUNTRIES country
================ ============ ======== ===== =============== ==========
Reali inventorizacijos lentelė yra kiek sudėtingesnė, šiame pavyzdyje yra
mažiau stulpelių dėl paprastumo.
Tokią pirminę inventorizacijos lentelę daugeliu atveju galima sugeneruoti
automatiškai iš duomenų šaltinio.
Deja ne viską galima automatizuoti, toliau prasideda rankinis darbas su
lentele:
- pažymimi laukai, kurie neturi būti atverti
- pateikiami laukų pavadinimai ir aprašymai, kad būtų aišku kaip juos naudoti
- pažymima, kuriuose laukuose pateikta asmeninė informacija
- verčiami lentelių ir laukų pavadinimai, į vieningą manifesto žodyną
Galiausiai gauname lentelę, kuri atrodo taip:
================ ======= ======== ===== ============ =======
dataset model property title table column
================ ======= ======== ===== ============ =======
gov/dc/countries country _id ID COUNTRIES id
gov/dc/countries country code Kodas COUNTRIES code
gov/dc/countries country name Šalis COUNTRIES country
================ ======= ======== ===== ============ =======
Manifestas
----------
Inventorizacijos lentelė yra tik patogesnė priemonė metaduomenų valdymui.
Tačiau, pagrindinis metaduomenų formatas yra manifesto YAML failai.
Darbas su inventorizacijos lentele yra patogus ir paprastas, tačiau deja kai
kurios sudėtingesnės automatizavimo veiklos reikalauja žymiai daugiau
metaduomenų. O turėti didelį kiekį metaduomenų vienoje lentelėje yra tiesiog
nepraktiška. Todėl paprasti dalykai ir pirminė inventorizacija daroma
lentelėse, sudėtingesni dalykai ir pilnas duomenų aprašas yra YAML failuose.
Visi įrankiai dirba su YAML failais. YAML failus galima nuskaityti mašininiu
būdu, tačiau YAML sintaksė yra lengvai suprantama ir žmonėms. Štai kaip
atrodytų mūsų inventorizacijos lentelė YAML formatu:
.. code-block:: yaml
name: pavyzdziai/salys
type: dataset
name: gov/dc/countries
resources:
countries:
type: csv
type: sql
source: postgresql://user:[email protected]/dbname
objects:
geografija/salis:
source: https://example.com/countries.csv
country:
source: COUNTRIES
properties:
id:
_id:
type: pk
source: code
kodas:
source: id
code:
type: string
source: code
pavadinimas:
name:
type: string
source: country
Šio duomenų aprašo dėka galima automatiškai importuoti duomenis iš įvairių
:ref:`šaltinių <sources>` vėliau juos eksportuoti įvairiais formatais.
======== ======= ===========
id kodas pavadinimas
======== ======= ===========
552c4c24 lt Lietuva
b5dcb868 lv Latvija
68de1c04 ee Estija
======== ======= ===========
Tokie duomenų aprašai leidžia pateikti daug daugiau informacijos apie duomenų
šaltinį, tačiau failo formatas yra kiek sudėtingesnis, nei inventorizacijos
lentelės. Todėl pirminė inventorizacija atliekama lentelės pagalba, o
išplėstinė, YAML failų pagalba.
Tarpinė duomenų saugykla
------------------------
Funkcijos
=========
Pasidarius tokią inventorizaciją, automatinėmis priemonėmis, duomenys
kopijuojami iš pirminio duomenų šaltinio į tarpinę duomenų saugyklą. Tarpinė
duomenų saugykla nėra prieinama iš išorės ir turėtų veikti įstaigos
atveriančios duomenis infrastruktūroje.
Toks duomenų struktūros aprašas turi pakankamai informacijos, kad galėtume
automatiškai atlikti dalykus išvardintus žemiau.
Tarpinėje duomenų saugykloje atliekami visi nuasmeninimo, transformacijos,
vertimo į manifesto žodyną ir kiti darbai. Kad neatskleisti jautrios
informacijos, visi šie darbai turi būti atliekami tarpinėje saugykloje, kad
duomenys, kol dar nėra iki galo paruošti, nepaliktų įstaigos infrastruktūros
ribų.
- Importuoti duomenis iš įvairių :ref:`šaltinių <sources>`.
Galiausiai ištestuoti ir patvirtinti atvėrimui duomenų rinkiniai keliauja į
viešąją duomenų saugyklą, kuri yra pasiekiama adresu https://atviriduomenys.lt.
- Patikrinti šaltinio duomenų kokybę.
Viešoji duomenų saugykla leidžia duomenis atsisiųsti įvairiais formatais,
suteikia vieningą API duomenų integracijai ir suteikia įvairias priemones
darbui su duomenimis. Duomenų naudotojai gali rašyti užklausas, jungti duomenis
tarpusavyje, sekti pasikeitimus duomenyse, matyti kokios klaidos įvyko
apdorojant duomenis ir pan.
- Patikrinti ar duomenų aprašas tikrai atitinka duomenų šaltinį.
Tiek vidinėje saugykloje, tiek viešojoje saugykloje, pagrindinis integracijos
taškas yra manifesto YAML failai. Atvėrus duomenis iš tarpinės duomenų
saugyklos, vidiniai YAML failai transformuojami į viešai prieigai tinkantį
pavidalą, kur yra paslėpti vidinių duomenų bazių pavadinimai, transformacijų
aprašai ir pan. Šis viešasis manifesto variantas skelbiamas
`atviriduomenys/manifest`_ kodo repozitorijoje.
- Eksportuoti duomenis įvairiais kitais formatais.
.. _atviriduomenys/manifest: https://gitlab.com/atviriduomenys/manifest
- Susieti įvairių šaltinių duomenis naudojant vieningą :ref:`žodyną <vocab>`.
Duomenų naudotojai, pastebėję klaidas, gali užregistruoti pranešimą `užduočių
valdymo sistemoje`__. Užduočių valdymo sistema yra atvira ir integruota su kodo
repozitorija. Viešoji manifesto dalis yra atviro kodo, todėl visi gali
įsitraukti ir tiksliai matyti kas vyksta.
- Valdyti duomenis naudojant :ref:`API <api>`.
.. __: https://gitlab.com/atviriduomenys/manifest/issues
- :ref:`Normalizuoti <norm>` denormalzuotas duomenų struktūras.
Paskutinis žingsnis - suformuotas duomenų rinkinys užregistruojamas atvirų
duomenų vitrinoje adresu https://data.gov.lt, kad duomenų naudotojai galėtų
rasti duomenis.
Turinys
......@@ -101,10 +175,12 @@ Turinys
.. toctree::
:maxdepth: 2
sources.rst
pk.rst
norm.rst
dependencies.rst
vocabulary.rst
api.rst
glossary.rst
inventorying
sources
pk
norm
dependencies
vocabulary
api
glossary
contributing
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment