Zoeken of een datum of tijdstip valt binnen een periode

Inleiding

Bij de uitgifte van kengegevens kan in de kenmerken (criteria) een periode worden opgegeven waarbinnen de waarde van een attribuut van een registratieobject moet liggen, opdat de kengegevens van het registratieobject zal worden uitgegeven. Daarbij kan het atribuut een van de volgende datatypes zijn:

Datum
DatumTijd (datum en tijdstip)
OnvolledigeDatum (de waarde is een volledige datum, of alleen en jaartal en maand, of alleen een jaartal, of de waarde is onbekend)

Enkele voorbeelden:

RO

Attribuut

Definitie

brocommon

registrationPeriod

Het datuminterval waarbinnen de datum van het tijdstip registratie van het registratieobject moet liggen.

N.B. Datatype van objectRegistrationTime is DatumTijd.

EPL

expiryDatePeriod

De periode waarbinnen de vervaldatum van de vergunning moet liggen.

N.B. Datatype van expiryDate is Datum.

EPC

boreholeSegmentDrillingStartPeriod

Het datuminterval waarbinnen de datum, die het begin aangeeft van de periode dat het boortraject is aangelegd, ligt.

N.B. Datatype van drillingStartDate is OnvolledigeDatum.

Deze kenmerken hebben Datuminterval (DatePeriod) als datatype. Dit datatype is gedefinieerd in brocommon.xsd als een gegevensgroep met 2 datums: begindatum en eindDatum, beide van het type Datum.

De volgende drie paragrafen beschrijven voor de drie datatypes hoe gecontroleerd wordt of de waarde van een attribuut met dat datatype ligt binnen de zoek periode.

Gezocht attribuut is een Datum

Als het datatype van het te vergelijken attribuut een Datum is, dan is de vergelijking triviaal.

Regel

Een attribuut voldoet aan het kenmerk als de waarde van het attribuut:

groter of gelijk is aan de beginDatum van de periode.
en kleiner of gelijk is aan de eindDatum van de periode.

Voorbeelden

Voorbeeld 1: Attribuut (Datum) moet worden vergeleken met een periode van meerdere dagen vanaf 10-11-2024 tot en met 07-01-2025.

Voorbeeld 2: Attribuut (Datum) moet worden vergeleken met een periode van 1 dag, namelijk vanaf en tot en met 05-12-2024.

Motivatie

Het kenmerk definieert een periode vanaf de begindatum tot en met de einddatum, beiden inclusief. Het begindatum en de einddatum van de periode en het te vergelijken attribuut worden beiden uitgedrukt in een Datum. Omdat de datatypes van de begindatum, de einddatum en het te vergelijken attribuut hetzelfde zijn, kunnen de waarde ervan rechtstreeks met elkaar worden vergeleken. Omdat de periode geldig is vanaf de begindatum leidt dit tot een vergelijking:

waarde van het attribuut >= begindatum van de periode.

Omdat de periode geldig is tot en met de einddatum leidt dit tot een vergelijking:

waarde van het attribuut <= einddatum van de periode.

Gezocht attribuut is een DatumTijd

Als het datatype van het te vergelijken attribuut een DatumTijd is, dan is de vergelijking iets minder eenvoudig. Dit wordt veroorzaakt doordat het datatype van de begindatum en de einddatum van de periode anders is dan het datatype van het te vergelijken attribuut. De datum plus tijdsdeel van het te vergelijken attribuut moet worden vergeleken met een ‘kale datum’ voor het begin en het einde van de periode. Daarbij spelen onder anderen de volgende vragen een rol:

Wat als het tijdsdeel niet nul is?
Hoe om te gaan met een tijdzone (note: in de BRO is het gebruik van tijdzone verplicht bij het aanleveren van DatumTijd gegevens; zie Handreiking aanleveren BRO-gegevens | 7.6.-DatumTijd)?

Regel

Een attribuut voldoet aan het kenmerk als de waarde van het attribuut na conversie naar lokale tijd (Nederlandse tijdzone met datumafhankelijke zomertijd/wintertijd):

