Specificaties UM Aquo CSV-encoding

Transcriptie

1 Specificaties UM Aquo CSV-encoding Auteur: Informatiehuis Water

2 Documentbeheer Wijzigingshistorie Datum Versie Auteur Wijziging 22 mrt Informatiehuis Initiële versie in memo-sjabloon 2012 Water 12 juni Hinne Reitsma Rapport-sjabloon toegepast. Inhoudelijk ongewijzigd behalve kleine wijziging in tabel en in bijlage B 17 dec Sylvia van Kuijck Opmerking over grootheid bij combinatie parameter O2 en eenheid % in Bijlage A aangepast André Meerkerk RfC W : foutherstel kolomnaam Taxon.name en wetenschappelijke notatie getallen; tekstuele verbeteringen; Bijlage A "Omgaan met typering, grootheid en parameter", is verwijderd Willemien Joosse Tekstuele verbetering aangebracht bij Formaat / verwerking importfunctie van Tijd_UTCoffset Review Datum Versie Reviewer Functie Controle en vrijgave Datum Versie Controleur Functie Boris Everwijn Programmamanager pagina 2 van 14

3 Literatuurbronnen 1. Inhoudsopgave 1. Inleiding Achtergrond en doel Algemeen Specificaties Inhoud Algemeen Kolommen en kolomkoppen Gegevensregels Details CSV bestanden Details CSV Meetpunt Details CSV Monster Details CSV Tijdwaarden... 9 Bijlage A Richtlijn importeren in systemen 11 Bijlage B ibever compatibiliteit 12 Bijlage C Mapping met UM Aquo klassen en attributen 13 pagina 3 van 14

4 1. Inleiding 1.1 Achtergrond en doel Dit document beschrijft de manier van omzetten ( encoding ) van het uitwisselmodel UM Aquo naar het technisch formaat CSV. Naast CSV ondersteunt het Informatiehuis Water ook het technische formaat XML, dit is een GML encoding (GML 3.1.1, technisch formaat) van UM Aquo. De in dit document beschreven CSV formaten zijn niet bedoeld als vervanging van het UM Aquo XML / GML formaat en kunnen niet dezelfde rijkheid aan informatie overbrengen. Doel van de CSV formaten is om, voor een aantal veelgebruikte constructies en met name voor grote hoeveelheden gegevens, een eenvoudig te genereren (en met b.v. MS-Excel in te lezen) formaat beschikbaar te stellen om zo de interoperabiliteit van (uitwisselbaarheid tussen) systemen te vergroten. Deze specificatie kan als vervanging van het ibever uitwisselformaat worden gezien maar wijkt daar op punten ook duidelijk van af. Dit is het gevolg van 15 jaar aanvullende ervaring met de standaardisatie en uitwisseling van meetgegevens. In bijlage B is een tabel opgenomen met daarin een vergelijking tussen de kolomkoppen uit het ibever formaat en die uit de Aquo CSV specificatie. 1.2 Algemeen Het is niet mogelijk om alle informatie die in het UM Aquo XML-formaat is opgenomen in een enkel CSV-bestand uit te wisselen. Om de complexe structuur van UM Aquo in een CSV-uitwisseling te gebruiken zijn meerdere CSV-formaten gedefinieerd: - Meetpunt. Momenteel ondersteunt dit formaat alleen het type meetpunt ; er is geen mogelijkheid om lijn- en/of vlakgeometrieën uit te wisselen, hiervoor dient de GML-encoding te worden toegepast. - Monster. Momenteel ondersteunt dit formaat alleen de uitwisseling van enkelvoudige, fysieke, monsters (dus geen deelmonsters of monsterobjecten met de functie om meerdere meetreeksen te bundelen). Hierbij is een aparte CSV met meetpunt eigenschappen noodzakelijk, conform het hierbovengenoemde CSV-formaat Meetpunt. - Tijdwaarden. Het gaat hierbij om waarnemingen op een specifiek moment in de tijd welke direct gekoppeld zijn aan meetpunten óf monsters. Meetreeksen kunnen alleen uitgewisseld worden in dit formaat door duplicatie van alle gegevens. Hierbij zijn er aparte CSV-bestanden met meetpunt en/of monster eigenschappen noodzakelijk, conform de hierboven genoemde CSV-formaten Meetpunt en Monster. Het is niet mogelijk om meervoudig bepaalde waarden uit te wisselen via CSV, hiervoor dient gebruik gemaakt te worden van het XML-formaat van UM Aquo Metingen. Het verschil tussen een uitwisseling waarbij ook monsters worden uitgewisseld en een uitwisseling waarbij alleen waarden (en meetpunten) Inleiding pagina 4 van 14

