HDD (Hierarchical Data Document) datan määrittely ================================================ Versio 1.0, Juha Lähteenmäki, 13:50 25.6.2002 (korjattu lyhenteen väärä määritelmä 14:38 18.3.2003, Juha) HDD dokumentin yleismääritelmä ============================== (Tämä määritelmä tulee pysymään samana myös tulevissa HDD:n versioissa.) HDD-dokumentti on hierargisen datan tallennukseen tarkoitettu dokumenttiformaatti, jolla pyritään kuvaamaan data ja sen riippuvuussuhteet. HDD dokumentti koostuu mahdollisesta koko dokumenttia kuvaavasta yleisdatasta ja jäsendatasta. Kullakin jäsenellä on oma yksilöllinen tunnisteensa joka liittää sen toisiin jäseniin vähintään jäsenpuun juuritasolla. Jäsenpuussa voi olla tasoja periaatteessa rajaton määrä. Käytännössä tasojen määrä voi HDD-dokumentin toteutustavasta riippuen olla rajoitettu. Tunnisteen lisäksi jokaisella jäsenellä voi olla rajaton määrä jäsendataa. HDD-määrittelyn eri versiot ja toteutustapa voivat kuitenkin rajata jäsendatan muotoa ja määrää. Kussakin HDD-dokumentin määrittelyn versiossa on tarkemmin määriteltävä datan formaatti. Formaatin tulee noudattaa yleisiä hieargisen datan esittämiseen laadittuja standardeja ja de-facto standardeja (esim. XML). Jos dokumenttiformaattiin tulee niin suuria muutoksia että ylöspäin yhteensopivuus ei säily, tulee seuraavan version yhteydessä määritellä myös se, miten edellisen määrittelyn mukaiset dokumentit voidaan muuntaa uuden määrittelyn mukaisiksi. Tämä vaatimus ei kuitenkaan koske sellaisia dokumentin osia joiden mahdollisista yhteensopimattomuus ongelmista on varoitettu edellisen version määrittelyn yhteydessä. HDD-dokumentti ei sinällään ota kantaa datan ulkoasuun. Dokumentin yleisdatan yhteydessä voi kuitenkin olla ohjeellista informaatiota siitä miten dokumentin eri tasot tulisi esittää. Myös jäsendatan yhteydessä voi olla jäsenen ja sen alijäsenten esittämiseen liittyviä ohjeita. Nämä ohjeet ovat nimensä mukaisesti kuitenkin vain ohjeellisia eikä niitä ole pakko huomioida datan esittämisen yhteydessä. Itse datan sisältöön HDD-dokumentti ei luonnollisesti ota kantaa (muutoin kuin mahdollisten muotorajoitusten osalta) 1) Termit ja merkinnät: ========================= Seuraavilla termeillä ja merkinnöillä on tässä dokumentissa erikoismerkitys: ... (kolme pistettä peräkkäin tai allekkain) ''''''''''''''''''''''''''''''''''''''''''''' rajaton määrä muuta sisältöä jonka muotoa rajoittaa xml-formaatti ja muut tässä dokumentissa ja tähän dokumenttiin liittyvissä dokumenteissa kuvatut säännöt. single_sub_element ''''''''''''''''''' xml:n elementti jolla ei ole omia alielementtejä tai attribuutteja, single_sub_element:n tagin täytyy olla yksilöllinen isäelementtinsä sisällä. father_sub_element '''''''''''''''''' xml:n elementti jolla on omia alielementtejä tai attribuutteja. Alielementit ja attribuutit voivat olla periaatteessa mitä tahansa paitsi tässä dokumentissa tai siihen liittyvissä dokumenteissa varattuja elementtejä. Jokaisella Alielementillä on name property jonka arvo on yhdessä tagin kanssa yksilöllinen sen oman isäelementin sisällä. 2) HDD-version 1 tarkempi formaatti ================================ HDD-versio 1 formaatti noudattaa xml-standardia (de facto) ja datan muodon sekä sisällön tulee olla tämän mukaista. 3)Dokumentin rakenteen kuvaus ja pakolliset elementit/attribuutit: ================================================ Jokaisessa HDD-dokumentissa ylimmällä tasolla on elementti. Kaikki muut elementit ovat tämän elementin sisällä. Jokaisessa HDD-dokumentissa on elementin lapsena elementti. Members elementin alla voi olla 0:sta n:ään member elmenttiä. elementin lisäksi elementin alla voi olla 0:sta n:ään muuta elementtiä jotka ovat xml:n sallimaa muotoa. Erikoisasemassa on mahdollinen project- elementti joka on toistaiseksi rajattu tulevien HDD-versioiden käyttöön. Tästä syystä project -elementin käyttöä ei suositella doc elementin alla, mahdollisten tulevien versioiden yhteensopimattomuusongelmien vuoksi. Mikäli tätä elementtiä kuitenkin käytetään jossain dokumentissa ko. dokumentti ei ole todennäköisesti muunnettavissa seuraavan HDD-version kuvaamaan muotoon. Esim. yksinkertaisin mahdollinen HDD-dokumentti: 4) Rajatut elementit/attribuutit ======================= Tässä määritellyt elementit eivät ole pakollisia (oletusarvot joko sovelluskohtaisia tai määritelty alla) mutta jos niitä käytetään, niiden käytön on oltava alla esitetyn kuvauksen mukaista. member-elementti ''''''''''''''''' Member elementti on members elementin father_sub_element jonka tagi on member ja jolla father_sub_element:n määrittelyn mukaan on aina yksilöllinen name attribuutti. Name attribuutista ilmenee member elementin tyyppi ja taso. Tätä kautta se myös sitoo ko. member elementin muihin member elementteihin. MemberElementin tyypin kuvaava id on aina name:n alussa ja erotettu muusta nimestä kaksoispisteellä (:) tästä syystä : ttä ei sallita käytettäväksi name attribuutissa muuhun tarkoitukseen. member-elementin sijainti jäsenhierargiassa on kuvattu koostamalla nimi hierargiatasojen yhdistelmästä ja erottelemalla kukin jäsenhierargian taso toisistaan pisteellä (.) Esim. TyyppiId:Liikkuminen.Auto.Volvo.S40 . Jokaista hierargiatasoa vastaten ei tarvitse olla omaa member -elementtiä. Tällöin jätetään kuitenkin sovelluskohtaisen tulkinnan varaan se, onko kyseessä erillinen taso jota vastaten ei ole omaa dokumentaatiota vai onko kyseessä tason nimi joka yksinkertaisesti sisältää pisteitä. Esimerkiksi jos edellisen TyyppiId:Liikkuminen.Auto.Volvo.S40 jäsenen lisäksi löytyy jäsen TyyppiId:Liikkuminen.Auto.Volvo mutta ei muita jäseniä (TyyppiId:Liikkuminen.Auto ja TyyppiId:Liikkuminen) jää sovelluskohtaisesti tulkittavaksi onko elementin nimeltä "S40" isäelementin nimi "Volvo" vai "Liikkuminen.Auto.Volvo". Määrittely rajoittaa tulkintatapaa kuitenkin sen verran, että tavan on oltava yhtenäinen (siis aina sama) koko dokumentin sisällä. Myös kaarisuluilla () on erityismerkitys nimen kannalta. Sulkujen sisällä olevaa nimenosaa ei nimittäin ollenkaan analysoida vaan se liitetään sellaisenaan nimihierargiaan Esim. TyppiId:Liikkuminen.Auto.Volvo.S40(Polttoneste.Bensa) jäsenen nimenä olisi edellisen esimerkin ehdoilla S40(Polttoneste.Bensa) eikä Bensa). Suluilla voidaan siis antaa nimeen liittyviä lisämääreitä jotka tarkentavat nimeä vaikuttamatta kuitenkaan nimihierargian tasorakenteeseen. Tämä antaa sovelluskohtaisen mahdollisuuden mm. esittää jäsenten välisiä riippuvuussuhteita jo nimen yhteydessä muullakin kuin hierargisen puurakenteen avulla. Huomaa että sulkujen sisällä oleva data lasketaan osaksi yksilöllistä nimeä eli TyppiId:Liikkuminen.Auto.Volvo.S40(Polttoneste.Diesel) on eri jäsen kuin TyppiId:Liikkuminen.Auto.Volvo.S40(Polttoneste.Bensa). Tässä HDD:n versiossa ei kuitenkaan oteta kantaa sulkujen sisällä olevan datan rakenteeseen vaan sen analyysi jää sovelluskohtaisesti ratkaistavaksi. Tulevassa HDD:n versiossa ko. datalle saattaa kuitenkin tulla rakenteellisia vaatimuksia minkä johdosta datan yhteensopivuutta ():ja käytettäessä ei tuleviin versioihin taata. name attribuutin lisäksi kullakin member-elementillä voi olla 0:sta - n:ään muuta attribuuttia ja/tai elementtiä joista elementit voivat olla sekä father_sub_element että single_sub_element tyyppiä. Tiettyyn tarkoitukseen rajatut elementit/attribuutit on listattu seuraavaksi: HDD-formaatin 1.0 versio rajaa seuraavat member elementin alla olevat elementit määriteltyyn käyttöön. summary '''''''''''''''''''''''''' Tyyppi: single_sub_element Kuvaus: Sanallinen yhteenveto memberistä (ei pituusrajaa) Oletusarvo: tyhjä string Esim: yhteenveto comment_visibility ''''''''''''''''''''''''''''''''''''''''''''''''''' Tyyppi: single_sub_element Kuvaus: memberin näkyvyyden tyyppi (esim. private, public, protected, internal) Pituusraja: 50 merkkiä Oletusarvo: Rajattava sovelluskohtaisesti Huom: Sallitut tyypit rajattava sovelluskohtaisesti esim: private image_url '''''''''''''''''''''''''''' Tyyppi: single_sub_element Kuvaus: memberiin liittyvän kuvan URL (esim. luokkakaavio) Oletusarvo: tyhjä string Huom: Sovelluskohtaisesti voidaan sallia myös suhteelliset URL:t esim: http://jokuhost/jokuImage.png image_text '''''''''''''''''''''''''''''''' Tyyppi: single_sub_element Kuvaus: memberiin liittyvään kuvan joka on määritelty image_url -elementillä liittyvä teksti Oletusarvo: tyhjä string Rajoitteet: image_text elementti ei saa määrittelyn mukaisissa dokumenteissa esiintyä ilman image_url elementtiä. esim: Luokkakaavio Lisäksi sovelluskohtaisesti voidaan tehdä muita rajauksia mutta näiden yhteensopivuutta Hdd:n tulevien versioiden kanssa ei taata. 5) Dokumentin rakenteen yhteenveto: =================================== HDD-dokumentti 1.0 on edellä esitetyn kuvauksen mukaisesti seuraavaa muotoa: yhteenveto private http://jokuhost/jokuImage.png Luokkakaavio . . . value ... . . . . . . . . . 5) Muut tähän dokumenttiin littyvät dokumentit =============================================== -