Noark metadata for koder

[sturtzel]

Gjennom GeoIntegrasjon 1.1 og senere har det vært behov for å overføre koder med både en kortkode og en beskrivelse.

Forslaget er tilpasset Noark 5 tjenestesnitt og Noark 5 datamodell samtidig som den gir bakoverkompatibilitet med eksisterende integrasjoner via GeoIntegrasjon 1.1.

Noark metadata for koder.docx

[sturtzel]

Ref. kommentarer ang. camelCase i annen issue fra GI: Det bør vurderes om M05x ergyldig bør hete erGyldig.

[hanber]

Dersom vi innfører kodelister som foreslått, eventuelt litt utvidet, bør i så fall f.eks. landkode angis med verdisett (hvilken standard det følger), siden landkoden vil være ulik for ulike objekter (som person og organisasjon) den inngår i? Faren med dette er at det kanskje vil medføre ønske om et mer omfattende kodeverk, og vi vil nødig at kodeverket i seg selv blir en kompleks struktur. @sturtzel: M05x bør hete erGyldig iht. våre skriveregler. Vi vil også gjøre de endringene i forslagene som må til for å få navningen på standard form. Ad en annen kommentar om metadatanavn og standardverdier: Vi benytter norsk orddeling når vi bruker camelCase (unntatt for forkortelsen ID). Vi bruker f.eks. systemID selv om elementet burde hete systemidentifikator.

[sturtzel]

Land er i henhold til bruk i korrespondanse. D.v.s. at det er totegnsvarianten som er aktuell. Det er ikke foreslått landkode for organisasjonsid og personid selv om disse kan tagges.

[hanber]

Jeg oppfatter kodeverdi som det som skal inneholde den lesbare verdien av metadataelementet, f.eks. "Overlappingsperiode" som verdien av arkivdelstatus, og at det er denne verdien som avleveres, og kortkodeverdi, f.eks. "O" for "Overlappingsperiode", bare benyttes i datautveksling. Er det riktig oppfattet? Vi må for all del unngå at kortkodeverdi brukes til oppslag i kode ved avlevering, slik at opprinnelig kodeverdi går tapt dersom denne er blitt endret etter at metadataelementet ble registrert. Hvor i arkivstrukturen skal i så fall kode ligge? Jeg ser for meg at det må ligge direkte under arkiv.

[sturtzel]

Kortkodeverdi tilsvarer koder slik de var i Noark 4 og er benyttes for integrasjoner, oppsett etc. Kodeverdi tilsvarer koder slik de er i Noark 5 avleveringsformat og benyttes fortsatt for dette. Kode er et objekt på toppen av begge og vil i integrasjoner benyttes "i stedet for" kodeverdi. Kodeverdi og kortkodeverdi henger sammen, så det vil ikke være mulig å endre den ene uten å endre den andre. I integrasjoner vil det enten sjekkes om den ene har verdi og hvis ikke om den andre har det, alternativt sjekkes begge og man får smekk på fingeren om det er avvik. Spesielt for objekter som saksbehandler og administrativ enhet er det et problem med at samme navn kan benyttes på forskjellige enheter. UID er mindre egnet for integrasjoner der det skal gjøres oppsett.

[petterreinholdtsen]

Jeg er veldig positiv til å kunne avlevere mer av informasjonen lagret i en Noark 5 Tjenestegrensesnitt-løsning, og håper vi kan finne feltnavn, beskrivelse og notasjon som fungerer for alle.

Noark 5 Tjenestegrensesnitt har følgende feltnavn i bruk for kodelister, som tilsvarer det som omtales i denne saken:

• kode
• kodenavn
• inaktiv

'kodenavn' tilsvarer forslagets M08x kodeverdi.

'kode' tilsvarer forslagets M08x kortkodeverdi.

'inaktiv' tilsvarer forslagets M05X 'ergyldig'. Jeg anbefaler at en bruker navnet som allerede er standardisert i Noark 5 Tjenestegrensesnitt, dvs 'inaktiv' i stedet for 'ergyldig'.