5 worden uitgewisseld is gelegen in het gebruik van een referentie naar een monster en het toepassen van het compartiment. Opname van het compartiment in de tijdwaarden is niet noodzakelijk als ook de monstergegevens worden uitgewisseld. 2. Specificaties 2.1 Inhoud Algemeen CSV-bestanden worden gecodeerd volgens de UTF-8 codering met gebruik van de Unicode (ASCII) karakterset. In deze specificatie worden een aantal bijzondere karakters gebruikt, deze hebben de volgende tekencode: Karakter / symbool Omschrijving Tekencode (Unicode) Dubbele quotes 34. Punt 46 ; Puntkomma 59 Ieder CSV-bestand bestaat uit twee delen: - Headerregel waarin de kolomkoppen zijn opgenomen, gescheiden door het scheidingsteken ; (puntkomma). - Serie gegevensregels waarin de daadwerkelijke informatie is opgenomen in dezelfde volgorde als in de headerregel. De gegevens per regel zijn gescheiden door het scheidingsteken ; (puntkomma) Kolommen en kolomkoppen Kolomkoppen hebben een naam die direct is afgeleid van (en zoveel mogelijk gelijkend op) de attribuutnamen uit UM Aquo (zie tabellen in paragraaf 2.2). Namen van kolomkoppen zijn niet hoofdlettergevoelig. De mapping van de kolomkoppen met UM Aquo klassen en attributen is opgenomen in bijlage C. Bij kolommen die verwijzen naar een domeintabel uit Aquo is de naam opgebouwd uit: de naam van het attribuut uit het uitwisselmodel, een '.' (punt), en de naam van het veld van de domeintabel dat is opgenomen (bijvoorbeeld code of omschrijving). Een voorbeeld van een kolomkop die verwijst naar een domeintabel is Organisme.naam, van het CSV-formaat Monster. Dit betreft dus UM Aquo attribuut "organisme", en het veld "naam" van de gekoppelde domeintabel Biotaxon. Specificaties pagina 5 van 14

