JHS 170 XML-scheman för den offentliga förvaltningen

JHS 170 XML-scheman för den offentliga förvaltningen Version: 1.2 5.10.2012 Publicerad: 30.3.2009 I kraft t.o.m. Tills vidare Innehåll 1 Inledning... 2 2 Tillämpningsområde... 2 3 Termer och definitioner... 3 4 Kopplingen mellan terminologiarbete och XML-scheman... 3 5 Namngivning av XML-strukturer... 3 5.1 Allmänna regler för namngivning... 5 5.2 Namngivning av element... 5 5.3 Namngivning av attribut... 6 5.4 Namngivning av typer... 6 5.5 Allmänna förkortningar... 6 5.6 Förekomster (Representation Terms)... 7 6 Grundläggande anvisningar för bildandet av scheman... 8 6.1 Element eller attribut... 8 6.2 Typdefinitioner... 8 6.3 Förekomsternas motsvarighet inom datatyperna... 9 6.4 Globala definitioner... 10 6.5 Värdelistor... 10 7 Namngivning av namnrymder (namespaces)... 11 8 Moduleringsmöjligheter och schemahierarki... 11 8.1 Basmodell för modulär uppbyggnad av scheman... 11 8.2 JHS-schemat för atomära element- och typdefinitioner... 12 8.3 Sammandragsscheman... 13 8.4 Gränssnittsscheman... 13 8.5 xs:import-definitioner i scheman... 14 8.6 Hierarkiska XML-träd... 14 9 Versionshantering av scheman... 14 9.1 Versionshantering av myndighetsgemensamma scheman inom den offentliga förvaltningen... 14 9.2 Versionshantering av organisationsspecifika scheman... 14 10 Teckenuppsättning... 15 11 Vägledning... 15 12 Bilagor... 15 1/15

1 Inledning I denna JHS-rekommendation ges anvisningar för produktion och hantering av XML-scheman inom den offentliga förvaltningen. I rekommendationen beskrivs gemensamma principer för bildande av XML-scheman inom den offentliga förvaltningen. Utöver detta har man utarbetat en preliminär katalog innehållande scheman som är gemensamma för ett flertal parter inom den offentliga förvaltningen. Rekommendationen baserar sig till tillämpliga delar på internationella standarder och välkända rekommendationer, vilka används som referens. Centrala utgångspunkter för rekommendationen är att den skall vara enkel och praktisk. Tillämpning av internationella standarder som sådana är inte att rekommendera. I stället har man strävat efter att finna sådan praxis som lämpar sig bäst med tanke på den offentliga förvaltningen i Finland. En parallell målsättning är att säkerställa en så god kompatibilitet som möjligt med internationella standarder. De XML-teknologier och XML-schemateknologier som rekommendationen hänvisar till baserar sig på rekommendationer från W3C: http://www.w3.org/xml/ och http://www.w3.org/xml/schema. Produktionen av XML-scheman är nära förknippad med terminologiarbete (ordlistor). Denna rekommendation MÅSTE följas då man härleder XML-strukturer ur icke-teknikspecifika begrepp i ordlistorna. I denna rekommendation används följande termer såsom de definieras av IETF (Internet Engineering Task Force) (RFC 2119 [3]). http://www.ietf.org/rfc/rfc2119.txt. MÅSTE (MUST) FÅR INTE (MUST NOT) OBLIGATORISK (REQUIRED) BORDE (SHOULD) BORDE INTE (SHOULD NOT) FÅR (MAY) VALFRI (OPTIONAL) Om organisationen vill att dess XML-scheman följer denna JHS-rekommendation, MÅSTE de krav som framställs i rekommendationen uppfyllas. På längre sikt förutsätter kompatibilitet mellan olika system att flere organisationer utarbetar XML-scheman i enlighet med de krav som rekommendationen innehåller. 2 Tillämpningsområde I rekommendationen presenteras gemensamma principer för framställning av XML-scheman inom den offentliga förvaltningen. Rekommendationen innehåller även en preliminär lista på scheman som är till för flere olika aktörer inom den offentliga förvaltningen. Rekommendationens målgrupper utgörs av: systemutvecklare inom den offentliga förvaltningen ledning och sakkunniga inom systemutvecklingsprojekt 2/15

