Dimensijos

Turinys

Dimensijos#

Demensijos leidžia vienoje lentelėje sutalpinti kelias skirtingas lenteles turinčias bendrų savybių.

DSA lentelėje turime tokius dimensijų stulpelius:

dataset
resource
model
property

dataset	resource	model	property	title
datasets/gov/rc/ar/ws				Duomenų rinkinys
	db			Duomenų teikimo paslauga
		Gyvenviete		Esybė
			pavadinimas	Savybė

Pavyzdyje aukščiau turime tris lenteles, turinčias vieną bendrą stulpelį title.

Daugiamatė lentelė pateikta viršuje, atitiktų tokią vienamatę lentelę:

type	name	title
dataset	datasets/gov/rc/ar/ws	Duomenų rinkinys
resource	db	Duomenų teikimo paslauga
model	Gyvenviete	Esybė
property	pavadinimas	Savybė

Kadangi DSA lentelė yra daugiamatė, nurodant stulpelį, jei kalbama apie konkrečios dimensijos stulpelį, reikia nurodyti ir dimensiją, pavyzdžiui dataset.title nurodo būtent apie dataset diemensijos title stulpelį.

dataset#

Duomenų rinkinys struktūros apraše nurodomas tam, kad būtų galimybė susieti duomenų struktūros elementus su duomenų rinkiniais registruotais duomenų kataloge. Toks susiejimas atliekamas naudojant duomenų rinkinio kodinį pavadinimą.

Pastaba

Nurodytas duomenų rinkinio ar vardų erdvės kodinis pavadinimas turi būti unikalus tarp visų duomenų struktūros aprašų.

Taip pat žiūrėkite

Vardų erdvės

Kodiniai pavadinimai

dataset.id#: Duomenų rinkinio arba duomenų erdvės identifikatorius.

dataset.type#

Jei nenurodyta, pagal nutylėjimą naudojama dataset reikšmė, kuri nurodo duomenų rinkinio kodinį pavadinimą nurodyta duomenų kataloge.

Galimos reikšmės:

ns: Vardų erdvė.
dataset: Duomenų rinkinys.

Pavyzdys

dataset	type	title
datasets/gov/rc	ns	Registrų centras
datasets/gov/rc/ar	ns	Adresų registras
datasets/gov/rc/ar/ws		Duomenų teikimo paslauga

dataset.ref#

Duomenų rinkinio identifikatorius duomenų kataloge. Alternatyviai, galima naudoti dataset.source.

Nenaudojamas jei dataset.type yra ns.

dataset.source#

Nuoroda į duomenų rinkinio puslapį duomenų kataloge.

Nenaudojama, jei dataset.type yra ns.

dataset.prepare#: Nenaudojama.

dataset.level#

Nenaudojamas.

Duomenų rinkinio brandos lygis yra išskaičiuojamas iš model.level ir property.level.

dataset.access#: Prieigos lygis, naudojamas pagal nutylėjimą viesiems šios vardų erdvės elementams.

dataset.title#: Duomenų rinkinio ar vardų erdvės pavadinimas.

dataset.description#: Duomenų rinkinio ar vardų erdvės aprašymas.

resource#

Fizinis duomenų šaltinis, kuriame saugomi duomenys.

Kiekvienam duomenų šaltiniui suteikiamas kodinis pavadinimas, kuris nėra naudojamas formuojant API URI, tačiau naudojamas identifikuojant patį duomenų šaltinį.

Nurodytas duomenų šaltinio kodinis pavadinimas turi būti unikalus duomenų rinkinio kontekste.

Taip pat žiūrėkite

Duomenų šaltiniai

resource.id#: Duomenų šaltinio unikalus identifikatorius UUID formatu.

resource.type#

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

`sql`	Reliacinės duomenų bazės
`csv`	CSV lentelės
`json`	JSON resursai
`xml`	XML resursai

resource.ref#

Identifikatorius, naudojamas konfiguracijoje, kurioje pateikiamas pilnas resurso adresas ir kiti parametrai, tokie kaip slaptažodžiai ar prisijungimo vardai.

Alternatyviai resurso pilną adresą galima nurodyti resource.source stulpelyje.

resource.source#

Pilnas resurso adresas URI formatu.

Įspėjimas

Jei duomenų šaltinis reikalauja naudotojo vardo ir slaptažodžio, rekomenduojama nerodyti URI struktūros apraše, vietoj to prisijungimo duomenis prie šaltinio pateikti atskirame konfigūraciniame faile, naudojant resource.ref stulpelį.

dialect [ + driver ] :// [ user : password @ ] host [ : port ] / path [ ? params ]

dialect