6 Naast de kolom Organisme.naam mogen optioneel ook extra kolommen worden opgenomen met gegevens uit de domeintabel. Bijvoorbeeld Organisme.taxonniveau. Taxonniveau is één van de andere velden van domeintabel Biotaxon. Namen van kolomkoppen zijn niet hoofdlettergevoelig. Kolommen die verwijzen naar een externe sleutel zoals in meetwaarde naar de meetpunt-identificatie hebben een opbouw die vergelijkbaar is met de verwijzing naar domeintabellen (bestand / tabel naam, gevolgd door een. (punt), gevolgd door het veld waarnaar verwezen wordt. In de huidige specificatie komt dit tweemaal voor: Meetpunt.identificatie en Monster.identificatie. De cardinaliteit per kolom is tenminste gelijk aan die van UM Aquo (zie hiervoor ook de details verder in dit document), voor specifieke uitwisselingsbehoeften mogen er aanvullende eisen gesteld worden (een N mag C of J worden, een C mag J worden). Dit gebeurt door specifieke afspraken die niet in dit document zijn opgenomen maar in de systeemdocumentatie welke voor alle gebruikers (en afnemers) toegankelijk is. Er wordt hierbij onderscheid gemaakt tussen J wel verplicht, N - niet verplicht en C conditioneel. Bij conditioneel bevat de toelichting op het veld een beschrijving onder welke omstandigheden het veld verplicht is en in welke omstandigheden niet. Het CSV bestand bevat tenminste alle kolommen die verplicht zijn (cardinaliteit = J). De niet verplichte kolommen mogen opgenomen worden, maar dit hoeft niet. Er gelden geen eisen met betrekking tot de volgorde waarin de kolommen (attributen) in het CSV bestand voorkomen. Elke volgorde is toegestaan. In het CSV bestand mogen kolommen worden opgenomen die niet in UM Aquo voorkomen. Deze worden in afzonderlijke afspraken tussen uitwisselende partijen vastgelegd en worden gepubliceerd door de partij die ze toevoegt op een dusdanige manier dat ze voor iedere (mogelijke) ontvanger beschikbaar zijn. Uitbreidingen worden voorafgegaan door een 3-karakter code gevolgd door een underscore om ze herkenbaar te maken voor derden. Het IHW zorgt voor registratie van de 3 karaktercode (deze is gelijk aan de extensie in de GML/XML encoding). Een voorbeeld van een dergelijke uitbreiding is de opname van het KRW watertype in het uitwisselbestand meetpunt voor de uitwisseling van meetpunt gegevens naar de Aquo-kit. Deze is voor de Aquo-kit nodig om de juiste norm te selecteren bij de aangeboden meetwaarden, voor andere uitwisseling is deze niet relevant. Specificaties pagina 6 van 14

7 2.1.3 Gegevensregels Gegevensregels moeten voldoen aan: Verplichte kolommen (J) dienen altijd (zinvolle) informatie te bevatten en mogen niet leeg gelaten worden in een gegevensregel. Optionele kolommen (N) mogen wel leeg gelaten worden in een gegevensregel. Teksten welke uitgewisseld worden waarin het scheidingsteken in de uit te wisselen tekst voorkomt zijn omgeven door " (dubbele quotes). Het advies is om alle tekstvelden van dubbele quotes te voorzien, dit is echter geen verplichting. Voorbeeld: "987654";"12345AB";;;"pH";"Zuurgraad";;;;"DIMSLS";"NVT";"OW";"NVT" ;; ;10:55:00;;;;8.2;;"00" In dit voorbeeld stelt geen getal voor maar de identificatiecode van het monster, oftewel tekst. De waarde 8.2 aan het eind is een decimaal getal. Decimale getallen worden uitgewisseld met de punt '.' als decimaal scheidingsteken. Het is daarbij ook toegestaan getallen in wetenschappelijke notatie uit te wisselen (dus bijvoorbeeld 1E-3 in plaats van 0.001). Een numerieke waarde kan maximaal 15 significante cijfers bevatten, waarvan maximaal 12 decimalen. Indien het aantal voorloopnullen te groot zou worden bij een dergelijke notatie dan kan er ook voor gekozen worden een andere eenheid te gebruiken (dus in plaats van met eenheid m gebruik maken van 1 met als eenheid mm. Het type van een veld wordt gedefinieerd door UM Aquo. Zie de beschrijving hiervan voor meer informatie ( Het type van een veld dat een Aquo domeintabel heeft is altijd tekst. De lengte van het tekstveld is gelijk aan die in de domeintabel. Deze informatie is te vinden in de Aquo domeintabellenservice ( Specificaties pagina 7 van 14

8 2.2 Details CSV bestanden Details CSV Meetpunt Kolomkop Verplicht Aquo domeintabel Opmerkingen Identificatie J MetingOmschrijving N Waterbeheerder.code N Waterbeheerder Tweecijferige code welke de waterbeheerder identificeert GeometriePunt.X_RD J RD-stelsel (in meters). GeometriePunt.Y_RD J RD-stelsel (in meters) Details CSV Monster Kolomkop Verplicht Aquo domeintabel Formaat / verwerking importfunctie Identificatie J Meetpunt.identificatie J Een verwijzing naar het bijbehorende meetpunt. Compartiment.code J Compartiment Dit is de tweelettercode, niet de cijfercode. Orgaan.code C Orgaan Verplicht als compartiment organisme is Organisme.naam C Biotaxon Verplicht als compartiment organisme is BeginDiepte_m N Begindiepte van het monster in meters EindDiepte_m C Verplicht als begindiepte is ingevuld Referentievlak.code C Hoedanigheid,groep: ReferentieVlak Monsterbewerkingsmethode.code N Monsterbewerkingsmethode Bemonsteringsmethode.code N Bemonsteringsmethode Monstercriterium.code N Hoedanigheid,groep: BiologischKenmerk KorrelgrootteFractie Plaatsbepaling.omschrijving N Plaatsbepalingsapparaat Veldapparaat.omschrijving N Meetapparaat Bemonsteringsapparaat Plaatsbepalingsapparaat Monsternemingsdatum J Eejj-mm-dd Monsternemingstijd N hh:mm:ss Verplicht als begin diepte niet ten opzichte van NAP is uitgedrukt. Er kan slechts één criterium per monster worden aangegeven (in UM Aquo zijn meerdere mogelijk) Er kan slechts één apparaat worden aangegeven (in UM Aquo zijn meerdere mogelijk) Tijd_UTCoffset C Als de monsternemingstijd is ingevuld en niet in MET is opgenomen (UTC + 1 / GMT + 1), dan hier de afwijking ten opzichte van UTC opnemen. Uitgangspunt is dat de monsternemingstijd is opgenomen in MET, waarbij de UTC-offset +1:00 is. Deze waarde is de default en als niets wordt ingevuld, wordt deze waarde dus aangenomen. De monsternemingstijd in zomertijd krijgt een offset van UTC + 2. Specificaties pagina 8 van 14

9 2.2.3 Details CSV Tijdwaarden Kolom Verplicht Aquo domeintabel Formaat / verwerking importfunctie Monster.identificatie C Er dient ofwel een verwijzing naar het bijbehorende Meetpunt.identificatie C monster ofwel naar het bijbehorende meetpunt te zijn opgenomen. Grootheid.code C Parameter,groep: Grootheid Typering.code C Parameter,groep: Typering Er dient óf een Grootheid óf een Typering te zijn gekozen Er dient óf een Grootheid óf een Typering te zijn gekozen Parameter.groep C Parameter Als de parameter.code of omschrijving is ingevuld dan hier aangeven welk type er is gebruikt ( ChemischeStof, Object of Biotaxon ) Parameter.code C Parameter,groep: ChemischeStof Object Parameter.omschrijving C Parameter,groep: ChemischeStof Object Biotaxon Eenheid.code J Eenheid Hoedanigheid.code N Hoedanigheid Deze kolom bevat of de code van een ChemischeStof of van een Object. Het veld is verplicht als een parametergroep van deze typen is gekozen. Deze kolom bevat of de omschrijving van een ChemischeStof of van een Object Of de taxonname uit de TWN (TWN = Taxa Waterbeheer Nederland). Het veld is verplicht als de parametergroep Biotaxon is gekozen Compartiment.code C Compartiment Dit is de tweelettercode, niet de cijfercode. Als er een referentie naar een monster is opgenomen is opname van het compartiment niet verplicht, anders wel. Waardebewerkingsmethode.code N Waardebewerkingsmethode Waardepalingsmethode.code N Waardebepalingsmethode Begindatum J eejj-mm-dd Begintijd N hh:mm:ss Einddatum N eejj-mm-dd Eindtijd N hh:mm:ss Tijd_UTCoffset C Als begintijd / eindtijd zijn ingevuld en niet in MET zijn opgenomen (UTC + 1 / GMT + 1), dan hier de afwijking ten opzichte van UTC opnemen. Uitgangspunt is dat metingen zijn uitgevoerd in MET, waarbij de UTC-offset +1:00 is. Deze waarde is de default en als niets wordt ingevuld, wordt deze waarde dus aangenomen. Een meting in zomertijd krijgt een offset van UTC + 2. Limietsymbool N Leeg of één van de twee symbolen < of > Numeriekewaarde C of numerieke of alfanumerieke waarde is gevuld Alfanumeriekewaarde C of numerieke of alfanumerieke waarde is gevuld Kwaliteitsoordeel.code J 1 Kwaliteitsoordeel 1 Binnen de huidige implementaties van dit CSV formaat voor het zwemwaterregister en de Aquo-kit (Toetsing aan waterkwaliteitsnormen en KRW-beoordeling) is voor de kolomkop Kwaliteitsoordeel.code afgeweken van dit specificatie document. Dit omdat gespecificeerd is dat indien deze kolom leeg gelaten is de code 00 (normale waarde) verondersteld mag Specificaties pagina 9 van 14

10 Toelichting op grootheid, parameter en typering In het UM Aquo wordt het verschijnsel dat gemeten wordt aangeduid met de velden Grootheid.code en/of Parameter.code, of met het veld Typering.code. In de praktijk wordt hiervoor echter ook gebruikt gemaakt van het zogenaamde waarnemingssoortnummer of het ibever uitwisselformaat. In tegenstelling tot UM Aquo wordt daarin alleen een identificatie gegeven van de parameter. Daarom is er een vertaalslag nodig om van bijvoorbeeld een waarnemingssoortnummer de overeenkomstige UM Aquo waarden van Grootheid- en Parameter.code of Typering.code te bepalen. Voor een groot aantal waarnemingssoorten is deze vertaling beschikbaar in de vorm van een mapping. Deze mapping UM Aquo Metingen Waarnemingssoort en een uitgebreidere toelichting op dit onderwerp vindt u op: worden te staan in deze kolom (conditionele opname). Middels een wijzigingsvoorstel zal dit worden hersteld. Specificaties pagina 10 van 14

11 Bijlage A Richtlijn importeren in systemen Niet herkende kolomkoppen worden bij een import genegeerd en vastgelegd in een logbestand of middels een melding aan de gebruiker gemeld. Indien een bestand verwijzingen bevat in kolommen uit UM Aquo met waarden die niet in Aquo domeintabellen zijn opgenomen dan worden deze bestanden geweigerd (ook herkende waarden worden dus niet geïmporteerd) en wordt de reden van het niet importeren (regel en kolom waarop de import heeft gefaald) weggeschreven naar een logbestand of aan de gebruiker gemeld. Voor bepaalde kolomkoppen is er een alternatieve sleutel (synoniem) beschikbaar om compatibiliteit met legacy systemen te waarborgen. Deze alternatieve sleutel is afkomstig van het ibever uitwisselformaat en mag niet worden gebruikt bij het schrijven van bestanden door systemen die deze specificatie nieuw implementeren. Belangrijkste reden om deze kolomkoppen te vermelden is om de relatie tussen deze CSV beschrijving en het (voormalige) ibever uitwisselformaat aan te duiden. Bijlagen pagina 11 van 14

12 Bijlage B ibever compatibiliteit Onderstaande tabel geeft de overeenkomstige kolomkoppen tussen het ibever CSV formaat en het Aquo CSV formaat. Niet alle kolommen uit het Aquo CSV formaat zijn in het ibever CSV formaat opgenomen. Aquo CSV kolomkop Hoedanigheid.code Veldapparaat.code 2 ibever kolomkop hoe_domgwcod mba_domafkrt Waardebewerkingsmethode.code mbm_domgwcod Bemonsteringsmethode.code Compartiment.code Eenheid.code Meetpunt.identificatie MetingOmschrijving BeginDiepte_m EindDiepte_m GeometriePunt.X_RD GeometriePunt.Y_RD Parameter.code Kwaliteitsoordeel.code Limietsymbool Begindatum Einddatum Begintijd Eindtijd Alfanumeriekewaarde Numeriekewaarde Orgaan.code Referentievlak.code Waardepalingsmethode.code Waterbeheerder.code mbw_domafkrt mco_domgwcod mep_domgwcod mpn_mpnident mpn_mpnomsch mpn_mpnzbove mpn_mpnzonde mpn_mrfxcoor mpn_mrfycoor mps_domgwcod mrsinkwa_id mrsinovs_domafkrt mwa_mwadtmb mwa_mwadtme mwa_mwatijdb mwa_mwatijdb mwa_mwawrdea mwa_mwawrden org_orgorgos rvlak_domafkrt wbm_domgwcod wsp_domgwcod 2 Alleen Plaatsbepalingsapparaat heeft een code en een omschrijving. Meetapparaat en Bemonsteringsapparaat bestaan uit een omschrijving zonder code en kunnen hier niet gebruikt worden. Bijlagen pagina 12 van 14

13 Bijlage C Mapping met UM Aquo klassen en attributen C.1 Toelichting op de mapping Deze mapping is gemaakt door te kijken naar het UM Aquo metingen zoals dat gemodelleerd is in het logische model UM Aquo en te bekijken is op onze website via de uitwisselmodellen interactief. Door het overerven van eigenschappen / attributen vanuit klassen naar subklassen en door het gebruik van DataTypen bestaan er verschillen. C.2 Mapping van CSV Meetpunt met MeetObject (een subklasse van NEN3610::GeoObject en IMWA::Meting) Aquo CSV kolomkop Afkomstig uit klasse Attribuutnaam Opmerkingen Identificatie NEN3610::GeoObject identificatie MetingOmschrijving IMWA::Meting metingomschrijving Waterbeheerder.code waterbeheerder GeometriePunt.X_RD geometriepunt De eerste set cijfers (x-coördinaat) uit GM_Point en uitgedrukt in het RD-stelsel (in meters). GeometriePunt.Y_RD geometriepunt De tweede set cijfers (y-coördinaat) uit GM_Point en uitgedrukt in het RD-stelsel (in meters). C.3 Mapping van CSV Monster met MonsterObject en subklasse FysiekMonster Aquo CSV kolomkop Afkomstig uit klasse Attribuutnaam Opmerkingen Identificatie MonsterObject identificatie Alleen in het xsd aanwezig Meetpunt.identificatie Relatie tussen MeetObject en MonsterObject MeetObject::identificatie Een verwijzing naar het bijbehorende MeetObject. Compartiment.code MonsterObject compartiment Dit is de tweelettercode, niet de cijfercode. Orgaan.code Organisme.naam orgaan organisme BeginDiepte_m begindiepte DiepteDataType, dieptehoogte Referentievlak.code DiepteDataType, referentievlak EindDiepte_m einddiepte DiepteDataType, dieptehoogte Referentievlak.code Monsterbewerkingsmethode.code Bemonsteringsmethode.code Monstercriterium.code Plaatsbepaling.omschrijving Veldapparaat.omschrijving monsterbewerkingsmethode bemonsteringsmethode monstercriterium plaatsbepaling veldapparaat Monsternemingsdatum FysiekMonster monsternemingsdatum datum Monsternemingstijd Tijd_UTCoffset DiepteDataType, referentievlak tijd Subattribuut van het DataType Tijd in Bijlagen pagina 13 van 14

14 het model C.4 Mapping van CSV Tijdwaarden met WaardeReeks en WaardeReeksTijd Aquo CSV kolomkop Afkomstig uit klasse Attribuutnaam Opmerkingen Monster.identificatie Relatie tussen WaardeReeks en MonsterObject MonsterObject::identificatie Meetpunt.identificatie MeetObject::identificatie Deze relatie is niet opgenomen in UM Aquo en is een directe koppeling (zonder tussenliggend MonsterObject) tussen WaardeReeks en MeetObject Grootheid.code WaardeReeks kwaliteitselementofparameter parametergrootheid (DataType), grootheid Typering.code kwaliteitselementofparameter typering (DataType) Parameter.groep - Komt niet voor in UM Aquo, is een technische toevoeging om een mapping mogelijk te maken naar het datatype KwaliteitsElementOfParameter. Vulling is afhankelijk van keuze Parameter.code kwaliteitselementofparameter parametergrootheid (DataType), parameter Parameter.omschrijving kwaliteitselementofparameter parametergrootheid (DataType), parameter Eenheid.code Hoedanigheid.code Compartiment.code Waardebewerkingsmethode.code Waardepalingsmethode.code Begindatum Begintijd Einddatum Eindtijd Tijd_UTCoffset Limietsymbool Numeriekewaarde Alfanumeriekewaarde Kwaliteitsoordeel.code WaardeReeksTijd eenheid hoedanigheid compartiment waardebewerkingsmethode waardebepalingsmethode reekswaarde, dit gedeelte is afkomstig uit het DataType TijdWaarde reekswaarde, dit gedeelte is afkomstig uit het DataType Waarde begintijd, DatumTijdDataType, datum begintijd, DatumTijdDataType, tijd eindtijd, DatumTijdDataType, datum eindtijd, DatumTijdDataType, tijd Subattribuut van het DataType Tijd in het model numeriekewaarde WaardeDataType, bepalingsgrens numeriekewaarde WaardeDataType, getalswaarde alfanumeriekewaarde kwaliteitsoordeel Bijlagen pagina 14 van 14