Tjenestegrensesnitt-standarden har ikke tekstlig beskrivelse i kodelistene, forslagets M021 beskrivelse eller M020 tittel. Jeg tenker i utgangspunkt at 'kodenavn' er feltets tittel, slik at M021 beskrivelse er mer egnet enn M020 tittel. Jeg har så langt ikke sett behovet for mer beskrivelse av kodelistene enn det som ligger i kode og kodenavn, og forslaget sier jo at dette som utgangspunkt skal være identisk med kodenavn og dermed overflødig. Kanskje denne heller bør droppes?

I dag er det kun 'kodenavn'-feltet som har XML-representasjon i uttrekksformatet. Jeg forstår dette forslaget til å ønske a utvide uttrekksformatet til å ta med mer av informasjonen i arkivsystemet i sin XML. Men det er litt uklart hva som konkret foreslås. I dag kan et XML-utsnitt for en kodeverdi se slik ut:

Opprettet

Er tanken å utvide til noe ala dette?

O Opprettet false

Eller er ideen å tillate alle disse:

O Opprettet O Opprettet false

Jeg tror det bør være minst mulig tolkningsrom for hvordan dette skal se ut, og liker derfor den mer verbose utgaven best.

For å være kompatibel med tidligere utgaver av Noark 5 tenker jeg at kodenavn bør være påkrevd, der denne verdien alltid må være med.

Mitt forslag til feltliste for ny entitet kodeverdi (ikke kode) er dermed følgende:

• kode (0-1) tekststreng
• kodenavn (1) tekststreng
• ergyldig (0-1) boolsk, forvalgt verdi er 'true' hvis den ikke er med.

Det gjør at dagens

Opprettet

blir til

Opprettet

-- Vennlig hilsen Petter Reinholdtsen

[petterreinholdtsen]

[Petter Reinholdtsen

Noark 5 Tjenestegrensesnitt har følgende feltnavn i bruk for kodelister, som tilsvarer det som omtales i denne saken: [...]

• inaktiv

Jeg kom nettopp på at tjenestegresesnittet faktisk har to ulike navn på en slik verdi, henholdsvis 'inaktiv' (kodelister) og 'utdatert' (virksomhetsspesifikkeMetadata). Jeg tror en av dem bør byttes ut med den andre, foreslått i https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues/268 , og at Noark 5 bør bruke sammen navn også i avleveringsformatet.

Det er altså tre navneforslag på bordet for dette feltet, 'erGyldig', 'inaktiv' og 'utdatert'. :)

-- Vennlig hilsen Petter Reinholdtsen

[petterreinholdtsen]

Det kan forresten være verdt å nevne forslaget i arkivverket/noark5-standard#95 om å ikke bruke en boolsk verdi for gjeldende/inaktiv/utdatert, men heller notere tidspunktet for når verdien ikke lenger er gyldig, og sammenligne med dagens dato for å finne ut om det er greit å bruke koden/navnet. Da kan kanskje M602 avsluttetDato, M604 arkivertDato, M613 slettetDato eller M630 kassertDato brukes?

[sturtzel]

Her ble det litt mange på en gang. Når det gjelder kortkode, full kode etc. har bruken i GI vært objekt med angivelse av om det er kortkode eller navn, ikke kun en tolkbar verdi slik det er i dagens avleveringsformat. Det er dette som er foreslått videreført.

GeoIntegrasjon 1.1 benytter erGyldig, arkivintegrasjon som har vært i almen bruk i snart 10 år. Jeg er enig i at man bør ha tilsvarende håndtering forskjellige steder. M6xx-feltene burde heller vært sanert da en del av de kan forekomme flere ganger, spesielt for koder og folk som kan gå inn og ut. Felt som aktiv/gyldig kan inngå direkte i et filter på en nedtrekksliste ved bruk og er derfor bedre egnet for disse enn dato fra/til. De komplette registrene har flere verdier enn id, kode, beskrivelse og datointervall. Bruken ved generisk koderegister er ikke helt den samme.

[petterreinholdtsen]

[Ragnar Sturtzel]

Her ble det litt mange på en gang.

Beklager hvis det ble for mye, men tenkte det var greit å få belyst saken så godt som mulig.

Når det gjelder kortkode, full kode etc. har bruken i GI vært objekt med angivelse av om det er kortkode eller navn, ikke kun en tolkbar verdi slik det er i dagens avleveringsformat. Det er dette som er foreslått videreført.