3 Termer och definitioner XML Rekommendation av W3C för presentation av strukturerad information i elektronisk form. XML-schema Rekommendation av W3C gällande definitionen av struktur och innehåll i XML-dokument. 4 Kopplingen mellan terminologiarbete och XML-scheman Med terminologiarbete avses de metoder och det praktiska arbete, som används för utveckling av ordlistor som befrämjar semantisk kompatibilitet. Med vokabulär avses en lista på ord som är tillåtna i ett visst språk. Listan innehåller även klassificeringar, definitioner samt beskrivningar och exempel på dessa ord. Ordlistorna beskriver begreppens betydelser på så sätt att olika informationssystem kan förstå den information de behandlar. Utgångspunkten är att ordlistorna är teknologioberoende. Olika tekniska beskrivningssätt s.s. XML-scheman kan härledas ur ordlistorna. Produktionen av XML-scheman BORDE börja med att definiera begreppen i vokabulären eller med att utnyttja redan definierade begrepp. Förvaltningen och de tekniska lösningarna för uppbevaring av ordlistor och XML-scheman BORDE utvecklas så att dessa stöder produktionen av scheman som sker med vokabulärens begrepp som utgångspunkt. I denna rekommendation ges inga råd med tanke på definitionerna i ordlistorna. De som utarbetar scheman BORDE beakta de linjer som dras i denna rekommendation, till den del dessa berör härledningen av XMLscheman ur begrepp som vokabulären innehåller. 5 Namngivning av XML-strukturer Vid namngivning av XML-strukturer stöder man i tillämpliga delar på internationella standarder. Utgångspunkten för namngivningsanvisningarna är ISO 11179-5 standarden (Information technology - Specification for standardization and registration of data elements and associated metadata - Part 5: Naming and identification principles). Namngivningen baserar sig på namngivningsmodellen i tre nivåer som ISO 11179-5 innehåller. Namnet som identifierar ett dataelement som namngivits enligt standarden, består av tre delar, nämligen Objektklass, Egenskapsterm och Förekomst som refererar till Egenskapstermens datatyp. (De motsvarande termerna på engelska är Object class, Property term och Representation term.) Objektklassen identifierar ett objekt eller en funktion i ett visst sammanhang. I klass- eller objektbaserade modeller skulle Objektklasserna kallas för klasser. Egenskapstermen identifierar en egenskap hos ett objekt. I klass- eller objektbaserade modeller skulle Egenskapstermerna kallas för klassernas attribut. Förekomsten definierar på vilket sätt en viss egenskaps datatyp förekommer. Dessutom FÅR man använda Bestämningar (Qualifier) för att specificera var och en del. Nedan finns ett exempel på hur ett namn bildas. Namnets olika delar har separerats med punkt.. 3/15

Objektklass Egenskapsterm Förekomst Formen som presenteras ovan är den tekniska term som används för ett begrepp som finns beskrivet i vokabulären. Då man av en teknisk term i vokabulären bildar ett JHS-elementnamn som används i ett XMLschema, avgränsar man Objektklassen, varefter Egenskapstermen och Förekomsten kombineras med varandra. Om ordet i slutet av egenskapstermen är identiskt med Förekomsten, kan man avlägsna det överlappande ordet. Namnet som bildas slutar då med Förekomsten, som börjar med stor bokstav. JHSelementnamnet som härletts ur den ovan illustrerade tekniska termen som finns i vokabulären är således: SukuNimi Användningen av bestämning klargörs av begreppexemplet Henkilön edellinen sukunimi ( Personens tidigare efternamn ). Den tekniska termen i vokabulären som motsvarar begreppet skulle vara: Henkilo. Edellinen_ Sukunimi. Nimi I den tekniska termen ovan utgörs bestämningen av Edellinen (Tidigare), som specificerar Egenskapstermen Sukunimi (Efternamn). Som avgränsare för bestämningen används understreck _. Motsvarande JHS-elementnamn skulle således bli: EdellinenSukuNimi Tabellen nedan innehåller exempel där man har beskrivit begreppet, den motsvarande tekniska termen i vokabulären, samt JHS-elementnamnet som härletts ur detta. Begreppet och den tekniska termen kan ha olika böjning. T.ex. är Henkilo. Kuolema. Pvm den tekniska termen som bildats av tabellens begrepp Kuolinpäivä (Dödsdag). Begrepp Teknisk term i vokabulären JHS-elementnamn Henkilötunnus (Personbeteckning) Henkilo. Henkilotunnus. Tunnus HenkiloTunnus Etunimet(Alla förnamn) Henkilo. Etunimet. Nimi EtunimetNimi Sukunimi(Efternamn) Henkilo. Sukunimi. Nimi SukuNimi Turvakielto (Säkerhetsförbud) Henkilo. Turvakielto. Kytkin TurvakieltoKytkin Kuolinpäivä (Dödsdag) Henkilo. Kuolema. Pvm KuolemaPvm Kadun nimi (Gatunamn) Osoite. Katu. Nimi KatuNimi Postinumero (Postnummer) Osoite. Postinumero. Koodi PostinumeroKoodi 4/15

