Skráning hugtaka

Þessi kafli lýsir því hvernig skráningu hugtakalíkana er háttað.

Hugtakalíkön innihalda þrjár tegundir skráninga:

• Hugtak — afmarkað fyrirbæri eða eining í viðkomandi umdæmi, t.d. Bygging, Landeign, Staðfang.

• Eigindi hugtaks — mælanleg eða lýsandi stærð hugtaks, t.d. BruttoM2, LandeignNr.

• Vensl á milli hugtaka — tenging milli hugtaka sem lýsir samhengi þeirra, t.d. tenging, alhæfing.

Sérhvert hugtak og eigindi fær stöðugt auðkenni (UUID) við stofnun sem breytist aldrei, jafnvel þótt hugtak sé endurnefnt eða fært á milli umdæma.

Reitir hugtaks

Reitur	Krafist	Lýsing
id	já	Stöðugt UUID. Breytist aldrei.
label	já	Lesanlegt heiti í nefnifalli eintölu.
name	já	PascalCase kóðaheiti.
definition	já	Stutt skilgreining á hugtakinu.
description	já	Lengri lýsing. Má vera tóm eða í sér md-skjali.
abbreviation	nei	Skammstöfun, notuð í gæðaritum og hliðvísunum.
propertyGroups	nei	Nafngreindar flokkar sem eigindi geta tilheyrt.
properties	já	Listi yfir eigindi (að minnsta kosti einn).

Eigindi

Sérhvert eigindi lýsir einni upplýsingu á hugtakinu og ber stöðugt UUID sem breytist aldrei.

Gagnatýpa

type-reiturinn tilgreinir gagnatýpu eigindis:

Gerð	Lýsing
string	Textastrengur.
text	Mjög langur texti þar sem lengd er óþekkt.
int32	32-bita heiltala. Notað fyrir magntölur.
int64	64-bita heiltala. Notað fyrir auðkenni og stóra teljara.
float	Fleytitala.
decimal	Nákvæm tugabrotastala. Notað fyrir mælingar og fjármál.
datetime	Dagsetning og tími með tímabelti (ISO 8601).
date	Dagsetning án tíma (ISO 8601).
boolean	Já/nei.
uuid	Einkvæmt auðkenni (RFC 4122).
geometry	Rúmfræðileg stærð — punktur, lína eða flatarmál.

Skilgreining

Sérhvert eigindi þarfnast skilgreiningar:

Reitur	Krafist	Lýsing
definition	já	Skilgreining eigindis.
purpose	já	Hvers vegna er eigindið til og hvernig það er notað. Má vera í sér md-skjali ef texti er langur.
notes	nei	Viðbótarsamhengi eða skýringar.

Vensl

Vensl lýsa sambandi á milli hugtaka. Hvert vensl hefur stöðugt UUID, gerð og tvo endapunkta (uppruna og markmið).

Gerðir vensla

Hugtök geta verið laustengd eða sterktengt, allt eftir því hvernig sambandi þeirra er háttað.

Gerð	Heiti	Notkun
association	Tenging	Almenn tengsl milli hugtaka
directed-association	Stefnutenging	Einstefna navigable tenging
aggregation	Samansöfnun	Hluti-heild; hlutar geta lifað sjálfstætt
composition	Samsetning	Hluti-heild; hlutar geta ekki lifað án heildarinnar
generalization	Alhæfing	Erfðir / „er-eins-og”
realization	Útfærsla	Uppruni útfærir markmið
dependency	Háð	Uppruni notar eða þarf markmið

Nafngiftir

Tungumál

Hugtak og eigindi eru nefndir á íslensku, í nefnifalli eintölu, með orðalagi viðkomandi fagssviðs. Tæknilegt kóðaheiti (name) er dregið af íslensku heitinu en er sett fram á tölvuvænu formi — sérstafir fjarlægðir og orð skrifuð saman með stórum staf á hverju orði (PascalCase).

label-gildi eru á íslensku — það eru nöfn sérfræðinga á sínu fagssviði. Tæknileg kóðaheiti (name, shortName) eru dregin af íslenskum heitum en eru á tölvuvænu formi, án sérstafa. Upplýsingar sem snúa að tæknilegri útfærslu afurða sem eiga ekki uppruna í hugtakalíkan (t.d. CreatedAt) eru settar fram á ensku, sem er viðurkennt tæknimál. Við útfærslu afurða þarf oft á tíðum að setja saman fagleg vel skilgreind hugtök úr hugtakalíkani og upplýsingar sem snúa að tæknilegri útfærslu. Þá skal nota íslensk heiti úr hugtakalíkani í bland við tæknileg heiti á ensku sem ekki eru í hugtakalíkani.

Nöfn hugtaka skulu alltaf vera sett fram í nefnifalli eintölu við útfærslu afurða en aldrei sem beyging á nafni. Þegar um mörg tilvik af hugtaki er að ræða skal gefa það til kynna með öðrum hætti.

Þrjú nafnasvæði

Hvert hugtak og eigindi hefur þrjár nafnlegar birtingarmyndir:

Reitur	Hlutverk	Dæmi
label	Lesanlegt heiti, eins og það er notað af fagsviði, má innihalda sérstafi og bil	Flatarmál berandi platna
name	PascalCase kóðaheiti (^[A-Z][A-Za-z0-9_]*$) Tölvuvænt án sértákna	Berandiplata_m2
shortName	Skammstafað PascalCase, mest 6 stafir. Notað þar sem pláss er takmarkað	BerPl

Samsett nöfn

Nöfn eru samsett úr hlutum aðskildum með undirstrik: [Forskeyti_] Grunnur [_Skýringarliður_] [_Eining]

Forskeyti, Skýringarliður og Eining eru valkvæm svæði.