Duomenų šaltinio dialektas arba protokolas, kuriuo teikiami duomenys, galimi variantai:

`postgresql`	PostgreSQL duomenų bazė.
`mysql`	MySQL duomenų bazė.
`mariadb`	MariaDB duomenų bazė.
`sqlite`	SQLite duomenų bazė.
`oracle`	Oracle duomenų bazė.
`mssql`	Microsoft SQL Server duomenų bazė.
`http`, `https`	Duomenų failas publikuojamas HTTP protokolu.

driver

Priklauso nuo dialect ir nuo naudojamo duomenų agento.

user

Duomenų šaltinio naudotojo vardas, jei duomenų šaltinis to reikalauja.

password

Duomenų šaltinio slaptažodis, jei duomenų šaltinis to reikalauja.

host

Duomenų šaltinio serverio adresas, jei duomenų šaltinis yra nuotoliniame serveryje.

port

Nuotolinio serverio prievado numeris.

path

Duomenų bazės pavadinimas arba kelias iki duomenų failo.

params

Papildomi parametrai, priklauso nuo naudojamo driver.

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

resource.access#

Duomenų šaltinio prieigos lygis.

Pildyti neprivaloma, jei nurodytas, tada visoms žemesnio lygio dimensijoms, pagal nutylėjimą taikomas nurodytas šaltinio prieigos lygis.

resource.title#: Duomenų šaltinio pavadinimas.

resource.description#: Duomenų šaltinio aprašymas.

Funkcijos#

resource.http(method='GET', body=form)#

Papildomi parametrai, reikaling konstruojant HTTP užklausas.

Argumentai

method (vardinis)

HTTP methodas.

body (vardinis)

HTTP užklausos perduodamų duomenų formatas.

Galimi variantai:

`json`	Duomenys perduodami JSON formatu.
`xml`	Duomenys perduodami XML formatu.
`from`	Duomenys perduodami `application/x-www-form-urlencoded` arba `multipart/form-data` (jei formoje pateikiami failai) formatu.

Pavyzdys

resource	type	ref	source	prepare
resource1	json		https://example.com/
	param	name1	NAME1	`query("value1")`
		name2	NAME2	`query("value2")`

Bus konstruojamas toks URI:

https://example.com/?NAME1=value1&NAME2=value2

base#

Modelio bazė naudojama objekto identifikatoriams susieti, kai keli skirtingi duomenų modeliai aprašo tą pačią realaus pasaulio esybę.

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.

Išoriniai identifikatoriai#

Modelis ir jo bazė turi vienodus išorinius identifikatorius, nors vidiniai šaltinio identifikatoriai gali skirtis.

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.

Identifikatorių apjungimas atliekamas pagal model.ref ir base.ref pateiktus pirminius raktus, kurie turi sutapti.

Visi base.ref laukai turi būti aprašyti tiek base, tiek model modeliusoe.

Paveldimumas#

model paveldi visus laukus iš base, į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 skaitomi iš arba rašomi į base modelį.

Skaitymas ir rašymas iš base įmanomas tik tuo atveju, jei tai palaiko duomenų šaltinis.

Duomenų lokalumas#

Visi modelio laukai, kurie neturi property.type, fiziškai saugomi base modelio šaltinyje.

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.

Persidengimas#

Tais atvejais, kai property yra saugomas tiek base, tiek model lentelėse, norint gauti persidengiančios savybės duomenis iš base, reikia naudoti _base. prefiksą.

_base rodo į bazinį modelė.

Pavyzdžiai#

Pavyzdys

dataset	base	model	property	type	ref	source
example
		Location			id
			id	integer
			name@lt	text
			population	integer
	Loocation				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ą.

model#

Duomenų modelio kodinis pavadinimas. Užrašomas vienaskaitos forma iš didžiosios raidės, jei pavadinimas iš kelių žodžių, žodžiai atskiriami didžiąja raide.

Pavyzdžiai

Gyvenviete

AdministracinisTipas

Modelis yra siejamas su realaus pasaulio esybėmis. Viena esybė gali turėti kelis skirtingus duomenų modelius, su skirtingomis savybėmis, tačiau skirtingi vienos esybės modeliai turi turėti vienodus identifikatorius.

model.type#

Pakeista 0.2 versijoje: Nuo 0.2 versijos nurodo modelio bazę.

Nurodo modelio bazę arba esybę, kurios pagalba skirtingiems modeliams suteikiami vienodi identifikatoriai.

Jei nurodyta modelio bazė, model.ref nurodytas pirminis raktas turi sutapti su bazinio modelio pirminiu raktu.