Objektklassen som avgränsats från vokabulärens tekniska term BORDE utgöra JHS-elementens överordnade element i en XML-struktur som motsvarar XML-schemat. Nedan finns ett exempel på XML-strukturer inom vilka JHS-elementen har inkluderats i de överordnade elementen som motsvarar objektklasserna. <Henkilo> <SukuNimi>Meikäläinen</SukuNimi> <EtunimetNimi>Matti Juhani</EtunimetNimi> <HenkiloTunnus>111111-1111</HenkiloTunnus> <TurvakieltoKytkin>False</TurvakieltoKytkin>... <!-- Övriga underordnade element till elementet Henkilo -->... </Henkilo> <Osoite> <KatuNimi>Kotikatu</KatuNimi> <PostinumeroKoodi>99999</PostinumeroKoodi>... <!-- Övriga underordnade element till elementet Osoite -->... </Osoite> 5.1 Allmänna regler för namngivning Namn på element och attribut BORDE främst stå på finska. Vid behov FÅR man översätta namnen till engelska. Dessa namn kan användas i engelskspråkiga scheman. Inom samma schema BORDE INTE användas namn på både finska och engelska. Ifall någon bransch använder sig av engelskspråkiga scheman som baserar sig på internationell standardisering, är det naturligtvis tillåtet och ofta även obligatoriskt att använda sig av dessa. Namnen MÅSTE innehålla substantiv, verb och adjektiv i skriftspråksform. Utgångspunkten är att substantiven MÅSTE stå i singularis, om inte begreppet i sig är i pluralis. I XML är både stora och små bokstäver skiftlägeskänsliga (case-sensitive). Detta betyder att t.ex. följande namn inte är identiska: KATUNIMI, katunimi, KatuNimi, katunimi Skandinaviska tecken FÅR INTE användas för element-, attribut- och typnamn i XML-meddelanden. Däremot FÅR skandinaviska tecken förekomma i innehållet i XML-meddelanden. Man FÅR INTE använda understreck ( _ ), punkt (. ), bindestreck ( - ) eller övriga tecken som inte tillhör alfabetet i element-, attribut- och typnamn. Siffror (0-9) FÅR användas. Samtliga namn på element, typer och attribut MÅSTE skrivas ihop. 5.2 Namngivning av element Elementnamnen MÅSTE följa s.k. Upper Camel Case -stil. Den första bokstaven i alla ord i namnet skrivs med stor bokstav. Orden skrivs ihop, exempelvis: HenkiloTunnus KatuNimi 5/15

