Navngiving- og Design Regler. for. Felles XML-Skjema i Bærum Kommune

BÆRUM KOMMUNE BK BEDRIFTER DATA Navngiving- og Design Regler for Felles XML-Skjema i Bærum Kommune Versjon: 1.0 Dato: 2009-01-20 Side 1 av 10

Innholdsfortegnelse Endringskontroll... 3 BKXML liste over representasjonstermer... 9 Toppdomener i tjenestekatalogen... 10 Side 2 av 10

Endringskontroll Versjon Dato Utført endring Endring 0.1 24.11.2008 ØAa Dokument opprettet 0.2 28.11.2008 ØAa Utkast av regler for skjema komplett 0.3 01.12.2008 ØAa Lagt til utkast av regler for WSDL 0.4 03.12.2008 ØAa Lagt til domenenavn fra arkitekturprinsipper 0.5 08.12.2008 ØAa Lagt til regler for WSDL. Endret rekkefølgen for namespace termer. 0.6 11.12.2008 ØAa Rettet skrivefeil 0.7 20.01.2009 ØAa Lagt til felt for regeltittel og tatt inn endringsforslag fra rbr 1.0 20.01.2009 ØAa/Lcf Release 1.0 Side 3 av 10

Regel Regeltittel Formulering BKXML regler BKXML-1 Gjenbruk av eksisterende BKXML elementer og typer Et BKXML-skjema SKAL, der hvor det er mulig, gjenbruke eksisterende elementer eller typer som allerede er godkjent i BKXML. BKXML-2 Gjenbruk av innebygde enkle typer Et BKXML-skjema SKAL gjenbruke innebygde enkle typer i XML Schema fremfor å definere egne typer til å representere samme informasjon. BKXML-3 Gjenbruk av element fremfor Et BKXML-skjema BØR gjenbruke et element fremfor dets type hvis BKXML-4 type Gjenbruk av seneste skjemaversjon elementets navn og anvendelse er entydig i den konkrete sammenheng. Et BKXML-skjema SKAL gjenbruke nyeste versjon av et annet eksisterende BKXML-skjema, hvis det andre skjema finnes i flere versjoner. BKXML-5 Et BKXML-skjemas innhold Et BKXML-skjema SKAL inneholde èn elementdeklarasjon, og hvis ikke elementet gjenbruker en eksisterende type fra et annet skjema, èn typedefinisjon for elementet. I tillegg kan et skjema inneholde en eller flere definisjoner av støttetyper hvis disse er nødvendige for å etablere elementets type. Hvis et skjema definerer en abstrakt type skal det ikke inneholde en elementdeklarasjon. BKXML-6 Skjemareferanser En BKXML-skjemaavlevering SKAL i sine enkelte skjema alltid referere til, enten allerede godkjente BKXML-skjema, nye skjema tilhørende den nye avleveringen eller til godkjente eksterne skjema (for eksempel skjemaer som allerede er etablerte som standard) BKXML-7 BKXML-skjemaer i Et BKXML-skjema SKAL plasseres i InfostrukturBiblioteket. InfostrukturBiblioteket BKXML-8 Systemuavhengige BKXML-skjemaer Utformingen av et BKXML-skjema skal ikke være påvirket av struktur eller begrensninger i bakenforliggende fagsystem. BKXML-9 Klare og entydige skjemaer Et BKXML-skjema SKAL designes så enkelt og entydig som mulig, uten unødvendig kompleksitet eller overflødige konstruksjoner. Generelle XML skjema regler BKGXS-1 Valg av skjemaspråk Et BKXML-skjema SKAL defineres i overensstemmelse med W3C XML Schema anbefalingen (versjon 1.0) av 2. mai 2001: XML Schema part 1: Structures og XML Schema Part 2: Datatypes. BKGXS-2 Versjon av XML Et BKXML-skjema SKAL anvende versjon 1.0 av W3C XML anbefalingen av 4. februar 2004: Extensible Markup Language (XML) 1.0 (Third Edition). BKGXS-3 Valg av encoding scheme Et BKXML-skjema SKAL anvende UTF-8 som encoding scheme. BKGXS-4 Tilknytning til namespace Et BKXML-skjema SKAL tilknyttes et namespace. BKGXS-5 Skjemareferanser Et BKXML-skjema SKAL benytte include konstruksjonen for å referere til andre skjema i samme namespace og import konstruksjonen for å referere til skjema i andre namespace enn skjemaets eget targetnamespace. BKGXS-6 Bruk av redefine Et BKXML-skjema SKAL IKKE benytte redefine konstruksjonen. BKGXS-7 Bruk av notation Et BKXML-skjema SKAL IKKE benytte notation konstruksjonen. BKGXS-8 Bruk av schemalocation Et BKXML-skjema SKAL angi alle dets schemalocation attributter med en absolutt og gyldig URL til det refererte skjemas plassering. BKGXS-9 Bruk av key, keyref eller unique Et BKXML-skjema SKAL IKKE benytte konstruksjonene key, keyref eller unique. Generelle navngivigsregler BKGNR-1 Unik navngiving Et BKXML-skjema SKAL navngi alle dets globale elementer og typer unikt innenfor sitt namespace, og bør navngi unikt også innenfor alle BKXML-skjema. BKGNR-2 Navngivningsmodellen for elementer, attributter og typer Et BKXML-skjema SKAL navngi alle sine globale og lokale elementer, typer og attributter etter ObjektEgenskapRepresentasjon navngivningsmodellen som presiseres i følgende underregler. BKGNR-2a Termen Objekt Et navn SKAL i sin Objekt term beskrive det dataobjekt som et element og dets type representerer i en bestemt sammenheng. Side 4 av 10