Taip pat turi sutapti ir modelio savybės su baziniu modeliu. Tačiau modelis gali turėti ir papildomų savybių, kurių nėra baziniame modelyje. Vienintelis privalomas reikalavimas yra pirminio rakto susiejimas, kad modelis ir bazinis modelis turėtu vienodus identifikatorius.

Pavyzdys

Duomenų modelis

        classDiagram

  class ns1Gyvenviete["ns1:Gyvenviete"]
  class ns2Gyvenviete["ns2:Gyvenviete"]
  class Location["locn:Location"] {
    + code: integer [1..1]
    + name: text [1..1]
  }
  ns1Gyvenviete --|> Location
  ns2Gyvenviete --|> Location

Struktūros aprašas

dataset	model	property	type	ref
locn
	Location			code
		code	integer
		name@en	string
ns1
	Gyvenviete		/locn/Location	code
		code	integer
		name@lt	string
ns2
	Gyvenviete		/locn/Location	code
		code	integer
		name@lt	string

Pavyzdyje turime tris modelius iš skirtingų duomenų rinkinių, ns1:Gyvenviete ir ns2:Gyvenviete nurodo locn:Location kaip šių modelių bazę, tai reiškia, kad visi trys modeliai realiame pasaulyje yra viena esybė, turinti vienodus identifikatorius skirtinguose modeliuose.

model.ref#

Kableliu atskirtas sąrašas model.property duomenų laukų pavadinimų, kurie kartu unikaliai identifikuoja vieną duomenų eilutę (pirminis lentelės raktas arba identifikatorius).

Jei nurodytas model.type, pirminis raktas būtinai turi sutapti su model.type pirminiu raktu.

Jei modelio objektą unikaliai identifikuoja keli duomenų laukai, model.ref stulpelyje galima nurodyti kelis duomenų laukus atskirtus kableliu.

model.source#

Modelio duomenų šaltinis, vieta ar pavadinimas fiziniame duomenų modelyje.

Kas įrašoma į šį stulpelį priklauso nuo duomenų šaltinio resource.type.

SQL atveju, tai bus lentelės pavadinimas, XML atveju - XPath išraiška, JSON atveju - JSONPath išraiška, skirtingi duomenų šaltiniai gali naudoti skirtingą sintaksę vietai (kur fiziškai saugomi duomenys) apibūdinti.

Jei duomenys publikuojami vidinėje saugykloje, model.source pildyti nereikia, kadangi vidinės saugyklos fizinio ir loginio modelio pavadinimai yra tokie patys.

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

Taip pat žiūrėkite

Formulės

Duomenų atranka

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

Taip pat žiūrėkite

Brandos lygis

model.access#

Modeliui priklausančių laukų prieigos lygis.

Modelio prieigos lygis yra išskaičiuojamas iš modeliui priskirtų duomenų laukų, imant didžiausią prieigos lygmenį nurodytą prie duomenų lauko. Pavyzdžiui, jei bent vienas duomenų laukas turi aukščiausią open prieigos lygmenį, tada ir viso modelio prieigos lygis tampa open.

Taip pat žiūrėkite

Prieigos lygiai

model.uri#

Sąsaja su OWL, RDFS ontologijomis ar SKOS kontroliuojamais žodynais.

Jei nenurodyta, generuojamas pavadinimas pagal tokį šabloną:

https://data.gov.lt/id/ dataset / model

Pavyzdys

https://data.gov.lt/id/datasets/gov/rc/ar/ws/Location

Struktūros apraše galima nurodyti automatiškai generuojamus URI.

Pavyzdys

dataset	model	property	type	ref	uri
adresai
			prefix	ar	https://data.gov.lt/id/adresai/
	Location			code
		code	integer		ar:code
		name@en	string		ar:name
datasets/gov/ivpk/dp/api
			prefix	ar	https://data.gov.lt/id/adresai/
	Gyvenviete			code	ar:Location
		code	integer		ar:code
		name@lt	string		ar:name

Šiame pavyzdyje ar:Location yra URI, kuris yra automatiškai generuojamas adresai duomenų rinkinyje.

Taip pat žiūrėkite

Išoriniai žodynai

model.title#

Trumpas modelio pavadinimas pirmas žodis iš didžiosios raidės, pavadinimo gale taško nereikia.

Pavadinime nereikia kartoti duomenų rinkinio pavadinimo. Modelio pavadinimas rašomas duomenų rinkinio kontekste.

model.description#: Modelio aprašymas.

model.property#: Modeliui priklausantis duomenų laukas.

Funkcijos#

model.distinct()#

Jei model.ref pirminis raktas nėra unikalus ir norma panaikinti besidubliuojančias reikšmes, galima nurodyti distinct() funkciją, kuri panaidins objktus su besidubliuojančiais pirminiais raktais.