groter of gelijk is aan de beginDatum van de periode.
en kleiner is dan de (eindDatum + 1 dag) van de periode.

Voorbeelden

Voorbeeld 1: Attribuut (DatumTijd) moet worden vergeleken met een periode vanaf 10-11-2024 tot en met 07-01-2025. De ‘vanaf-tot-en-met’ periode wordt geconverteerd naar een periode vanaf 10-11-2024 tot 08-01-2025. Merk op dat in dit geval de geconverteerde einddatum 8-1-2025 van de periode buiten de geldige period valt. Merk op dat de attribuutwaarden bestaan uit een datum en tijd. Merk op dat het grensgeval 07-01-2025 23:59:59 binnen de geldige period valt en dat het grensgeval 08-01-2025 00:00:00 buiten de geldige periode valt.

Motivatie

Het begin en het einde van de periode worden uitgedrukt in een Datum. De periode is geldig vanaf de begindatum tot en met de einddatum, beiden inclusief. Als de waarde van het te vergelijken attribuut samenvalt met de begindatum en/of einddatum van de periode, dan voldoet het attribuut aan het kenmerk. Deze uitgangspunten worden doorgetrokken voor het geval het datatype een DatumTijd is;

Als de waarde van het te vergelijken attribuut bestaat uit een datumdeel dat gelijk is aan de begindatum van de periode en een niet-nul tijdstip, dan ligt de waarde van het attribuut na (vanaf) de begindatum.
Als de waarde van het te vergelijken attribuut bestaat uit een datumdeel dat gelijk is aan de einddatum van de periode en een niet-nul tijdstip op die datum, dan ligt de waarde van het attribuut op (tot en met) de einddatum.

In de gestipuleerde regel wordt de waarde van het te vergelijken attribuut eerst geconverteerd naar lokale (Nederlandse) tijd en daarna vergeleken met de begindatum en einddatum van de periode. Omdat het tijdsdeel niet-nul kan zijn, leidt dit voor de vergelijking met de einddatum van de periode tot de uitdrukking ‘kleiner dan (einddatum + 1 dag)’ in plaats van 'kleiner of gelijk aan de eindDate'.

In de gestipuleerde regel is als uitgangspunt genomen dat een DatumTijd waarde van het te vergelijken attribuut wordt vergeleken met de begindatum/einddatum van de periode. Een ander uitgangspunt had kunnen zijn om de nauwkeurigheid van de waarden (van het te vergelijken attribuut, de begindatum van de periode en de einddatum cvan de periode) op elkaar af te stemmen, waarna een rechtstreekse vergelijking mogelijk is. Daarbij moet een tweede uitgangspunt worden gekozen, namelijk:

de nauwkeurigheid inperken tot de laagst aanwezige nauwkeurigheid
of de nauwkeurigheid oprekken tot de hoogst aanwezige nauwkeurigheid

Omdat de nauwkeurigheid van het tijdsdeel van het te vergelijken attribuut onbekend is (ergens tussen minuut en milliseconde; zie de ISO definitie van een DatumTijd), zou het oprekken van de nauwkeurigheid leiden tot het optellen van een onbekend tijdsdeel bij de einddatum van de periode voordat deze wordt vergeleken met de waarde van het te vergelijken attribuut. Daarmee vervalt deze optie.

Het inperken van de nauwkeurigheid zou leiden tot het aanpassen van de waarde van het te vergelijken attribuut. Dit zou worst-case moeten worden gedaan voor de gehele populatie van registratieobjecten van het bevraagde type registratieobject.

In plaats daarvan is ervoor gekozen de regel te formuleren uitgaande van een aangepaste periode die geldig is vanaf de begindatum (inclusief) tot de einddatum (exclusief). De aanpassing bestaat uit het optellen van 1 dag bij de einddatum van de periode. Met de genoemde alternatieven kan hetzelfde effect worden bereikt. Maar omdat het aanpassen van de waarde van het te vergelijken attribuut zou kunnen leiden tot performance problemen, is gekozen voor de beschreven methode. Daarentegen is het aanpassen van de einddatum van de periode een orde-grootte-nul bewerking.

