Dimensijos

Dimensijos apibrėžia duomenų metaduomenų detalumo lygį. Stulpeliai dataset, resource, base, model ir property yra naudojami kaip DSA dimensijos. dataset yra aukščiausia dimensija, property žemiausia. dataset ir resource dimensijos atitinka DCAT žodyną ir užtikrina trečia duomenų brandos lygį, o žemiau esantys base, model ir property atitinka RDFS žodyną ir užtikrina penktą duomenų brandos lygį. Vienoje lentelės eilutėje gali būti užpildytas ne daugiau kaip vienas dimensijos stulpelis. Užpildytasis dimensijos stulpelis nustato visų kitų stulpelių prasmę.

id

d

r

b

m

property

title

1

datasets/gov/ivpk/adk

Atvirų duomenų katalogas

2

adk

Atvirų duomenų katalogo duomenų bazė

3

/dcat/dataset

Duomenų rinkinys

4

dataset

Duomenų rinkinys

5

title

Duomenų rinkinio pavadinimas

Pavyzdyje aukščiau, taupant vietą, dalies dimensijų pavadinimai sutrumpinti iki vienos raidės ir įtraukti ne visi stulpeliai, o tik id ir title metaduomenų stulpeliai. Pavyzdyje matome, kad vienoje eilutėje užpildytas tik vienas dimensijos stulpelis, o title stulpelio prasmė keičiasi priklausomai nuo dimensijos reikšmės. Toliau specifikacijoje konkrečios dimensijos stulpeliai įvardijami pateikiant tiek dimensijos, tiek metaduomens stulpelio pavadinimus, kad būtų aiškiau apie kurios dimensijos metaduomenį kalbama, pavyzdžiui model.title leidžia suprasti kad kalbama apie „Duomenų rinkinys“ reikšmę 4-oje eilutėje.

Be minėtų dimensijų stulpelių DSA lentelėje gali būti naudojami papildomos metaduomenų dimensijos, kai nurodoma type reikšmė ir nepateikiama nei viena dimensijos stulpelio reikšmė. Pavyzdžiui:

id

d

r

b

m

property

type

ref

uri

1

prefix

dcat

http://www.w3.org/ns/dcat#

Šiuo atveju prefix tampa dar viena dimensija, leidžianti pateikti metaduomenis apie naudojamų URI prefiksus. Analogiškai, kaip ir su kitomis dimensijomis, dimensijos ir metaduomens pavadinimus galima apjungti, pavyzdžiui prefix.ref apibūdina tik prefix dimensijai priklausančius ref stulpelius.

Dimensijos leidžia suskirstyti metaduomenis į hierarchinę struktūrą. Todėl DSA lentelės eilučių eiliškumas yra svarbus, kadangi žemiau esančios eilutės priklauso aukščiau esančiai dimensijai. Tas pats galioja ir pagalbinėms dimensijoms.

Nors lentelėje sudaro tik 15 stulpelių, tačiau pasitelkiant 5 pagrindinius dimensijas ir keletą papildomų dimensijų, atsiranda galimybė išsamiai aprašyti visą duomenų šaltinio struktūrą.

Duomenų rinkinys

DSA lentelėje duomenų rinkinys nurodomas tam, kad būtų išlaikomas ryšys tarp DSA ir ADK. Atliekant duomenų inventorizaciją, automatiškai generuota DSA lentelė turi būti suskirstoma į duomenų rinkinius. Tada priemonių pagalba automatiškai sukuriami pirminiai ADK metaduomenys apie duomenų rinkinius, kuriuos vėliau reikia papildyti rankiniu būdu prisijungus prie ADK. Automatizuota priemonė sukūrus duomenų rinkinių įrašus ADK, papildys DSA lentelę, į dataset.ref įrašant ADK sukurto duomenų rinkinio identifikatorių. Tokiu būdu, sekantį kartą vykdant sinchronizaciją, jei dataset.ref yra užpildytas, bus atnaujinami jau sukurti ADK duomenų rinkinių įrašai.

Į ADK turi būti publikuojami tik tie duomenų rinkiniai iš DSA, kurių dataset.access reikšmė yra public arba open.

dataset.source

Jei nenurodyta, naudoti https://data.gov.lt/ adresą.

Nenaudojama, jei dataset.type yra ns.

dataset.prepare

Nenaudojama.

dataset.type

Jei nenurodyta, naudoti ivpk reikšmę. type nurodo API formatą, kuriuo automatiškai pildomi duomenų rinkinių metaduomenys atvirų duomenų portale.

Galimos reikšmės:

ns

Atitinka vardų erdvę, kurioje pateikiami duomenų rinkiniai. Naudojamas tais atvejais, kai norima pateiki papildomus metaduomenis vardų erdvei, pavydžui pavadinimą ar parašymą.

ckan

Atitinka duomenų rinkinį iš CKAN duomenų katalogo.

ivpk

Atitinka duomenų rinkinį iš data.gov.lt duomenų katalogo.

dataset.ref

Duomenų rinkinio duomenų kataloge identifikatorius.