Pavyzdys

Turint tokius duomenis duomenų šaltinyje:

CITY	COUNTRY
Vilnius	Lithuania
Kaunas	Lithuania

Ir struktūros aprašą, kuriame COUNTY aprašytas, kaip atskiras modelis:

model	property	type	ref	source	prepare	level	access
Country			name@en	CITIES	`distinct()`	4
	name@en	string		COUNTRY		4	open
City			name@en	CITIES		4
	name@en	string		CITY		4	open
	country	ref	Country	COUNTRY		3	open

distinct() funkcija panaikina besidubliuojančius objektus ir grąžina tik vieną šalį.

property#

Savybė yra duomenų laukas, modelio atributas.

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 enum.

Papildomos dimensijos#

prefix#

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.ref#

Prefikso pavadinimas.

Rekomenduojama naudoti prefix.cc paslaugą URI prefiksų pavadinimams.

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	type	ref	uri
dataset1
	prefix	spinta	https://github.com/atviriduomenys/spinta/issues/
		dsa	https://ivpk.github.io/dsa/
		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 patiems URI. Pavyzdžiui abiejuose rinkinių pavyzdžiuose aukščiau, dct iš dataset1 ir dctype iš dataset2 rodo į tą patį URI.

enum#

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	m	property	type	ref	source	prepare	level	access	title
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 keliose skirtingose vietose, tada galima iškelti klasifikatorių ir suteikti jam pavadinimą, pavyzdžiui:

id	d	r	m	property	type	ref	source	prepare	level	access	title
1	datasets/example/places
2					enum	place	1	"city"			City
3							2	"town"			Town
4							3	"village"			Village
5		places			sql		sqlite://
6			Place			id	PLACES
7				id	integer		ID		3	open
8				type	string	place	CODE		3	open
9				name	string		NAME		3	open

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

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 enum 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).

param#

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 atiduodami dinamiškai.

Parametrai aprašomi pasitelkiant papildomą param dimensiją.

d	r	m	property	type	ref	source	prepare
datasets/example/cities
	places			csv		https://example.com/{}.csv
		Country			id	countries
			code	string		CODE
			title	string		TITLE
		City			country, title	cities/{code}
				param	code	Country	read().code
			country	ref	Country	code	param()
			title	string		TITLE

param.ref#: Parametro kodinis pavadinimas.

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

param.source#

Nurodoma parametro reikšmė šaltinyje, kuri yra pateikiama kaip pirmas param.prepare funkcijos argumentas.

Jei param.prepare nenurodyta jokia formulė, tada bus naudojam konstanta nurodyta param.source stulpelyje.

Pavyzdys

Jei param.prepare pateikta formulė param.read(), o param.source nurodyta Country, tai formulė bus iškviesta kaip read("Country").

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 param 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 param, 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:

dataset	resource	model	property	type	ref	source	prepare
datasets/example/cities
	places			csv		https://example.com/{}.csv
		Country			id	countries
			code	string		CODE
			title	string		TITLE
		City			country, title	cities/{country}
				param	country	lt
						lv
						ee
			country	ref	Country		`param(country)`
			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į.

param reikšmės pasiekiamos naudojant 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).

Funkcijos#

Parametrų generavimui galima naudoti tokias formules:

param.read(model)#: Sukuriama priklausomybė nuo kito modelio, skaitomi duomenys iš kito modelio ir su kiekvienu objektu, kreipiamasi į resource.source, panaudojant nuskaitytą objektą kaip parametrą formuojant šaltinio užklausą.

param.range(stop)#: Sveikų skaičių generavimas nuo 0 iki stop, stop neįeina.

param.range(start, stop): Sveikų skaičių generavimas nuo start iki stop, stop neįeina.

param.path(name, value)#

Parametras pateikia URI path dalies parametrą.

resource.source URI path parametrų vieta pateikiama {} skliaustų viduje, pavyzdžiui /cities/{id} nurodytas parametras id.

Funkcija gali būti iškviestai tokiais būdais:

path(value)
path(name, value)

Argumentai

name: Parametro pavadinimas nurodytas {} riestinių skliaustelių viduje. Jei nenurodyta, tada naudojamas param.source, jei šis nenurodytas, tada naudojamas param.ref pavadinimas.
value: Parametro reikšmė, gali būti statinė arba dinaminė.

Pavyzdys

resource	type	ref	source	prepare
resource1	json		/cities/{id}/
	param	id		`path(42)`

Bus konstruojamas toks URI:

/cities/42/

param.query(name, value)#