Kan du forklare hvordan du konkret ser for deg at dette skal se ut i XML? Det du skriver virker å blande GUI, API-utforming og XML, og jeg håper det blir klarere hvis du beskriver XML-representasjonen du ser for deg, gjerne basert på eksemplet jeg laget.

GeoIntegrasjon 1.1 benytter erGyldig, arkivintegrasjon som har vært i almen bruk i snart 10 år.

GeoIntegrasjon kan naturligvis fortsette å bruke erGyldig som før. Det er jo kun når innsamlet informasjon skal omformes til uttrekks-XML at en må forholde seg til eventuelt feltnavn i Noark 5.

Jeg er enig i at man bør ha tilsvarende håndtering forskjellige steder. M6xx-feltene burde heller vært sanert da en del av de kan forekomme flere ganger, spesielt for koder og folk som kan gå inn og ut. Felt som aktiv/gyldig kan inngå direkte i et filter på en nedtrekksliste ved bruk og er derfor bedre egnet for disse enn dato fra/til. De komplette registrene har flere verdier enn id, kode, beskrivelse og datointervall. Bruken ved generisk koderegister er ikke helt den samme.

Jeg antar det du skriver her blir enklere å forstå når jeg ser hva slags XML du ser for deg. Blant det som forvirrer er at jeg antar ethvert GUI vil være i stand til å sammenligne datoer og slik kunne lage en nedtrekksliste like godt der grunnlaget er boolks verdi eller dato, og klarer dermed ikke se hva dato har med eventuell nedtrekksliste i GUI å gjøre. Jeg mistenker dermed jeg har misforstått noe og håper konkrete eksempler kan gjøre ting klarere.

-- Vennlig hilsen Petter Reinholdtsen

[sturtzel]

Kode slik det ligger i GI 1.1 (og som vi har foreslått for Noark) blir noe slikt (struktur, feltnavnene våre var forskjellig):

O Opprettet false

Det er prinsippet som er viktigst for oss og vi har foreslått ut fra bruk i tjenestegrensesnitt (men en stor fordel om det er likt mellom eForsendelse Arkivmelding, FIKS Arkiv, N5WS og avleveringsformatet).

Om det skal være dato i stedet for erGyldig, bør det være generisk gyldigFra og gyldigTil da en rolle kan settes inaktiv og så aktiveres igjen. Tom verdi må da bli "fra tidenes morgen" og "til evigheten".

[petterreinholdtsen]

[Ragnar Sturtzel]

Kode slik det ligger i GI 1.1 (og som vi har foreslått for Noark) blir noe slikt (struktur, feltnavnene våre var forskjellig):

O Opprettet false

Da forstår jeg.

Joe Hans-Fredrik forklarte meg en gang slår meg når jeg ser forslaget igjen. Han sa at slike statusverdier skulle kopieres inn i arkivenheten ved registrering, og ikke endres deretter. Slik at hvis det finnes en verdikatalog over arkivstatus-verdier (O/Opprettet her) som presenteres for brukeren, så skulle ikke endringer i verdikatalogen føre til endringer i eksisterende arkivenheter, kun i fremtidig registrerte arkivenheter.

Hvis det også gjelder for 'inaktiv'-feltet, så vil vel den verdien alltid være 'false', for ellers ville en ikke kunne kopiere verdien inn i arkivenheten. Det gjør kanskje 'inaktiv' redundant i hver enkelt arkivenhet, og gir kun mening hvis selve katalogen over gyldige verdier representeres i XML-uttrekket, hvilket ikke gjøres i dagens arkivstruktur.xml.

Jeg vil gjerne ha standardisert uttrekk av en slik katalog, slik at en kan bruke XML-uttrekket til å migrere til neste arkivsystem, men mistenker det kanskje bør håndteres som separat XML- eller XSD-fil?

Det er prinsippet som er viktigst for oss og vi har foreslått ut fra bruk i tjenestegrensesnitt (men en stor fordel om det er likt mellom eForsendelse Arkivmelding, FIKS Arkiv, N5WS og avleveringsformatet).

Godt prinsipp, men detaljene er utfordringen. :)