Nenaudojamas jei dataset.type yra ns.

dataset.level

Nenaudojamas.

dataset.access

Viso duomenų rinkinio ar vardų erdvės Prieigos lygiai. Paveldimas.

dataset.title

Duomenų rinkinio ar vardų erdvės pavadinimas.

dataset.description

Duomenų rinkinio ar vardų erdvės aprašymas.

Skaidymas į duomenų rinkinius turi būti atliekamas tokiu principu, kad visi tarpusavyje susiję modeliai patektų į vieną duomenų rinkinį. Teoriškai, absoliučiai visi modeliai gali būti susiję tarpusavyje, skaidymą reikėtų daryti pagal tematinį modelių tarpusavio ryšį, o ne pagal reliacinius ryšius.

Jei duomenys yra išskaidyti pagal laiką, vietove ar kitus kriterijus į skirtingus duomenų šaltinius, tokie duomenys turėtų būti apjungti į vieną modelį Modelio bazė pagalba ir turėtų priklausyti vienam duomenų rinkiniui. Tą pačią semantinę prasmę turintys duomenys neturėtų būti išskaidyti keliuose duomenų rinkiniuose.

Pavyzdys:

d

r

b

m

property

type

datasets/gov/ivpk

ns

Informacinės visuomenės plėtros komitetas

datasets/gov/ivpk/adp

ns

Lietuvos atvirų duomenų portalas

datasets/gov/ivpk/adp/catalog

Lietuvos atvirų duomenų katalogas

datasets/gov/ivpk/adp/store

Lietuvos atvirų duomenų saugykla

Šiame pavyzdyje apibrėžtos dvi vardų erdvės ir du rinkiniai.

Kiekviena organizacija turėtu deklaruoti tik savo vardų erdvės metaduomenis. Globalios vardų erdvės, tokios kaip datasets ir datasets/gov yra administruojamos vyriausiojo duomenų atvėrimo koordinatoriaus.

Duomenų šaltinis

ŠDSA atveju duomenų šaltinis bus vidinis duomenų bazių serveris, kažkoks vidinis katalogas kuriame yra lentelių failai ar koks nors vidinis API.

ADSA atveju, duomenų šaltinis gali būti nenurodytas, tai reiškia, kad duomenų rinkinio duomenys dar nėra publikuoti. Jei duomenys jau yra publikuoti, tada ADSA duomenų šaltinis turi rodyti į publikuotus atvertus duomenis, tai gali būti nuorodos į CSV failus, į viešą JSON API ir pan.

Duomenų šaltinio įrašas taip pat naudojamas tam, kad automatiškai atnaujinti ADK esančius duomenų rinkinius, patelkiant konkrečias nuorodas į konkrečius duomenų failus. Analogiškai kaip ir Duomenų rinkinys atveju, resource.ref stulpelyje nurodomas duomenų šaltinio identifikatorius iš ADK.

resource.type

Duomenų šaltinio tipas. Galimos reikšmės:

sql

Reliacinės duomenų bazės

csv

CSV lentelės

tsv

TSV lentelės

json

JSON resursai

jsonl

JSON lines resursai

geojson

GeoJSON failai

xml

XML resursai

html

HTML puslapiai

xlsx

Excel lentelės (naujasis OOXML formatas)

xls

Excel lentelės (senasis formatas)

ods

ODT skaičiuoklės formatas

zip

ZIP failų archyvas.

resource.source

Priklauso nuo resource.source. Žiūrėti Duomenų šaltiniai.

resource.ref

Resurso kodinis pavadinimas, kuris yra apibrėžtas atskirai duomenų struktūros apraše, ar konfigūracijos failuose.

Kai vienas resursas nurodo kitą, tuomet aprašomas resursas išplečia kitą resursą į kurį rodo arba naudoja kitą resursą, kaip konteinerį, kuriame saugomi duomenys.

Išplėtimo atveju, galima pateikti tam tikro resurso konfidencialius duomenis, tokius, kaip slaptažodis, atskirai nuo duomenų struktūros aprašo, konfigūracijos failuose, o duomenų struktūros apraše išplėsti resursą, pateikiant ne konfidencialius duomenis.

Tokiais atvejais, kaip duomenų failai saugomi ZIP archyvuose arba FTP serveryje, galima atskirai aprašyti ZIP ar FTP resursą, o po to, aprašant konkretų duomenų failo resursą, pateikti nuorodą, kuriame kitame resurse aprašomas failas yra.

resource.level

Duomenų šaltinio brandos lygis, vertinant tik pagal formatą, nežiūrint į šaltinyje esančių duomenų turinį.

resource.access

Viso duomenų šaltinio prieigos lygis. Paveldimas.

resource.title

Duomenų šaltinio pavadinimas.

resource.description

Duomenų šaltinio aprašymas.

Duomenų šaltinio resource.type reikšmė apibrėžia kokią ETL priemonę naudoti skaitant duomenis iš duomenų šaltinio. Automatizuota duomenų priemonė skirta įstaigos duomenų atvėrimui turėtų palaikyti tik tokius duomenų šaltinius, kurie naudojami įstaigos vidinėje infrastruktūroje.