Parametras pateikia URI query dalies parametrą.

Jei resource.source jau turi query parametrus, jei bus papildyti arba perrašyti.

Argumentai

name: Nurodo URI query parametro pavadinimą, nurodomas param.source stulpelyje.
value: URI query paramtro reikšmė.

Pavyzdys

resource	type	ref	source	prepare
resource1	json		https://example.com/
	param	name1	NAME1	`query("value1")`
		name2	NAME2	`query("value2")`

Bus konstruojamas toks URI:

https://example.com/?NAME1=value1&NAME2=value2

param.header(name, value)#

Parametras pateikiamas, kaip HTTP antraštė.

Argumentai

name: Nurodo HTTP antraštės pavadinimą, nurodomas param.source stulpelyje.
value: HTTP antraštės reikšmė.

Pavyzdys

resource	type	ref	source	prepare
resource1	json		https://example.com/
	param	name1	X-Name1	`header("value1")`
		name2	X-Name2	`header("value2")`

Bus konstruojama tokia HTTP užklausa:

GET / HTTP/1.1
X-Name1: value1
X-Name2: value2

param.body(name, value, parent, type)#

Generuoja XML, JSON ar kito formato dokumentą, kuris pateikiamas HTTP užklausos metu.

Argumentai

name

JSONPath arba XPath_ išraiška, priklauso nuoo resource.prapare nurodytos resource.http() body tipo.

Nurodoma param.source stulpelyje.

value

Reikšmė suteikiama name elementui http užklausos struktūroje.

parent (neprivalomas)

Parametro pavadinimas, kurio pagrindu konstruojamas naujas dokumentas.

type (neprivalomas, vardinis)

Naudojamas konstruojant naują dokumentą, jei nurodytas, kiti argumentai turi būti nepateikti.

Pavyzdys (JSON)

resource	type	ref	source	prepare
resource1	json		https://example.com/	`http(body: json)`
	param	name1	NAME1	`body("value1")`
		name2	NAME2	`body("value2")`
		name3	NESTED.NAME3	`body("value3")`
		name4	ARRAY[].NAME4	`body("value4")`
		name5	MATRIX[]	`body()`
			MATRIX[][]	`body("value5")`
			MATRIX[]	`body()`
			MATRIX[][]	`body("value6")`
			MATRIX[][]	`body("value7")`

{
    "NAME1": "value1",
    "NAME2": "value2",
    "NESTED": {
        "NAME3": "value3",
    },
    "ARRAY": [
        {"NAME4": "value4"}
    ],
    "MATRIX": [
        ["value5"],
        ["value6", "value7"]
    ]
}

Pavyzdys (XML)

resource	type	ref	source	prepare
resource1	json		https://example.com/	`http(body: xml)`
	param	name1	DATA/@NAME1	`body("value1")`
		name2	DATA/NAME2	`body("value2")`
		name3	DATA/NESTED/NAME3	`body("value3")`
		name4	DATA/ARRAY/NAME4	`body("value4")`
		name5	DATA/ARRAY/NAME4	`body("value5")`

<?xml version="1.0" encoding="utf-8"?>
<DATA NAME1="value1">
    <NAME2>value2</NAME2>
    <NESTED>
        <NAME3>value3</NAME3>
    </NESTED>
    <ARRAY>
        <NAME4>value4</NAME4>
        <NAME4>value5</NAME4>
    </ARRAY>
</DATA>

Pavyzdys (maišytas)

resource	type	ref	source	prepare
resource1	json		https://example.com/	`http(body: xml)`
	param	name1	DATA/@NAME1	`body("value1")`
		name2	DATA/NAME2	`body(name3)`
		name3		`body(type: json)`
		name4	NAME4	`body("value4", name3)`
		name5	NAME5	`body("value5", name3)`

<?xml version="1.0" encoding="utf-8"?>
<DATA NAME1="value1">
    <NAME2><![CDATA[
        {
            "NAME4": "value4",
            "NAME5": "value5"
        }
    ]]></NAME2>
</DATA>

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.

switch#

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.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ė.

comment#

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

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 siū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, kurios pateikia 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	m	property	type	ref	prepare	level	access	uri
example
			prefix	spinta				https://github.com/atviriduomenys/spinta/issues/
				dsa				https://ivpk.github.io/dsa/
	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

lang#

Nebepalaikoma nuo 0.2 versijos.

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.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.

migrate#

Nebepalaikoma nuo 0.2 versijos.

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	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:

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.
Antrosios migracijos metu buvo įtrauktas naujas duomenų laukas Country.name.
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.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:

migrate.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.

migrate.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.

migrate.delete()#

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

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

migrate.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.