BKGNR-2b Utelatelse av termen Objekt Et navn KAN utelate sin Objekt term i de tilfeller hvor et element og dets type opptrer i kontekst av et objekt, eller der objektet er ukjent. BKGNR-2c Termen Egenskap Et navn SKAL i sin Egenskap term, ved hjelp av ett eller flere kvalifiserte ord beskrive en fremtredende egenskap ved et element og dets types Objekt term. BKGNR-2d Termen Representasjon Et navn SKAL i sin Representasjon term beskrive et element og dets types representative kategori. Representasjon termen SKAL anta en av verdiene i BKXML s liste over godkjente representasjonstermer. BKGNR-2e Synonyme termer Et navn SKAL, hvis det har en frase i termen Egenskap som er synonymt med en frase i termen Representasjon, fjerne frasen fra Egenskap og beholde den i Representasjon. BKGNR-2f Entallsform av termer Et navn SKAL angis på entallsform, med mindre navneordet er en flertallsform. BKGNR-2g Forkortelser og akronymer Et navn BØR IKKE benytte forkortelser og akronymer, med mindre disse er de vanligst brukte termer. BKGNR-2h Anvendelse av tegn Et navn SKAL IKKE inneholde annet enn bokstaver og tall. Bruk av språk BKLNR-1 Bruk av norsk språk Et BKXML-skjema SKAL navngi alle sine globale og lokale elementer, attributter og typer på norsk bokmål. BKLNR-2 Språkangivelse med xml:lang Et BKXML-skjema SKAL i sitt xml:lang attributt i elementet schema ha verdien NB. BKLNR-3 Ord- og fagbøker Navngiving i et BKXML-skjema SKAL skje i henhold til Norsk rettskrivingsordbok eller relevante fagbøker. BKLNR-4 Bruk av Æ, Ø og Å Et BKXML-skjema SKAL IKKE anvende de norske spesialtegnene æ, ø, å, Æ, Ø eller Å. Som alternativ benyttes i stedet ae for æ, oe for ø, aa for å, Ae for Æ, Oe for Ø og Aa for Å. Navngiving av typer BKTPN-1 Type suffiks Et BKXML-skjema SKAL avslutte navnet til en simpletype eller complextype med suffikset Type. BKTPN-2 Navngiving for simpletype Et BKXML-skjema SKAL benytte termen Representasjon for alle sine simpletype. BKTPN-3 Navngiving for complextype Et BKXML-skjema SKAL i sin Representasjon term i typenavnet for en complextype benytte verdien Liste hvis og bare hvis innholdet er minst to forekomster av nøyaktig ett element (dvs. typen inneholder kun en element deklarasjon, og denne har maxoccurs større eller lik 2 eller lik unbounded ). I alle andre tilfeller skal termen Egenskap være Struktur. BKTPN-4 Navngiving av lister Hvis et element i en BKXML-skjema complextype SKAL ha minst to forekomster (dvs. en element deklarasjon skal ha maxoccurs større eller lik 2 eller lik unbounded ), så skal elementet legges alene inn i en ny complextype med sin Representasjon term lik Liste som beskrevet i foregående punkt. BKTPN-5 Bruk av UpperCamelcase for typer BKTPN-6 Systemspesifikke navn for typer Navngiving av elementer BKELN-1 Sammenheng mellom element- og typenavn BKELN-2 Bruk av UpperCamelCase for elementer BKELN-3 Systemspesifikke navn for elementer Navngiving av attributter BKATN-1 Bruk av lowercamelcase for attributter Et BKXML-skjema SKAL navngi alle sine simpletype og complextype i UpperCamelCase. Et BKXML-skjema SKAL IKKE benytte termer som er system- eller leverandøravhengige i sine typenavn. Et BKXML-skjema SKAL navngi sine elementer identisk med elementets type, uten typens Type suffiks, hvis element erklæringen og type definisjonen forekommer sammen i skjema. Et BKXML-skjema skal navngi alle sine elementer i UpperCamelCase. Et BKXML-skjema SKAL IKKE benytte termer som er system- eller leverandøravhengige i sine elementnavn. Et BKXML-skjema SKAL navngi alle sine attributter i lowercamelcase. Side 5 av 10