Esant poreikiui gali būti įgyvendintas palaikymas naujiems duomenų šaltiniams.

Modelio bazė

Pastaba

Kol kas modelių apjungimas naudojant vieną bazę nėra įgyvendintas.

Modelio bazė naudojama kelių modelių (lentelių) susiejimui arba apjungimui. Kadangi įvairiuose duomenų šaltiniuose dažnai pasitaiko duomenų, kuriuose saugomos tą pačią semantinę prasmę turinčios lentelės, base stulpelyje galima nurodyti kaip skirtingos lentelės siejasi tarpusavyje.

base.type stulpelyje nurodoma kokiu būdu lentelės yra susiję. ETL priemonė vadovaujantis base informacija duomenis automatiškai transformuoja ir sujungia kelias lenteles į vieną.

Modeliai ne tik susiejami semantiškai tarpusavyje, bet taip pat suliejami ir dviejų modelių duomenys naudojant laukų sąrašą nurodytą base.ref stulpelyje. base.ref stulpelyje nurodyti laukai naudojami norint unikaliai identifikuoti model lentelėje esančią eilutę, kuri atitinka base lentelėje esančią eilutę. Tai reiškia, kad modelis ir jo bazė turi vienodus identifikatorius.

Siejant model ir base duomenis tarpusavyje, model lentelė įgauna lygiai tokius pačius unikalius identifikatorius, kurie yra base lentelėje. Tai reiškia, kad model lentelėje negali būti duomenų, kurių nėra base lentelėje.

model.property laukams, kurie sutampa su base modelio laukais, nenurodomas property.type, tokiu būdu nurodoma, kad model.property turi tą pačią semantinę prasmę, kaip ir base, tačiau model gali turėti ir papildomų laukų, kurių nėra base modelyje, tokiu atveju property.type turi būti nurodomas.

Visi base.ref laukai turi būti aprašyti tiek base, tiek model modeliuose, tai reiškia, kad base.ref gali būti naudojami tik tiek laukai, kurie neturi tipo.

Jei base stulpelyje nurodoma / reikšmė, tai reiškia, kad model neturi bazės, arba modelio bazė yra panaikinama. / naudojamas tais atvejais, kai norima vieną ar kelis modelius prijungti prie vienos bazės, tačiau sekantys modeliai nebeturi priklausyti jokiai bazei.

Sinonimai

Tais atvejais, kai visi model laukai neturi property.type, tada toks modelis laikomas base sinonimu ir iš esmės saugomas tik identifikatorius.

Tačiau, jei bent vienas property.type yra nurodytas, tada modelis įgyja fizinę reprezentaciją ir turi vieną ar kelis savo laukus, kurių nėra base modelyje.

Kiekvieną kartą saugant duomenis per kitą modelį į bazę, bazės modelio istorijoje išsaugoma informacija iš kokio modelio atėjo duomenys.

Paveldimumas

model paveldi visus laukus, įskaitant ir tuos, kurie nėra nurodyti prie model laukų sąrašo. Tai reiškia, kad galima skaityti ir rašyti duomenis į base, per model. Jei skaitomas ar rašomas laukas, kurio nėra model laukų sąraše, tada to lauko duomenys sakomi iš arba rašomi į base modelį.

Visi modelio laukai, kurie neturi tipo, fiziškai yra priskiriami base modeliui.

Dubliavimas

Laukai pavadinimai modelyje, kurie turi tą pačią semantinę prasmę, kaip ir bazėje turi sutapti su pavadinimais nurodytais bazėje. Tačiau, jei yra nurodomas jų tipas, tada tie duomenys dubliuojami, laikant, kad duomenys skiriasi nuo bazės, nepaisant to, kad semantiškai jie yra vienodi.

Turint tokius dubliuojamus laukus su nurodytais tipais, jei norima pasiekti bazės lauką, galima naudoti _base.prop išraišką, kuri nurodo, kad norima pasiekti bazėje esančius duomenis, laukui tuo pačiu pavadinimu.

base.source

Nenaudojamas.

base.prepare

Išimtiniais atvejais, kai nėra galimybės lentelių susieti ar apjungti įprastiniais metodais, galima pasitelkti formules, kurių pagalba galima įgyvendinti nestandartinius lentelių apjungimo atvejus.

base.type

Nenaudojamas.

base.ref

model.property reikšmė, kurios pagalba model objektai siejami su base objektais. Jei susiejimas pagal vieną model property yra neįmanomas, galima nurodyti kelis model.property pavadinimus atskirtus kableliu.

Galima naudoti tik tuos model.property, kurie neturi nurodyto property.type, kas reiškia, kad toks pat laukas turi būti tiek base, tiek model laukų sąraše.

Tais atvejais, kai base.ref rodo į modelio lauką, kuris turi tipą, tada base.level negali būti didesnis nei 3, kadangi jei modelio laukas turi tipą, tai reiškia, kad jo duomenys nesutampa su bazės duomenimis ir todėl jungimas negali būti daromas.