Hluti	Tilgangur	Dæmi
Forskeyti	Táknar hugtak sem eigindið tilheyrir	Stf (Staðfang), Baf (Byggingaráfangi)
Grunnur	Aðalviðfang — eining, eiginleiki eða mæling	Flatarmal, Veggop
Skýringarliður	Bætir samhengi við	Berandi (í Berandiplata)
Eining	Mælieining eða hlutverk	_m2, _m3, _nr, _id

Mælieiningar í heitum

Þegar eigindi mælir gildi er mælieiningin kóðuð sem viðskeyti á name. Gildi eru geymd í grunneiningum.

Mæling	Viðskeyti
Metri	_m
Fermetri	_m2
Rúmmetri	_m3
Volt	_v
Amper	_a
Sekúnda	_s
Vatt	_w
Kílóvattstund	_kwh

Hlutverk- og auðkennisviðskeyti

Viðskeyti sem tákna hlutverk eða gerð auðkennis:

Viðskeyti	Merking
_Id	Kerfisauðkenni — UUID eða heiltölu-lykill sem kerfið útbýr
_Nr	Númer — lesanlegt auðkenni, t.d. bygginganúmer eða landeignanúmer
_Fl	Flokkur — flokkun eða tegundarkóði
_Kd	Kóði — kóðagildi úr viðmiðunartöflu
_Sk	Skammstöfun — stytt form til notkunar þar sem pláss er takmarkað

Þegar rík hefð hefur myndast fyrir að sterktengja viðfang og viðskeyti er heimilt að skeyta þeim saman án undirstriks. Dæmi um það er Fasteignanúmer sem mætti setja fram sem FasteignNr, Fasteign_Nr eða FasteignNr_Id eftir atvikum. Raðnúmer mætti setja fram sem RadNr eða Radnr_Id.

Lýsigögn eiginda

Sérhvert eigindi ber fjóra flokka lýsigagna sem lýsa hlutverki þess og hegðun.

Auðkenni

Lýsir hlutverki eigindis sem auðkenni.

Reitur	Flagg	Merking
key	PK	Aðallykill. Einstakt kerfisauðkenni hvers færslu. Nákvæmlega eitt eigindi á hverju hugtaki á að hafa key: true.
ck	CK	Varalykill. Annað einkvæmt auðkenni sem gæti þjónað sem aðallykill en gerir það ekki. Dæmi: ByggingNr er einkvæmt og merkingarbært en kerfið notar ByggingId sem aðallykilinn.
fk	FK	Ytri lykill. Vísar í eigindi annars hugtaks. Þegar fk: true þarf að tilgreina references með heiti markhugtaks og eigindis.
unique	UNIQUE	Einkvæmt auðkenni. Engar tvær færslur mega deila sama gildi. Aðal- og varalyklar eru alltaf einkvæmir en eigindi getur verið einkvæmt án þess að vera lykill.
opaque	OPAQUE	Upplýsingalaust auðkenni. Gildið ber enga innbyggða merkingu — ekki hægt að túlka eða þátta það. Dæmi: sjálfvirkt raðnúmer (1024) er ómerkt; skipulagt kóðaheiti (B-00512) er það ekki.

Tegund

Lýsir því hvort eigindið taki gildi úr föstu mengi eða hafi sérstakan kóða.

Reitur	Flagg	Merking
code	CODE	Kóðagildi. Lesanlegt auðkenni þar sem bygging eða snið ber merkingu. Kóðar eru stöðugir og notaðir til uppflettingar. Dæmi: B-00512 (bygginganúmer), IS-101 (póstnúmer).
enum	ENUM	Upptalið gildi. Takmarkað við fyrirfram skilgreint mengi leyfilegra gilda, skilgreint í viðmiðunartöflu eða kóðalista. Dæmi: tegund byggingar (Einbýli, Fjölbýli, Raðhús).

Eigindi getur verið bæði code og enum, hvorugt, eða annað hvort.

Hegðun

Lýsir því hvernig gildi eigindis myndast og er stjórnað.

Reitur	Flagg	Merking
system	SYSTEM	Kerfistýrt. Gildið er sett eða viðhaldið af kerfinu.
user	USER	Notandainntak. Gildið er slegið inn eða valið af notanda.
derived	DERIVED	Reiknað. Gildið er reiknað út frá öðrum eigindum, t.d. heildarmæling = summa hlutmælinga.
virtual	VIRTUAL	Sýndargildi. Gildið er ekki geymt — það er reiknað þegar þess er óskað.
internal	INTERNAL	Innra gildi. Notað innan kerfis og ekki birt utanaðkomandi notendum eða opinberum viðmótum.
volatile	VOLATILE	Óstöðugt gildi. Gildið getur breyst tíðum og án fyrirvara. Notendur ættu ekki að geyma það í skyndiminni.

Eigindi getur borið fleiri en eitt flagg, t.d. bæði system og user ef kerfið gefur sjálfgefið gildi en leyfir notanda að breyta því.

Þvinganir

Lýsir gildisprófunum og sjálfgefnum gildum.

Reitur	Flagg	Gerð	Merking
nullable	NULLABLE	boolean	Leyfir tómt. Eigindið má vera án gildis.
required	REQUIRED	boolean	Skyldugildi. Gildi verður að fylgja þegar færsla er stofnuð.
auto	AUTO	boolean	Sjálfvirkt. Kerfið myndar gildið sjálfkrafa, t.d. raðnúmer eða tímastimpill.
default		string, tala, boolean eða null	Sjálfgefið gildi. Notað þegar ekkert gildi er gefið upp. Tómt svæði ef ekkert sjálfgefið gildi er til. Hvaða stýrigildi sem er — þar á meðal null — er gilt sjálfgefið gildi.