BKATN-2 Systemspesifikke navn for attributter Navngiving av skjemafiler BKFNR-1 Navngiving av BKXML skjemafil BKFNR-2 Bruk av elementnavn i filnavn Et BKXML-skjema SKAL IKKE benytte termer som er system- eller leverandøravhengige i sine attributtnavn. Et BKXML-skjema SKAL navngi sine skjema filer etter modellen <namespace prefiks>+ _ +<elementnavn>+ _ +<versjon>+.xsd. Et BKXML-skjema SKAL i filnavnets <elementnavn> term angi navnet på skjemaets globale element. Hvis skjemaet inneholder en abstrakt type definisjon skal navnet på den definerte typen, uten suffikset Type brukes. BKFNR-3 Bruk av dato i filnavn Et BKXML-skjema SKAL i filnavnets <versjon> term benytte samme dato som er angitt som dato i filens namespace, angitt på formatet ÅÅÅÅMMDD. BKFNR-4 Bruk av namespace prefiks Et BKXML-skjema SKAL i filnavnets <namespace prefiks> term benytte en etablert og godkjent forkortelse for innholdets namespace term for forretningsområde. Forkortelsen skal være felles for alle skjema innen samme forretningsområde, og unik på tvers av alle forretningsområder. Generelle regler for typedefinisjoner BKGTD-1 Sterke datatyper Et BKXML-skjema SKAL definere alle sine simpletype og complextype sterkest mulig. BKGTD-2 Globale typedefinisjoner Et BKXML-skjema SKAL definere alle sine simpletype og complextype globalt. BKGTD-3 BKGTD-4 Ny definisjon av eksisterende type Bruk av innebygde XML Schema typer Et BKXML-skjema SKAL IKKE definere en simpletype eller complextype identisk med en type i et allerede eksisterende BKXMLskjema. Et BKXML-skjema SKAL IKKE bruke noen av de følgende innebygde enkle typer: anytype, anysimpletype, long, int, short, byte, unsignedlong, unsignedint, unsignedshort, unsignedbyte, normalizedstring, token, language, name, NCName, ID, IDREF, ENTITY, ENTITIES, NMTOKEN eller NMTOKENS. BKGTD-5 Håndtering av binært innhold Et BKXML-skjema SKAL benytte de innebygde enkle typer anyuri eller base64binary for å håndtere binært innhold. BKGTD-6 Abstrakte typer Et BKXML-skjema KAN benytte attributtet abstract i simpletype og complextype til å definere abstrakte typer BKGTD-7 Begrensning av typeavledninger Et BKXML-skjema SKAL IKKE begrense typeavledninger med attributtene finaldefault og blockdefault i schema elementet, attributtet final i simpletype eller attributtene block og final i complextype. BKGTD-8 Bruk av støttetyper Et BKXML-skjema SKAL utelukkende benytte støttetyper for å etablere skjemaets ene typedefinisjon hvis denne ikke kan etableres uten støttetypene. Støttetypene skal ligge i samme fil som typedefinisjonen, og kan ikke brukes av andre skjema. BKGTD-9 Oppbygging av støttetyper Et BKXML-skjema SKAL definere alle sine støttetyper som simpletype eller som lister (complextype som inneholder nøyaktig en elementdeklarasjon hvor maxoccurs er større eller lik 2 eller lik unbounded ) Regler for simpletype definisjoner BKSTD-1 Bruk av list og union Et BKXML-skjema SKAL IKKE benytte konstruksjonene list eller union. BKSTD-2 Lengden av string Et BKXML-skjema BØR IKKE begrense lengden av den innebygde typen string hvis det ikke finnes en allment vedtatt lengde. BKSTD-3 Representasjon av kodelister Et BKXML-skjema SKAL uttrykke kodelister ved hjelp av konstruksjonen enumeration. BKSTD-4 Verdier i kodelister Et BKXML-skjema SKAL utelukkende uttrykke verdier i kodelister med bokstaver og tall, uttrykt i UpperCamelCase. BKSTD-5 Bruk av whitespace Et BKXML-skjema SKAL IKKE benytte whitespace fasetten. Regler for complextype definisjoner BKCTD-1 Oppbygging av Et BKXML-skjema SKAL definere en complextype ved bruk av Side 6 av 10