base.level

Brandos lygis, nurodantis modelio susiejamumą su nurodytu baziniu modeliu. Plačiau žiūrėti Ryšiai tarp modelių | Brandos lygis.

Jei brandos lygis yra žemesnis nei 3, tada identifikatorių siejimas nėra atliekamas, tokiu būdu tiesiog nurodomas semantinis susiejimas metaduomenų, o ne duomenų lygmenyje.

base.access

Nenaudojamas.

Paaiškinimas, ką reiškia kiekviena savybė.

Pavyzdys be išorinio duomenų šaltinio:

d

r

b

m

property

type

ref

example

Location

name@lt

text

population

integer

Location

City

name@lt

population

Village

name@lt

population

region

ref

Location

/

Country

name@lt

population

Šiame pavyzdyje:

  • City ir Village priklauso vienai bazei Location.

  • Kadangi Location turi savybes name@lt ir population, tai City ir Village modeliuose tą pačią semantinę prasmę turinčios savybės turi turėti lygiai tokius pačius pavadinimus, o property.type turi būti tuščias. Kai property.type yra tuščias, tai reiškia, kad savybė ateina iš bazinio modelio.

  • Kadangi Village turi papildomą property su nurodytu property.type, tai reiškia, kad name ir population` priklauso bazei, tačiau region priklauso Village modeliui ir jo nėra bazėje.

  • Kadangi Country semantiškai nėra tas pats, kas Gyvenviete, nors ir turi tokias pačias savybes, atskiriame ją nuo Location bazės, priskirdami / bazei, kas reiškia, kas bazės nėra.

Pavyzdys su išoriniu duomenų šaltiniu:

d

r

b

m

property

type

ref

source

example

Location

id

id

integer

name@lt

text

population

integer

Location

name@lt

City

name@lt

CITY

name@lt

NAME

population

POPULATION

Village

name@lt

VILLAGE

name@lt

VILLAGE

population

POPULATION

region

ref

Location

REGION

Šiame pavyzdyje esminis skirtumas yra tas, kad nurodyta kaip daromas jungimas. City ir Village su Location jungiame per name@lt lauką.

Duomenų modelis

Duomenų modelis apibrėžia duomenų grupę turinčią tas pačias savybes. Skirtinguose duomenų šaltiniuose ir formatuose, duomenų modelis gali būti išreikštas skirtingomis formomis, pavyzdžiui sql duomenų šaltinio atveju, modelis aprašo vieną duomenų bazės lentelę.

Kiekvienas modelis turi turėti pirminį raktą, unikalų modelio duomenų identifikatorių. Pirminis raktas aprašomas pateikiant vieną ar kelias model.property reikšmes model.ref stulpelyje, kurios kartu unikaliai identifikuoja kiekvieną duomenų eilutę.

Išimtiniais atvejais, kai modelio duomenų laukų reikšmės turi būti generuojamos dinamiškai ar kitais nestandartiniais atvejais yra galimybė nurodyti model.type reikšmę. Jei model.type yra pateiktas, tada už modelio duomenų generavimą, įeinančių duomenų tikrinimą ir visos kitos su modeliu susijusios dalys gali būti pritaikytos konkretaus modelio atvejui. Tačiau, jei reikia keisti tik duomenų pateikimą, užtenka naudoti model.prepare formules.

model.source

Modelio pavadinimas šaltinyje. Prasmė priklauso nuo resource.type.

model.prepare

Formulė skirta duomenų filtravimui ir paruošimui, iš dalies priklauso nuo resource.type.

Taip pat skaitykite: Duomenų atranka.

model.type

Jei nurodytą, naudoti išplėstą modelio variantą, jei nenurodyta palikti tuščią. Jei tuščia, naudoti standartinį modelio variantą.

Gali būti įrašoma reikšmė absent, kuri nurodo, kad modelis buvo ištrintas.

model.ref

Kableliu atskirtas sąrašas model.property reikšmių, kurios kartu unikaliai identifikuoja vieną duomenų eilutę (pirminis lentelės raktas).

model.level

Modelio brandos lygis, nusakantis pačio modelio brandos lygį, pavyzdžiui ar nurodytas pirminis raktas, ar modelio pavadinimas atitinka kodiniams pavadinimams kelimus reikalavimus.

model.access

Modeliui priklausančių laukų prieigos lygis. Paveldimas.

model.uri

Sąsaja su išoriniu žodynu.

model.title

Modelio pavadinimas.

model.description

Modelio aprašymas.

model.property

Modeliui priklausantis duomenų laukas.

Savybė

Duomenų laukas atspindi tam tikrą modelio savybę arba tai gali būti lentelės stulpelis, jei duomenų šaltinis yra lentelė.

property.source

Duomenų lauko pavadinimas šaltinyje. Prasmė priklauso nuo resource.type.

property.prepare

Formulė skirta duomenų tikrinimui ir transformavimui arba statinės reikšmės pateikimui.

property.type

Nurodomas loginis duomenų tipas. Dėl galimų tipų sąrašo žiūrėti Duomenų tipai.

Loginis duomenų tipas yra toks tipas, kurį tikitės gauti publikuojant duomenis per API. Loginis tipas gali skirtis nuo duomenų šaltinio tipo.

Visi duomenų tipai gali turėti tokius parametrus:

  • required - nurodo, kad šis duomenų laukas yra privalomas, tai reiškia, kad šio duomenų lauko reikšmė visada turi būti pateikta. Pagal nutylėjimą visi modelio duomenų laukai yra neprivalomi.

Kai kurie duomenų tipai, gali turėti konkrečiam duomenų tipui pateikiamus papildomus parametrus, tokie parametrai nurodomi skliausteliuose.

Dupmenų tipų pavyzdžiai:

  • integer

  • integer required

  • geometry

  • geometry(linestringm, 3345) required

property.ref

Priklauso nuo property.type, nurodo matavimo vienetus, laiko ar vietos tikslumą, klasifikatorių arba ryšį su kitais modeliais. Ką tiksliai reiškia šis laukas, patikslinta skyrelyje Duomenų tipai.

property.level

Nurodo duomenų lauko brandos lygį. Žiūrėti Brandos lygiai.

property.access

Nurodo prieigos prie duomenų lygį. Žiūrėti skyrių Prieigos lygiai.

property.uri

Sąsaja su išoriniu žodynu. Žiūrėti Išoriniai žodynai.

property.title

Duomenų lauko pavadinimas. Šis pavadinimas yra skirtas skaityti žmonėms ir bus rodomas duomenų laukų sąrašuose ir antraštėse. Jei nenurodyta, bus naudojamas property kodinis pavadinimas.

property.description

Duomenų lauko aprašymas.

property.enum

Žiūrėti Klasifikatoriai.

Papildomos dimensijos

Išorinių žodynų prefiksai

Sąsają su išoriniais žodynais galima pateikti model.uri ir property.uri stulpeliuose. Tačiau prieš naudojant žodynus, pirmiausia reikia apsirašyti žodynų prefiksus. Žodynų prefiksai aprašomi taip:

prefix
prefix.ref

Prefikso pavadinimas.

prefix.uri

Išorinio žodyno URI.

prefix.title

Prefikso antraštė.

prefix.description

Prefikso aprašymas.

Rekomenduojama naudoti LOV prefiksus.

Aprašyti prefiksai gali būti naudojami model.uri ir property.uri stulpeliuose tokiu būdu: prefix:name.

Pavyzdys:

d

r

b

m

property

type

ref

uri

dataset1

prefix

spinta

https://github.com/atviriduomenys/manifest/issues/

manifest

https://github.com/atviriduomenys/spinta/issues/

vadovas

https://atviriduomenys.readthedocs.io/

dct

http://purl.org/dc/dcmitype/

dataset2

prefix

dcat

http://www.w3.org/ns/dcat#

dct

http://purl.org/dc/terms/

dctype

http://purl.org/dc/dcmitype/

foaf

http://xmlns.com/foaf/0.1/

owl

http://www.w3.org/2002/07/owl#

prov

http://www.w3.org/ns/prov#

rdf

http://www.w3.org/1999/02/22-rdf-syntax-ns#

rdfs

http://www.w3.org/2000/01/rdf-schema#

sdo

http://schema.org/

skos

http://www.w3.org/2004/02/skos/core#

vcard

http://www.w3.org/2006/vcard/ns#

xsd

http://www.w3.org/2001/XMLSchema#

Prefiksai turi būti apibrėžti duomenų rinkinio kontekste, kadangi skirtingi duomenų rinkiniai gali naudoti skirtingus prefiksus, tiems pateims URI. Pavyzdžiui abiejusoe rinkinyje pavyzdyje aukščiau, dct ir dctype rodo į tą patį URI.

Klasifikatoriai

Tam tikri duomenų laukai turi fiksuotą reikšmių variantų aibę. Dažnai duomenų bazėse fiksuotos reikšmės saugomos skaitine forma ar kitais kodiniais pavadinimais. Tokias fiksuotas reikšmes duomenų struktūros apraše galima pateikti neužpildant hierarchinių stulpelių ir nurodant type reikšmę enum, pavyzdžiui:

id

d

r

b

m

property

type

ref

source

prepare

level

access

uri

title

description

1

datasets/example/places

2

places

sql

sqlite://

3

Place

id

PLACES

4

id

integer

ID

3

open

5

type

string

CODE

3

open

6

enum

1

"city"

City

7

2

"town"

Town

8

3

"village"

Village

9

name

string

NAME

3

open

Šiame pavyzdyje Place.type laukas yra klasifikatorius, kurio reikšmės yra kodai 1, 2 ir 3, kurios duomenų struktūros apraše keičiamos į city, town ir village, papildomai title stulpelyje nurodant reikšmės pavadinimą.

Jei tas pats klasifikatorius gali būti naudojamas kelios skirtingose vietos, tada galima iškelti klasifikatorių ir suteikti jam pavadinimą, pavyzdžiui:

id

d

r

b

m

property

type

ref

source

prepare

level

access

uri

title

description

1

datasets/example/places

6

enum

place

1

"city"

City

7

2

"town"

Town

8

3

"village"

Village

2

places

sql

sqlite://

3

Place

id

PLACES

4

id

integer

ID

3

open

5

type

string

place

CODE

3

open

9

name

string

NAME

3

open

Šiuo atveju, klasifikatoriui buvo suteiktas pavadinimas place įrašytas enum.ref stulpelyje, 6 eilutėje. O Place.type laukui, prepare stulpelyje nurodyta, kad šis laukas naudoja vardinį place klasifikatorių.

enum
enum.ref

Pasirinkimų sąrašo pavadinimas.

enum.source

Pateikiama originali reikšmė, taip kaip ji saugoma duomenų šaltinyje. Pateiktos reikšmės turi būti unikalios ir negali kartotis.

Jei pageidaujama aprašyti tuščią šaltinio reikšmę, tada property.prepare celėje reikia nurodyti formulę, kuri tuščią reikšmę pakeičia, į kokią nors kitą. Formulės pavyzdys:

swap('', '-')
enum.prepare

Pateikiama reikšmė, tokia kuri bus naudojama atveriant duomenis. model.prepare filtruose taip pat bus naudojama būtent ši reikšmė.

enum.prepare reikšmės gali kartotis, tokiu būdu, kelios skirtingos enum.source reikšmės bus susietos su viena enum.prepare reikšme.

enum.access

Klasifikatoriams galima nurodyti skirtingas prieigos teises, tokiu atveju, naudotojas turintis open prieigą matys tik tuos duomenis, kurių klasifikatorių reikšmės turi open prieigos teises, visi kiti bus išfiltruoti.

enum.title

Fiksuotos reikšmės pavadinimas.

enum.description

Fiksuotos reikšmės aprašymas.

Pagal nutylėjimą, jei property.prepare yra tuščias ir property turi Klasifikatoriai sąrašą, tada jei šaltinis turi neaprašytą reikšmę, turėtų būti fiksuojama klaida.

Jei yra poreikis fiksuoti tik tam tikras reikšmes, o visas kitas palikti tokias, kokios yra šaltinyje, tada property.prepare stulpelyje reikia įrašyti self.choose(self).

Parametrai

Parametrai leidžia iškelti tam tikras duomenų paruošimo operacijas į parametrus kurie gali būti naudojami Dimensijos, kurioje apibrėžtas parametras kontekste. Parametrai gali gražinti iteratorius, kurių pagalba galima dinamiškai kartoti resource duomenų skaitymą, panaudojant aprašytus parametrus. Taip pat parametrų pagalba galima sudaryti reikšmių sąrašus, kurių pagalba galima kartoti resource su kiekviena reikšme.

Parametrai dažniausiai naudojami žemesnio brandos lygio duomenų šaltiniams aprašyti, o taip pat API atvejais, kai duomenys atiduodame dinamiškai.

Parametrai aprašomi pasitelkiant papildomą Parametrai dimensiją.

id

d

r

b

m

property

type

ref

source

prepare

1

datasets/example/cities

2

places

csv

https://example.com/{}.csv

3

Country

id

countries

4

code

string

CODE

5

title

string

TITLE

6

City

country, title

cities/{country.code}

7

param

country

Country

select(code)

8

country

ref

Country

param("country").code

9

title

string

TITLE
param
param.ref

Parametro kodinis pavadinimas.

param.prepare

Formulė, kuri grąžina sąrašą reikšmių aprašomam parametrui.

param.source

Jei reikšmė pateikta, tada ši reikšmė perduodama formulei kaip self. Pavyzdžiui, jei param.prepare pateikta formulė select(code), o param.source nurodyta Country, tai formulė bus iškviesta taip select("Country", code).

Jei parametro reikšmė yra iteratorius, tada dimensija, kurios kontekste yra aprašytas parametras yra kartojama tiek kartų, kiek reikšmių grąžina iteratorius.

Jei yra keli Parametrai grąžinantys iteratorius, tada iš visų iteratorių sudaroma Dekarto sandauga ir resource dimensija vykdoma su kiekviena sandaugos rezultato reikšme.

Jei sekančioje DSA eilutėje, einančioje po eilutės, kurioje aprašytas Parametrai, nenurodytas type ir neužpildytas joks kitas dimensijos stulpelis, tada parametras tampa iteratoriumi, kurio reikšmių sąrašą sudaro sekančiose eilutėse patektos source ir prepare reikšmės. Pavyzdžiui anksčiau pateiktą pavyzdį galima būtų perdaryti taip:

id

d

r

b

m

property

type

ref

source

prepare

1

datasets/example/cities

2

places

csv

https://example.com/{}.csv

3

Country

id

countries

4

code

string

CODE

5

title

string

TITLE

6

City

country, title

cities/{country}

7

param

country

"lt"

7

"lv"

7

"ee"

8

country

ref

Country

param("country")

9

title

string

TITLE

Šiame pavyzdyje, parametras country grąžins tris šalies kodus: lt, lv ir ee, kurie bus panaudojami cities/{country} pavadinime, pakeičiant {country} dalį.

Parametrai reikšmės pasiekiamos naudojanti pavadinimą įrašytą param.ref stulpelyje. Pavyzdžiui, jei param.ref stulpelyje įrašyta x, tada x parametro reikšmę galima gauti taip:

source

{x}.

prepare

x arba param(x).

Parametrų generavimui galima naudoti tokias formules:

param.prepare
range(stop)

Sveikų skaičių generavimas nuo 0 iki stop, stop neįeina.

range(start, stop)

Sveikų skaičių generavimas nuo start iki stop, stop neįeina.

scalar(name)

Jei nurodytas param.source, tada imama tik name lauko reikšmė, o ne visi modelio laukai.

Jei užpildytas param.source stulpelis, tada param.prepare stulpelyje galima naudoti filtrą nurodyto param.source modelio duomenims filtruoti, o naudojant parametrus galima nurodyti ir modelio laukų pavadinimus, pavyzdžiui:

source

{x.field}.

prepare

x.field arba param(x).field.

Reikšmių sukeitimas

Tam tikrais atvejais duomenis tenka normalizuoti parenkant tam tikrą reikšmę jei tenkinama nurodyta sąlyga. Tokias situacijas galima aprašyti pasitelkiant switch dimensiją.

switch
switch.source

Reikšmė, kuri bus atveriama.

switch.prepare

Sąlyga, naudojant einamojo modelio laukus. Jei sąlyga tenkinama, tada laukui priskiriama switch.source reikšmė. Jei sąlyga netenkinama, tada bandoma tikrinti sekančią sąlygą. Parenkama ta reikšmė, kurios pirmoji sąlyga tenkinama.

Jei switch.prepare yra tuščias, tada sąlyga visada teigiama ir visada grąžinama switch.source reikšmė.

Komentavimas

Dirbant su DSA yra galimybė komentuoti eilutes, naudojant papildomą comment dimensiją, kurią galima naudoti bet kurios kitos dimensijos kontekste.

comment
comment.id

Komentaro numeris.

comment.ref

Komentuojamo vieno ar kelių kableliu atskirtų property pavadinimai. Galima nurodyti ne tik stulpelio pavadinimą, bet ir dimensiją.

comment.source

Komentaro autorius.

comment.prepare

Keitimo pasiūlymas, naudojant create(), update ir delete() funkcijas. Pavyzdžiui:

update(property: "pavadinimas@lt", type: "text")

Šiuo atveju nurodoma, kad siūloma keisti property pavadnimą į pavadinimas@lt, o type į text.

comment.level

Nurodoma, kad patenkinus keitimo sliūlymą, kuris nurodytas comment.prepare stulplyje, komentuojamai eilutei gali būti suteiktas nurodytas brandos lygis.

comment.access

Nurodoma, ar komentaras gali būti publikuojamas viešai.

private

Komentaras negali būti publikuojamas viešai. Šis prieigos lygis naudojamas pagal nutylėjimą.

open

Komentaras gali būti publikuojamas viešai.

comment.uri

Viena ar kelios kableliu atskirtos šaltinio nuorodos, kuri pateikta daugiau informacijos apie tai, kas komentuojama. Taip pat gali būti nurodytas kito komentaro comment.id, nurodant, kad tai yra atsakymas į ankstesnį komentarą.

URI pateikiami sutrumpinta forma, naudojant prefikstus. Žiūrėti skrių Išoriniai žodynai.

comment.title

Komentaro data, ISO 8601 formatu.

comment.description

Komentaro tekstas.

Pavyzdys

d

r

b

m

property

type

ref

prepare

level

access

uri

example

prefix

spinta

https://github.com/atviriduomenys/manifest/issues/

manifest

https://github.com/atviriduomenys/spinta/issues/

vadovas

https://atviriduomenys.readthedocs.io/

Imone

2

comment

base

update(base: "/jar/JuridinisAsmuo", ref: "id")

4

open

spinta:205, manifest:1290

comment

ref

update(ref: "id")

4

open

vadovas:dsa/dimensijos.html#model.ref

id

integer

4

open

pavadinimas

string

2

open

comment

ref

update(property: "pavadinimas@lt", type: "text")

4

open

spinta:204

Daugiakalbiškumas

title ir description stulpeliuose tekstas rašomas lietuvių kalba, tačiau galima pateikti tekstą ir kita kalba, panaudojus papildomą lang dimensiją, kurią reikia naudoti prieš eilutę, kuriai pateikiamas tekstas kita kalba.

lang
lang.ref

ISO 639-1 dviejų simbolių kalbos kodas.

lang.title

Pavadinimas lang.ref stulpelyje nurodyta kalba.

lang.description

Aprašymas lang.ref stulpelyje nurodyta kalba.

Struktūros keitimas

Laikui einant, pirminių duomenų šaltinių arba jau atvertų duomenų struktūra keičiasi, papildoma naujais modeliais ar savybėmis, keliant duomenų brandos lygį seni duomenys keičiami naujais, aukštesnio brandos lygio duomenimis.

Visi šie struktūros ar pačių duomenų pasikeitimai fiksuojami papildomos migrate dimensijos pagalba, kuri gali būti naudojama, bet kurios kitos dimensijos kontekste.

Pastaba

Migracijos naudojamos tik tuo atveju, kai keičiasi duomenų struktūra arba patys duomenys. Jei keičiasi tik metaduomenys, tai migracijų sąraše neatsispindi.

id

d

r

b

m

property

type

ref

prepare

level

title

description

1

migrate

2021-12-21 16:29

Pirmoji migracija.

2

migrate

1

2021-12-21 16:33

Antroji migracija.

3

migrate

2

2022-06-21 16:41

Trečioji migracija.

datasets/example/migrate

Country

id

id

integer

4

code

string

3

migrate

1

create(level: 2)

migrate

3

update(level: 3)

name

string

migrate

2

create()

Pavyzdyje aukščiau matome, kad šis duomenų struktūros aprašas turi tris migracijas:

  1. Pirmosios migracijos metu sukuriamas pradinis duomenų struktūros variantas. Pirmoji migracija nežymima prie modelių ir duomenų laukų, nebent daromas keitimas, tuomet įtraukiam ir pirmoji migracija, kad būtų matoma, kas keitėsi. Būtent toks atvejis parodytas prie Country.code lauko, kuri trečiojo migracijoje keičiamas brandos lygis.

  2. Antrosios migracijos metu buvo įtrauktas naujas duomenų laukas Country.name.

  3. Trečiosios migracijos metu, buvo keičiami Country.code lauko duomenys, pakeitimo metu brandos lygis buvo pakeltas iki trečio. Atkreipkite dėmesį, kad metaduomenų pasikeitimas, kaip šiuo atveju, žymimas migracijose tik tuo atveju, jei tai yra susiję su pačių duomenų pasikeitimu.

    Jei brandos lygis būtų pakeistas, nekeičiant pačių duomenų, tuomet tokio pakeitimo nereikėtų įtraukti į migracijų sąrašą.

    Kadangi trečiojoje migracijoje buvo atliktas su ankstesne versija nesuderinamas pakeitimas, tai šios migracijos data yra 6 mėnesiai ateityje, kadangi nesuderinamos migracijos pirmiausia paskelbiamos, o įgyvendinamos tik praėjus 6 mėnesiams nuo paskelbimo.

migrate
migrate.id

Migracijos numeris (UUID). Kiekvienos migracijos metu gali būti atliekama eilė operacijų, visos operacijos fiksuojamos naudojant migracijos numerį.

Visų migracijų sąrašas pateikiamas, kai migrate nepriklauso jokiam dimensijos kontekstui.

migrate.ref

Ankstesnės migracijos numeris, pateiktas migrate.id stulpelyje, arba tuščia, jei prieš tai jokių kitų migracijų nebuvo.

Naudojamas jei migrate nepatenka į jokios dimensijos kontekstą.

Jei migrate aprašomas dimensijos kontekste, tada šis stulpelis nenaudojamas.

migrate.prepare

Migracijos operacija. Galimos tokios operacijos:

create()

Priklausomai nuo dimensijos konteksto, prideda naują modelį, arba savybę.

Funkcijai galima perduoti ref ir kitus vardinius argumentus, kurie atitinka DSA lentelės metaduomenų stulpelių pavadinimus.

update()

Taikomas tik duomenų laukams ir nurodo, kad buvo pakeistos esamų duomenų reikšmės, keičiant reikšmių dimensiją, matavimo vienetus, formatą ir kita.

Funkcijai galima perduoti ref ir kitus vardinius argumentus, kurie atitinka DSA lentelės metaduomenų stulpelių pavadinimus.

Perduodami tik tie vardiniai argumentai, kuriuos atitinkantys metaduomenys keičiasi.

delete()

Priklausomai nuo dimensijos konteksto, šalina modelį ar savybę.

Pašalinto modelio ar savybės type keičiamas į absent reikšmę.

filter(where)

Naudojamas property kontekste, kai vykdoma duomenų migracija. Nurodo, kad migracija taikoma tik where sąlygą tenkinantiems duomenims.

Be šių pagrindinių migracijos operacijų, galima naudoti kitas duomenų transformavimo operacijas, kurios vykdomos su kiekviena duomenų eilute ir atlikus pateiktas transformacijos funkcijas, pakeista reikšmė išsaugoma.

migrate.title

Migracijos įvykdymo data ir laikas. Migracijos laikas ir data gali būti ir ateityje, tuo atveju, jei daromas nesuderinamas keitimas.

Naudojamas tik tada, kai migrate nepatenka į jokios dimensijos kontekstą.

migrate.description

Migracijos atliekamo pakeitimo trumpas aprašymas.