Vet noen hvordan slike statusverdier ser ut i eForsendelse Arkivmelding, FIKS Arkiv, N5WS og avleveringsformatet og kan poste det her? Det hadde vært nyttig å ha som sammenligningsgrunnlag.

Om det skal være dato i stedet for erGyldig, bør det være generisk gyldigFra og gyldigTil da en rolle kan settes inaktiv og så aktiveres igjen. Tom verdi må da bli "fra tidenes morgen" og "til evigheten".

Enig.

-- Vennlig hilsen Petter Reinholdtsen

[sturtzel]

Kodeobjektet med erGyldig er tenkt for å hente kodelister, ikke ved bruk i objekter. Da vet klienten om dette er en verdi for kun for visning/søk eller en verdi også for registrering.

eForsendelse Arkivmelding og FIKS Arkiv (tidligere kalt GeoIntegrasjon Arkiv versjon 2) vil få samme struktur. Ref. https://github.com/ks-no/fiks-arkiv

[petterreinholdtsen]

[Ragnar Sturtzel]

Kodeobjektet med erGyldig er tenkt for å hente kodelister, ikke ved bruk i objekter. Da vet klienten om dette er en verdi for kun for visning eller en verdi også for registrering.

Aha. Da misforsto jeg bruksområdet litt.

Er tanken at en slik liste over koder skal være del av deponeringsformatet i en ny fil, eller er det kun tenkt brukt i API og til utveksling?

Hvis det skal være del av deponeringsformatet eller brukes til utveksling, antar jeg det også må lages et tekstforslag til tillegg B (kapitler/120-vedlegg_2_metadatakatalog_objektsortert.rst), i tillegg til et par YAML-filer i metadata/-katalogen.

eForsendelse Arkivmelding og FIKS Arkiv (tidligere kalt GeoIntegrasjon Arkiv versjon 2) vil få samme struktur. Ref. https://github.com/ks-no/fiks-arkiv

Jeg klarte ikke finne noe eksempel på liste over koder i det nevnte github-depotet. Hvilken fil bør jeg se i, eller misforstår jeg henvisningen?

-- Vennlig hilsen Petter Reinholdtsen

[sturtzel]

Behovet er for API, men som sagt er det en fordel med felles format for API og avlevering (avlevering må da ha med mer spesifikk info da spesielt personnavn kan være flertydige). Noark 5 har p.t. ingen beskrivelse av koderegistre andre steder enn i teksten (obligatoriske verdier = minimum). De lå i XSD-ene, men det medførte at de ikke kunne brukes i forbindelse med API (spesielt ikke for uferdig materiale) og dessuten som oftest måtte redigeres.

I GI 1.1 er kodelistene spesifisert. I GI 2.0 (FIKS Arkiv) så jeg at dette manglet (også i XSD-en). Status der er vel at vi avventet svar fra Arkivverket før vi gikk videre. Eksempler på kodelister finnes i http://geointegrasjon.no.

[petterreinholdtsen]

Jeg laget et utkast til endringsforslag for å beskrive slike lister over gyldige metadata-verdier. Ikke helt fornøyd med den tekstlige beskrivelsen, og tar gjerne imot forslag til forbedringer.

Ideen er å beskrive innholdet i en ny fil metadata.xml som ser noe ala dette ut:

<metadata>
  <kodeliste type="arkivstatus">
    <kodeverdi>
      <kode>A</kode>
      <kodenavn>Aktiv periode</kodenavn>
    </kodeverdi>
    ...
  </kodeliste>
  ...
</metadata>

Jeg er usikker på hvordan dette best beskrives i tillegg B.

[sturtzel]

Behovet er det samme i dag som i 2012. giFellesKodeliste20210131.xsd: <?xml version="1.0" encoding="UTF-8"?>

Vi hadde ikke typeangivelse der siden kodelistene ble returnert basert på tjeneste om å hente en kodeliste med et angitt navn. Når det gjelder attributtnavnene kan tittel være et bedre navn enn kodebeskrivelse. Om kode er et bedre navn enn kodeverdi er jeg litt mer usikker på, spesielt siden objektet i seg selv heter Kode.

[petterreinholdtsen]

[Ragnar Sturtzel]