complextype konstruksjonene sequence eller choice. BKCTD-2 Bruk av all Et BKXML-skjema SKAL IKKE definere en complextype ved hjelp av konstruksjonene all. BKCTD-3 Bruk av hjelpeattributt for choice En complextype som er definert ved hjelp av konstruksjonen choice SKAL ha et attributt for å fortelle hvilket av elementene som inneholder en verdi. BKCTD-4 Bruk av extension Et BKXML-skjema KAN definere en complextype ved hjelp av konstruksjonen extension. BKCTD-5 Bruk av restriction Et BKXML-skjema SKAL IKKE definere en complextype ved hjelp av restriction konstruksjonen. BKCTD-6 Bruk av mixed og empty content Et BKXML-skjema SKAL IKKE benytte blandet (mixed content) eller tom (empty content) innholdsmodell. BKCTD-7 Bruk av any og anyattribute Et BKXML-skjema SKAL IKKE benytte konstruksjonene any eller anyattribute i complextype. Regler for elementdeklarasjoner BKELD-1 Globale Et BKXML-skjema SKAL deklarere sitt element globalt. elementdeklarasjoner BKELD-2 Namespace for elementer Et BKXML-skjema SKAL tildele ett namespace til sitt element. Dvs. attributtet elementformdefault i elementet schema skal tildeles verdien qualified og attributtet form i element deklarasjonen skal ikke benyttes. BKELD-3 Bruk av default og fixed for elementer Et BKXML-skjema SKAL IKKE benytte attributtene default eller fixed i sine element deklarasjoner. BKELD-4 Bruk av nillable Et BKXML-skjema SKAL IKKE sette nillable attributtet til verdien true i sin elementdeklarasjon. Regler for attributtdeklarasjoner BKATD-1 Bruk av attributter Et BKXML-skjema SKAL kun benytte sitt elements attributter til metadata for elementets verdi. BKATD-2 Lokale attributter Et BKXML-skjema SKAL deklarere alle sine attributter lokalt. BKATD-3 Namespace for attributter Et BKXML-skjema SKAL IKKE tildele et namespace til sine attributter. Dvs. attributtet attributeformdefault skal ikke spesifiseres (false er default verdi), og attributtet form i attributt deklarasjonen skal ikke benyttes. BKATD-4 Bruk av default og fixed for attributter Et BKXML-skjema SKAL IKKE benytte attributtene default eller fixed i sine attributt deklarasjoner. Versjoneringsregler BKVER-1 Versjonering i namespace Et BKXML-skjema SKAL angi sin versjon ved hjelp av <version> termen i sitt filnavn og i sitt namespace. BKVER-2 Bruk av dato i namespace Et BKXML-skjema SKAL i en ny versjon av samme BKXML-skjema spesifisere en datoangivelse i <versjon> termen i sitt filnavn og namespace med en senere dato enn den dato som er brukt i en eventuell tidligere versjon av skjemaet. BKVER-3 Opprettelse av ny versjon Et BKXML-skjema SKAL IKKE opprettes i en ny versjon hvis skjemaets innhold er uendret. BKVER-4 Sletting av BKXML-skjema Et BKXML-skjema som er godtatt SKAL IKKE slettes eller endres fra InfostrukturBiblioteket. BKVER-5 Nye skjema i eksisterende namespace Et BKXML-skjema SKAL legges inn i et allerede eksisterende namespace (versjon) hvis det ikke endrer noe av det eksisterende innholdet. BKVER-6 Bruk av version attributtet Et BKXML-skjema SKAL også angi sin nummeriske versjon i attributtet version i schema elementet. Versjoner skal her angis økende med hovedversjonsnummer før punktum og ett nivå med subversjonsnummer etter punktum. Denne versjonen angir versjonen av dette spesifikke BKXML-skjema, og trenger ikke være felles for alle BKXML-skjema innen samme namespace. Namespaceregler BKNMS-1 Navngiving av namespace Et BKXML-skjema namespace SKAL ha følgende oppbygning: <bkinngang>+ / +<bk-område>+ / +<teknikk>+ / +<versjon >. Side 7 av 10