Gezocht attribuut is een OnvolledigeDatum

Als het datatype van het te vergelijken attribuut een OnvolledigeDatum (PartialDate) is, dan is de vergelijking niet triviaal. Dit wordt veroorzaakt door de variable nauwkeurigheid van de waarde van het attribuut dat moet worden vergelijken met de periode in het zoekkenmerk.

In tegenstelling tot de situatie waarbij het datatype van het te vergelijken attribuut een DatumTijd is, waarbij de nauwkeurgheid van het tijdsdeel van de DatumTijd niet bekend is, is bij het datatype OnvolledigeDatum de nauwkeurigheid wel bekend. Dit maakt de volgende regel mogelijk.

Regel

Een attribuut voldoet aan het kenmerk als de waarde van het attribuut:

onbekend is
of een volledige datum is:
- en groter of gelijk is aan de beginDatum van de periode.
- en kleiner is dan de (eindDatum + 1 dag) van de periode.
of een jaartal en maand is:
- en groter of gelijk is aan het jaartal en maand van de beginDatum van de periode.
- en kleiner is dan de het jaartal en maand van de (eindDatum + 1 dag) van de periode.
of een jaartal is:
- en groter of gelijk is aan het jaartal van de beginDatum van de periode.
- en kleiner is dan het jaartal van de (eindDatum + 1 dag) van de periode.

Voorbeelden

Voorbeeld 1: Attribuut (OnvolledigeDatum) moet worden vergeleken met een periode vanaf 10-11-2024 tot en met 07-01-2025.

Als eerste stap wordt de ‘vanaf-tot-en-met’ periode geconverteerd naar een ‘vanaf-tot’ periode door de einddatum ter verhogen met één dag. Daarna worden voor zowel de begindatum als de einddatum van de periode 3 varianten berekend, namelijk met een nauwkeurigheid van een volledige datum, een jaartal en maand en alleen een jaartal. Merk op dat in dit geval de geconverteerde einddatum 8-1-2025 cq 02-2025 cq 2026 van de periode buiten de geldige periode valt.

Daarna kan voor alle relevante objecten afhankelijk van de nauwkeurigheid van het attribuut de waarde ervan worden vergeleken met de bijpassende varianten van de begindatum en einddatum van de periode. Merk op dat de attribuutwaarden bestaan uit een variable nauwkeurigheid (volledige datum, jaartal en maand, jaartal, onbekend).

Motivatie

De waarde ‘onbekend’ heeft een uitzonderlijke betekenis: het gegeven is aanwezig maar de waarde ervan is niet bekend. In lijn met de definitie van het datatype PartialDate (Onvolledige datum) in de Handreiking aanleveren BRO-gegevens voldoet het attribuut aan het kenmerk als het attribuut de waarde onbekend heeft. Bijvoorbeeld:

We zoeken naar boorgaten waarvan de startdatum ligt in een bepaalde periode.
Een bepaald boorgat heeft de waarde onbekend voor de startDate van het primaire traject.
Omdat we weten dat het boren is begonnen, voldoet het boorgat aan het kenmerk, ondanks dat we niet precies weten wanneer het boren is begonnen.

Uitsluiten van de waarde onbekend zou tot gevolg hebben dat objecten met deze waarde nooit voldoen aan het kenmerk en een afnemer deze objecten nooit zou vinden. Bij de gestipuleerde regel verschijnen objecten met de waarde onbekend altijd in het zoekresultaat, waarbij de afnemer de mogelijkheid heeft objecten met de waarde onbekend te negeren.

Voor de overige drie gevallen wordt de waarde van het attribuut vergeleken met een bij de nauwkeurigheid van het attribuut passende geconverteerde waarden van de begindatum en einddatum van de periode. Het maken van de geconverteerde waarden is een een orde-grootte-nul bewerking. Daarna kan het attribuut direct worden vergeleken met een bijpassende geconverteerde waarde.