Vi hadde ikke typeangivelse der siden kodelistene ble returnert basert på tjeneste om å hente en kodeliste med et angitt navn.

Aha.

Hvis jeg leser den oppgitte giFellesKodeliste20210131.xsd: riktig, så legger den opp til følgende XML-struktur

• kodeliste
  • kode
    • kodeverdi
    • kodebeskrivelse
    • erGyldig

Dagens Noark 5 Tjenestegrensesnitt har derimot litt mindre syntaktisk glassur, så der er JSON-strukturen mer slik:

• <navn på liste>
  • kode
  • kodenavn
  • inaktiv

(I realiteten er <navn på liste> i URL-en, og kode/kodenavn/inaktiv JSON-objekt i et søkeresultat, men jeg justerte presentasjonen til å passe bedre med XML-strukturen.

De tre indre feltene har så vidt jeg kan forstå, samsvarende definisjoner, der kodeverdi=kode, kodebeskrivelse=kodenavn og erGyldig="ikke inaktiv".

Jeg vet ikke hvorfor Arkitektum gikk for navnene kode og kodenavn, da jeg antar de kjente til GeoIntegrasjon, men det hadde vært nyttig å vite.

Hvis jeg forstår filen fra GeoIntegrasjon riktig blir dette XML-en:

B Under behandling ... Rent intuitivt finner jeg XML ala dette mer beskrivende: B Under behandling ... I tillegg legger den siste strukturen opp til å kunne ha alle kodelister i samme XML-fil i motsetning til GeoIntegrasjons-notasjonen som nok krever en fil per kodeliste. Slik jeg ser det er det et par ubesvarte spørsmål som vil styre hvilke valg som gir mest mening: * Bør en kunne hente ut og lagre alle kodelister i en felles fil? * Bør en ha bolsk aktiv/inaktiv eller datobasert gyldig fra/til? * Bør en holde på navnevalg gjort av Arkivverket i Noark 5 Tjenestegrensesnitt eller velge navn basert på GeoIntegrasjon? Selv heller jeg mot Ja, Nei og Ja da jeg tror det gir størst fleksibilitet, funksjonalitet og samvirke i fremtiden. -- Vennlig hilsen Petter Reinholdtsen

[sturtzel]

Hvis man har typefeltet blir unødvendig. Det er 10 år siden vi definerte GI, men jeg tipper at generisk kode som objektnavn gjorde at man kunne bruke én tjeneste for å hente og at definisjonene ble enklere.

Dato fra/til gir flere muligheter enn "gyldig", men er lite relevant for en klient (mer relevant for avlevering).

Jeg mener at det var Tor Kjetil som modellerte GI i sin tid og at det var han som også modellerte N5WS. Men uansett mener jeg det var en glipp av N5WS å ikke ta utgangspunkt i GI (uten å følge den slavisk - bl.a. objektet Kontakt i GI ble altfor komplisert).

Det hadde ellers vært en fordel om flere deltok i diskusjonene... Dessuten litt lett å overse noe når man bare har diskusjonen på en liten skjerm.

[petterreinholdtsen]

[Ragnar Sturtzel]

Dato fra/til gir flere muligheter enn "gyldig", men er lite relevant for en klient (mer relevant for avlevering).

Jeg ser to bruksområder der fra/til-dato gir mening, både for avlevering og for migrering av data mellom systemer.

Men uansett mener jeg det var en glipp av N5WS å ikke ta utgangspunkt i GI (uten å følge den slavisk - bl.a. objektet Kontakt i GI ble altfor komplisert).

Når en studerer Noark 5 Tjenestegrensesnitt-spesifikasjonen, så er det relativt åpenbart at den har tatt utgangspunkt i GeoIntegrasjon, og jeg vet med sikkerhet at definisjonen av Nasjonale Identifikatorer i Noark 5 Tjenestegrensesnitt tok utgangspunkt i GeoIntegrasjon.

Det hadde ellers vært en fordel om flere deltok i diskusjonene...

Enig. Er overbevist om at det finnes poenger vi går glipp av og vinklinger som burde vært tenkt på, og håper jo flere vil komme med sine innspill til de ulike innspillene og forslagene slik at spesifikasjonen kan bli så bra som mulig. :)

-- Vennlig hilsen Petter Reinholdtsen