BKNMS-1a BKNMS-1b BKNMS-1c Namespace navngiving for bk-inngang Namespace navngiving for områder Systemspesifikke navn for namespace BKNMS-1d Namespace navngiving for versjon BKNMS-1e Namespace navngiving for teknikk Generelle regler for WSDL BKWSR-1 Bruk av WS-I Basic Profile 1.1 Et BKXML-skjema SKAL i sin namespace term <bk-inngang> ha verdien http://rep.baerum.kommune.no. Et BKXML-skjema SKAL i sin namespace term <bk-område> bruke oppbygningen <toppområde>( / <subområde>)*. Verdiene for toppområde og subområde skal hentes fra listen over områder definert under Arkitekturprinsipper. Ved behov for områder som ikke allerede er definert her, skal nye verdier godkjennes og legges til i Arkitekturprinsipper. Et BKXML-skjema SKAL IKKE benytte termer som er system- eller leverandøravhengige i sine toppområde eller subområde termer i sitt namespace. Et BKXML-skjema SKAL i sin namespace term <versjon> ha en gyldig dato på formatet ÅÅÅÅMMDD. Et BKXML-skjema SKAL i sin namespace term <teknikk> ha verdien Xml/Schema. En BKWSDL SKAL følge anbefalingene til WS-I Basic Profile 1.1, og skal ikke generere feil når de testes med siste versjon av WS-I WSDL- Analyzer. BKWSR-1 Bruk av document-literal En BKWSDL SKAL benytte document-literal binding. BKWSR-3 Bruk av godkjente BKXML En BKWSDL SKAL kun benytte typer fra godkjente BKXML-skjema. typer BKWSR-4 Bruk av elementreferanser En BKWSDL SKAL i sine message elementer kun ha ett part element. Dette part elementet skal benytte element attributtet og skal referere til et globalt godkjent BKXML-element. BKWSR-5 Bruk av request-response En BKWSDL SKAL benytte request-response utveksling. BKWSR-6 Bruk av fault En BKWSDL SKAL IKKE benytte fault konstruksjonen. Alle feilmeldinger skal fanges opp i tjenesten og returneres som feilmelding i kontekstobjektet for status. BKWSR-7 Bruk av protokoller En BKWSDL SKAL definere tjenester som kommuniserer over Soap protokollen. Navngivingsregler for WSDL BKWSN-1 Bruk av BKXML navngivingsregler En BKWSDL SKAL følge navngivingsreglene for BKXML-skjema der disse gir mening. BKWSN-2 Bruk av namespace i WSDL En BKWSDL SKAL i sine namespace termer <bk-inngang>, <bkområde> og <versjon> følge reglene for BKXML-skjema. BKWSN-3 Namespace navngiving for teknikk i WSDL En BKWSDL SKAL i sin namespace term <teknikk> ha verdien Xml/Wsdl BKWSN-4 Navngiving av WSDL filer En BKWSDL SKAL navngi sine wsdl fil etter modellen <namespace prefix>+ _ +<tjenestenavn>+ _ +<versjon>+.wsdl. BKWSN-5 Navngiving av tjenester En BKWSDL SKAL navngi sin tjeneste (service) med et begrep som er dekkende for alle dens operasjoner. Et tjenestenavn bør ikke beskrive en handling BKWSN-6 Navngiving av operasjoner En BKWSDL SKAL navngi sine operasjoner etter HandlingObjekt navngivningsmodellen. Det er ingen faste regler for Handling eller Objekt termene, men Handling termen skal presist gjengi operasjonens oppgave. Objekt termen vil i mange tilfeller være identisk med navnet på selve tjenesten. BKWSN-7 Navngiving av meldinger En BKWSDL SKAL navngi sine meldinger (message) etter modellen <operasjonsnavn>+ In og <operasjonsnavn>+ Out for hhv. Inn og ut parameterene. BKWSN-8 Navngiving og oppbygging av meldingsinnhold En BKWSDL SKAL i sine meldinger ha nøyaktig ett part element. Dette part elementet skal ha navnet body og skal referere til elementet i et gyldig BKXML-skjema som inneholder korrekte kontekst objekter samt et element som samler alle forretningsdata i inn eller ut parametrene. Nevnte BKXML-skjema skal ha som navn <operasjonsnavn>+ Request for inn parameteren og Side 8 av 10