5.3 Namngivning av attribut Attributnamnen MÅSTE följa s.k. lower Camel Case -stil. Den första bokstaven i alla ord i namnet utom det första skrivs med stor bokstav. Orden skrivs ihop, exempelvis: kielikoodi 5.4 Namngivning av typer Härledda datatyper som definierats av användarna MÅSTE följa s.k. Upper Camel Case -stil. Den första bokstaven i alla ord i namnet skrivs med stor bokstav. Orden skrivs ihop. Man MÅSTE lägga till ändelsen Tyyppi i slutet av namnet, exempelvis: HenkiloTunnusTyyppi I engelskspråkiga scheman MÅSTE man lägga till ändelsen Type i slutet av typnamnet. 5.5 Allmänna förkortningar Med förkortningar förstås allmänt använda eller kända förkortningar som används i syfte att märkbart förkorta det ursprungliga ordet. En förkortning kan förekomma var som helst i namnet. Förkortningar MÅSTE skrivas med stora eller små bokstäver i enlighet med det typiska sättet på vilka de används. I listan på förkortningar nedan presenteras de mest allmänt förekommande förkortningarna i den form de skrivs. Förkortningarna MÅSTE användas i namn på de ställen där respektive ord förekommer. Som källa för listan har man använt listan på förkortningar som publicerats av Forskningscentralen för de inhemska språken (http://www.kotus.fi/index.phtml?s=2149). Förkortning ALV ATK BKT CV db Dnro EU ICT ISBN ISSN JNro Km Kv Förklaring arvonlisävero (Mervärdesskatt, MOMS) automaattinen tietojenkäsittely (automatisk databehandling) bruttokansantuote (bruttonationalprodukt) lat. curriculum vitae (meritförteckning) Desibeli(ä) (decibel) diaarinumero (diarienummer) Euroopan unioni (Europeiska unionen) engl. information and communication technology (informationsoch kommunikationsteknik) engl. International Standard Book Number, (det internationella standardnumret på en bok) engl. International Standard Serial Number, (det internationella standardnumret på en tidskrift) järjestysnumero (ordningsnummer) kilometri(ä) (kilometer) Kansainvälinen (internationell) 6/15

Max Min Nro Oy Oyj Puh Pvm Srk Tmi URL Vrk maksimi, korkeintaan, enintään (maximum, högst) minimi, vähintään (minimum, minst) Numero (nummer) Osakeyhtiö (aktiebolag) julkinen osakeyhtiö (publikt aktiebolag) Puhelin (telefon) Päivämäärä (datum) Seurakunta (församling) Toiminimi (firma) engl. uniform resource locator (identifieraren för en fil eller ett arkiv på internet, vilken även behövs för protokollet som möjliggör användning av filen eller arkivet (t.ex. http://www.jhs-suositukset.fi)) vuorokausi, vuorokautta (ett eller flera dygn) Som målsättning BORDE XML-elementnamn härledas ur begrepp i vokabulären. Elementnamnen BORDE huvudsakligen vara identiska med motsvarande begrepp i vokabulären. Om en förkortning används i vokabulären MÅSTE samma förkortning användas även i XML-schemat. Förkortningar av organisationers namn BORDE underhållas centraliserat. Dessa har inte beskrivits i tabellen ovan, med undantag av de allra mest allmänt förekommande förkortningarna av organisationer (t.ex. EU). I denna rekommendation dras inte upp riktlinjer för vilka parter som skulle ansvara för förkortningarna av olika organisationers namn. 5.6 Förekomster (Representation Terms) Förekomst (Representation Term) är en term som fogas till slutet av ett elementnamn. Denna term beskriver typen av innehåll i elementet. Förekomsten MÅSTE fogas till slutet av ett element som kan innehålla data. Term Term på engelska Användningsändamål Aika Time Klockslag, tidpunkt (ISO 8601) Arvo Value Numeriskt värde Binaari BinaryObject Data i binär form Koodi Code Lista över tillåtna värden. Vart och ett enskilt värde utgörs av en teckensträng som används för att ersätta eller representera värdet eller definitionen på vissa kodade data Kuva Graphic Lagringsformat för grafik 7/15

Kytkin Indicator Ett par bestående av två värden, representerande status on/off (på/av), true/false (sann/osann), osv.(synonym: Boolean ) Lkm Quantity Antal; gäller inte antal penningenheter Mitta Measure Numeriskt värde, som fastställts genom att mäta ett visst objekt. Används tillsammans med måttenhet. Maara Amount Penningmässigt värde i valutaenheter Nimi Name Teckensträng som används för identifiering av ett visst objekt. Till skillnad från en identifierare, behöver namnet inte vara entydigt. Numero Number Nummer Prosentti Percent Numeriskt värde som presenteras i procent Pvm Date Kalenderdatum, tidpunkt (ISO 8601) Hetki DateTime Kalenderdatum och klockslag, tidpunkt (ISO 8601) Suhde Rate Proportion som ett numeriskt värde Teksti Text En teckensträng som förekommer på något naturligt språk Tunnus ID, Identifier En teckensträng som används för att bilda en identitet åt någon förekomst hos objektet, eller för att särskilja denna på ett entydigt sätt ifrån andra förekomster 6 Grundläggande anvisningar för bildandet av scheman 6.1 Element eller attribut I första hand MÅSTE man använda element som representationsstruktur för data i XML-format. Attributen BORDE huvudsakligen innehålla metadata som beskriver värdet i elementets innehåll. 6.2 Typdefinitioner För enkla typdefinitioner av element (SimpleType) MÅSTE man som huvudregel använda grundtyperna som finns i rekommendationen XML Schema av W3C. För definitioner BORDE man använda grundtyperna som finns uppräknade i tabellen nedan. Typ Förklaring Exempel xs:string teckensträng Hushållsarbete xs:integer heltal -123 xs:decimal decimaltal -2.54 8/15

xs:time klockslag 12:00:00 xs:date datum 2006-06-14 xs:datetime Kalenderdatum och klockslag 2006-06-14T12:00:00 xs:boolean sanningsvärde (true/false) true xs:base64binary binärtyp Se: http://www.ietf.org/rfc/rfc2045.txt Utöver detta innehåller rekommendationen XML Schema även andra grundtyper. Man FÅR INTE använda dessa utom i särskilda fall för vilka det bör föreligga vägande skäl. Om man inför nya restriktioner i en grundtyp, MÅSTE man ge denna datatyp ett eget namn (se 5.4 namngivning av typer). 6.3 Förekomsternas motsvarighet inom datatyperna Enkla datatyper i element (SimpleType) inom ett XML-schema MÅSTE framställas i form av grundtyper i rekommendationen XML Schema av W3C. Nedan framställs hur datatyperna och förekomsterna motsvarar varandra. Förekomst Aika (Tid) Arvo (Värde) Binaari (Binär) Koodi (Kod) Kuva (Grafik) Kytkin (Brytare) Lkm (Antal) Mitta (Mått) Maara (Mängd) Nimi (Namn) Numero (Nummer) Prosentti (Procent) Datatyp xs:time xs:decimal xs:base64binary xs:string xs:base64binary xs:string, xs:boolean xs:decimal xs:decimal xs:decimal xs:string xs:decimal xs:decimal 9/15

Pvm (Datum) Hetki (Datum och klockslag) Suhde (Förhållande) Teksti (Text) Tunnus (Identifierare) xs:date xs:datetime xs:decimal xs:string xs:string 6.4 Globala definitioner Alla element och typer MÅSTE definieras som globala. Detta betyder att de MÅSTE definieras på schemats översta nivå under elementet xs:schema. Globala element- och typdefinitioner kan återanvändas. Ändringar i en definition kommer att avspegla sig på alla ställen där det hänvisas till denna. Dessutom är globala definitioner lättare att hitta i schemana, eftersom de inte är inbäddade i övriga definitioner. En planeringsmall (Design Pattern), där samtliga element och typer definieras som globala, kallas för en Garden of Eden -mall. Man refererar till ett globalt element med xs:element-definitionens ref-attribut. Man refererar till en global typ med xs:element-definitionens type-attribut. Nedan finns ett exempel på en referens till en global definition av ett element (EtunimetNimi) och två exempel på en referens till en global definition av en datatyp (EtunimetNimiTyyppi och HenkiloTyyppi). <xs:type name EtunimetNimiTyyppi type xs:string /> <xs:element name="etunimetnimi" type= EtunimetNimiTyyppi /> <xs:complextype name= HenkiloTyyppi > <xs:sequence> <xs:element ref="etunimetnimi"/>... </xs:sequence> </xs:complextype> <xs:element name= Henkilo type= HenkiloTyyppi /> 6.5 Värdelistor Värdelistorna är standardiserade, etablerade eller officiella listor innehållande koder. Värdelistorna upprätthålls vanligen av någon för detta ändamål utnämnd instans. I XML-scheman används värdelistorna till att begränsa elementens tillåtna värden. Exempel på allmänt förekommande värdelistor: Postnummer Landskoder Språkkoder 10/15

Ifall man använder allmänt förekommande, importerade värdelistor för bruk i XML-scheman, MÅSTE någon ansvara för underhållet av dessa. 7 Namngivning av namnrymder (namespaces) Namnrymder i XML definieras av W3C i rekommendationen för namnrymder (Namespaces in XML). Med namnrymder länkar man element och attribut till en entydig kontext. Om två element eller attribut har samma namn, kan man skilja på dessa genom att länka dem till sina respektive namnrymder. Namnrymden beskrivs som en URI-referens. För vart och ett schema MÅSTE man namnge ett targetnamespace. De delar som tillhör definitionen XML Schema specificeras med hjälp av namnrymden http://www.w3.org/2001/xmlschema. Som dess kortnamn MÅSTE man använda förkortningen xs. Namnet på en namnrymd har följande grundstruktur: perusosa/<organisaatiokohtainen rakenne>/vuosi/kuukausi/päivä/ (grunddel/<den struktur som används inom organisationen>/år/månad/dag/) Den grundläggande namnrymden (basdelen) för de XML-scheman som är gemensamma för den offentliga förvaltningen är: http://skeemat.jhs-suositukset.fi/ Inom varje organisation MÅSTE man själv definiera den grundläggande namnrymden för organisationsspecifika XML-scheman. Namnrymdens del <organisaatiokohtainen rakenne> FÅR organisationen bilda själv, eftersom domänerna och användningsområdena är kraftigt förknippade med branschen och organisationen i fråga. <organisaatiokohtainen rakenne> FÅR innehålla flera hierarkiska nivåer, enligt behov. Den organisationsspecifika delen av den offentliga förvaltningens myndighetsgemensamma lista över scheman heter yhteiset. I slutet av namnrymdens namn MÅSTE man märka ut schemats publiceringsdatum. Namnrymden använder datumet till att ange schemats version (se kapitel 9 - Versionshantering av scheman). Till exempel heter namnrymden till den 12.2.2009 publicerade offentliga förvaltningens myndighetsgemensamma lista över scheman: http://skeemat.jhs-suositukset.fi/yhteiset/2009/03/04 Användning av URL-adressen som namn på namnrymden gör det möjligt att använda namnrymden i fysiska hänvisningar till scheman. URL-adressen FÅR användas direkt vid fysisk adressering. Man får dock fritt välja (VALFRITT) om man vill lagra schemat i URL-adressen eller inte. URL-länken BORDE leda till åtminstone beskrivande dokumentation av schemat. 8 Moduleringsmöjligheter och schemahierarki 8.1 Basmodell för modulär uppbyggnad av scheman Med hjälp av modulär uppbyggnad av scheman strävar man efter att effektivt kunna återanvända dessa. De delar av scheman som redan definierats kan användas i ett flertal scheman på högre nivå i hierarkin. 11/15

Målsättningarna med basmodellen för modulär uppbyggnad av scheman är följande: 1. Modellen är tillräckligt enkel för att kunna appliceras i praktiken 2. Modellen är tillräckligt mångsidig, med vilket man strävar efter att minska på systemutvecklarnas arbetsbörda i samband med schemadefinitioner 3. Redan utförda schemadefinitioner kan användas på nytt 4. Schemanas element- och typdefinitioner kan härledas direkt ur begreppen i vokabulären För att scheman flexibelt ska kunna bildas, förutsätts att man inte fixerar styva och komplicerade strukturer i form av separata underliggande scheman. Det är typiskt att t.ex. ordningen på de element som tillhör ett visst schema varierar mellan olika organisationer. Samma sak gäller huruvida elementen är obligatoriska eller inte. Återanvändning av dylika schemadefinitioner leder ofta såväl till ändringar som är specifika för olika organisationer och områden som till inofficiella versioner. Bild 1 avbildar ett exempel på modulär uppbyggnad av scheman. På den högsta nivån finns Gränssnittsscheman. Dessa kan innehålla återanvändbara sammandragsscheman. Gränssnittsscheman och sammandragsscheman kan innehålla scheman med atomära element- och typdefinitioner. Bilden illustrerar ett exempel på ett schema med atomära element- och typdefinitioner (JHSYdin.xsd). I detta schema finns samtliga element- och typdefinitioner som är gemensamma för den offentliga förvaltningen. I regel MÅSTE olika organisationer importera dessa gemensamma atomära definitioner till sina egna scheman. Organisation X Organisation Y Gränssnitts -scheman Sammandrags -scheman JHS-schemat för atomära element- och typdefinitioner Bild 1. Grundmodell för modulär uppbyggnad av scheman Alla organisationer FÅR även definiera sina egna målområdesspecifika element- och typdefinitioner som motsvarande atomärscheman. Olika organisationers egna atomära scheman kan vid behov importera definitioner från JHS-scheman och modifiera dessa så att de motsvarar organisationens behov. 8.2 JHS-schemat för atomära element- och typdefinitioner JHS-schemat för atomära element- och typdefinitioner innehåller de myndighetsgemensamma schemadefinitionerna för den offentliga förvaltningen. En atomär elementdefinition består av en elementdefinition, t.ex.: <xs:element name="henkilotunnus" type="jhs:henkilotunnustyyppi"/> I schemat motsvaras varje atomär elementdefinition av en enkel typdefinition (simpletype), t.ex.: 12/15

<xs:simpletype name="henkilotunnustyyppi"> <xs:restriction base="xs:string"/> </xs:simpletype> Sambandet mellan schemana och begreppen i vokabulären uppstår på så sätt att ett begrepp i vokabulären MÅSTE motsvara antingen en atomär elementdefinition eller motsvarande typdefinition. På detta sätt strävar man efter att säkerställa att gemensamma begrepp används, samt att namngivningen av scheman sker på ett enhetligt sätt inom alla domäner. Vokabulären FÅR även innehålla begrepp som saknar motsvarighet i form av en atomär element- och typdefinition. Varje atomär element- och typdefinition BORDE motsvara ett begrepp i vokabulären. I regel BORDE organisationens interna scheman referera till den centrala elementdefinitionen. Det är lättare att modifiera den atomära definitionen till att motsvara organisationens krav genom att referera till den motsvarande typdefinitionen. Därför FÅR en organisation referera till typdefinitionen i sina interna scheman. Som exempel ser typdefinitionen av efternamn ut på följande sätt i ett XML-schema innehållande atomära definitioner: <xs:simpletype name="sukunimityyppi"> <xs:restriction base="xs:string"/> </xs:simpletype> En organisation får referera till typdefinitionen i JHS-schemat och ändra på denna t.ex. genom att begränsa elementets längd: <xs:simpletype name="sukunimityyppi"> <xs:restriction base="jhs:sukunimityyppi"> <xs:maxlength value="50"/> </xs:restriction> </xs:simpletype> En dylik definition FÅR finnas i en organisations interna schema innehållande atomära element- och typdefinitioner. Om en nybildad datatyps namn är identiskt med en JHS-datatyps namn, separerar man den nybildade typen från den ursprungliga JHS-typen genom att fixera den nya till en namnrymd som organisationen har definierat internt. 8.3 Sammandragsscheman Ett sammandragsschema är ett schema som innehåller den exakta strukturen för någon grupp element som definierats av en viss organisation, en domän, ett projekt, el. dyl. Sammandragsschemat BORDE konstrueras av centrala elementdefinitioner, eller genom att referera till de typdefinitioner som motsvarar dessa. Sammandragsschemat kan innehålla definitioner av elementens inbördes ordning och huruvida elementen är obligatoriska eller inte. I vissa fall kan det vara ändamålsenligt att en organisation definierar exempelvis den exakta strukturen för en adress. Flera gränssnittsscheman inom en organisation kan återanvända ett sådant adresschema. En organisation kan publicera ett återanvändbart sammandragsschema i ett öppet arkiv av scheman. Detta gör sammandragsschemat tillgängligt för övriga organisationer att utnyttja. 8.4 Gränssnittsscheman Ett gränssnittsschema är en teknisk informationsbeskrivning av ett gränssnitt som utvecklats med tanke på en tjänst som någon organisation tillhandahåller, eller i anslutning till ett informationssystem. Mängden gränssnittsscheman består i typiska fall av par bestående av fråga och svar. Ett visst schema beskriver frågan och ett annat beskriver svarsmeddelandet. 13/15

Huvudregeln är att man BORDE referera från gränssnittsscheman till atomära elementdefinitioner eller till typdefinitioner som motsvarar dessa. Man FÅR också referera från gränssnittsscheman till återanvändbara sammandragsscheman. Om man refererar från ett gränssnittsschema till ett sammandragsschema, MÅSTE hänvisningarna till de atomära elementdefinitionerna göras från detta sammandragsschema. I gränssnittsschemana slår man bl.a. fast ordningen på elementen och huruvida de är obligatoriska eller inte. I ett gränssnittsschema MÅSTE atomära elementdefinitioner inkluderas som en del av schemat med hjälp av xs:import-definitioner. 8.5 xs:import-definitioner i scheman Scheman på lägre nivåer MÅSTE inkluderas som en del av ett schema på högre nivå, genom att man använder xs:import-definitioner, t.ex.: <xs:import namespace= "http://skeemat.jhs-suositukset.fi/yhteiset/ 2009/03/04" schemalocation="jhsydin20090304.xsd"/> 8.6 Hierarkiska XML-träd Inom XML-strukturerna för meddelandescheman BORDE man sträva efter så låga hierarkier som möjligt och MÅSTE man undvika onödiga mellanliggande nivåer. Antalet tillåtna nivåer i hierarkin begränsas dock inte exakt. Nivåernas antal är beroende av kraven och datamallens grad av komplexitet. Logiska helheter borde befinna sig inuti ett överordnat element. Nedan exemplifieras hierarkin med hjälp av en XML-instans. <Henkilo> <EtunimetNimi>Matti Juhani</EtunimetNimi> <SukuNimi>Meikäläinen</SukuNimi> <HenkiloTunnus>111111-1111</HenkiloTunnus> </Henkilo> 9 Versionshantering av scheman Versionshanteringen av scheman på olika nivåer innebär utmaningar för de lösningar som används i XMLgränssnittet. Gränssnitten MÅSTE fungera även efter att ändringar har gjorts i schemana. 9.1 Versionshantering av myndighetsgemensamma scheman inom den offentliga förvaltningen För versionshantering av myndighetsgemensamma scheman inom den offentliga förvaltningen MÅSTE man använda den version som finns uttryckt i namnrymden. Namngivningen av namnrymder behandlas i kapitel 7. I samband med varje ändring som sker i schemat, MÅSTE versionen uppgraderas till att motsvara datum för utgivandet av ändringen. 9.2 Versionshantering av organisationsspecifika scheman Ändringar som förutsätter hantering av organisationsspecifika schemaversioner, kan indelas i två grupper: 1. Ändringen inverkar på valideringen av XML-instanser som följer den tidigare versionen av schemat Om ändringen inverkar på valideringen av XML-instanser som följer den tidigare versionen av schemat MÅSTE den nya versionen uttryckas i namnrymdens namn. Namngivningen av namnrymder behandlas i kapitel 7. 14/15

Ett typiskt exempel på en ändring tillhörande grupp 1 är att man tillför schemat en eller flera elementdefinitioner, inom vilka respektive element definieras som obligatoriskt. Ändringen inverkar på valideringen av XML-instanser som följer den tidigare versionen av schemat. Detta beror på att sådana XML-instanser som saknar elementet i fråga, är felaktiga enligt det nya schemat. I dessa fall bör man ändra på schemats huvudsakliga version (namnrymdens namn). 2. Ändringen inverkar inte på validering av XML-instanser som följer den tidigare versionen av schemat Om ändringen inte inverkar på valideringen av XML-instanser som följer den tidigare versionen av schemat, MÅSTE ändringen uttryckas i attributet version i xs:schema-elementet. Numreringen börjar med delversion 1.0. Ett typiskt exempel på en ändring tillhörande grupp 2 är att man tillför schemat en eller flera elementdefinitioner, inom vilka respektive element definieras som en valfri uppgift. Denna ändring inverkar inte på valideringen av XML-instanser som följer den tidigare versionen av schemat, eftersom alla XMLinstanser är valida även enligt det nya schemat. I detta fall behöver man inte byta ut schemats huvudsakliga version. Det räcker att man uttrycker delversionens nummer. När schemat skapas för första gången namnges det både i den huvudsakliga versionens namnrymd och i attributet version i xs:schema-elementet. Schemats första delversion MÅSTE vara 1.0. 10 Teckenuppsättning I XML-scheman och -meddelanden MÅSTE man använda UTF-8 kodning och attributet encoding, som klart och tydligt uttrycker den använda kodningen. 11 Vägledning Denna rekommendation underhålls av JUHTA - Delegationen för informationsförvaltningen i den offentliga förvaltningen, tfn 0295 16001, e-post: jhs-sihteeri@jhs-suositukset.fi JHS-systemets webbsidor: http://www.jhs-suositukset.fi/ 12 Bilagor Bilaga 1: Gemensamt XML-kärnskema för den offentliga förvaltningen (på finska) 15/15