<operasjonsnavn>+ Response for ut parameteren. De tilsvarende typer skal ha samme navn, men med endelsen Type BKWSN-9 Navngiving av porttype En BKWSDL SKAL navngi sine porttype elementer etter navngivningsmodellen <tjenestenavn>+<teknikk>+ Port. Hvor <teknikk> for eksempel er Soap, Get eller Post BKWSN-10 Navngiving av bindinger En BKWSDL SKAL navngi sine binding elementer etter navngivningsmodellen <tjenestenavn>+<teknikk>+ Binding. Hvor <teknikk> er som i punktet for porttype. BKWSN-11 Navngiving av SOAP-action En BKWSDL SKAL navngi sin SOAP-action etter modellen <namespace>+ / +<tjenestenavn> # +<operasjonsnavn>. BKXML liste over representasjonstermer Representasjonsterm Beskrivelse Antall Et antall ikke-monetære enheter. Beloep Et antall monetære enheter. Data Binære data representert i base64binary Dato En dato innenfor et bestemt kalenderår, basert på ISO 8601 DatoTid Et bestemt tidspunkt, innenfor en spesifisert dato. Id(entifikator) En string som, innenfor en identifikasjonsramme, brukes til å identifisere og unikt utpeke èn instans av et objekt blant alle objekter innenfor samme ramme. Indikator En liste av nøyaktig to verdier som indikerer en tilstand. For eksempel av/på eller sann/usann. Tilsvarer boolean. Kode En enumerert kode. Maal En nummerisk verdi bestemt ved å måle et objekt. Kan angis sammen med en måleenhet fra UN/ECE Rec. 20. Navn Et ord eller en frase som inneholder den presise betegnelse for en person, et sted, ting eller konsept. Prosent En rate uttrykt som en hundrededel mellom to verdier med samme måleenhet Rate En mengde eller et antall målt i forhold til hverandre, eller en fast eller passende verdi. For eksempel kroner per time, norske kroner per EURO eller kilometer per liter. Referanse En string som brukes til å referere en bestemt objektinstans som er identifisert med en Identifikator. Tekst En generell tekststreng/tekst. Tid Tidspunkt innenfor en ikke-spesifisert dag. Side 9 av 10

Toppdomener i tjenestekatalogen Område Barnehager og parker Barnevern BK Bedrifter Forurensning og renovasjon Grunnskole Helse Kemneren i Asker og Bærum Kultur, kirke, fritid Natur og idrett Plan og bygningstjenester Pleie og omsorg Sosial og bolig Vann og avløp Vei og trafikk Øvrige tjenester Støttetjenester Domenenavn Barnehage Barnevern BKB Renovasjon Grunnskole Helse Kemner Kultur Idrett Plan PLO Sosial VA Vei Diverse Stoette Side 10 av 10