Klarere, entydig og mer kompakt representasjon av kodeliste-verdier i JSON for instanser

[petterreinholdtsen]

Dette er en mangelmelding som kun er registrert på github, og ikke er sendt inn til Arkivverkets postmottak. Se også https://github.com/petterreinholdtsen/noark5-tester/blob/master/mangelmelding/sendt/2019-04-20-json-kodeliste-verdi.md .

---

       Prosjekt  Noark 5 Tjenestegresesnitt
       Kategori  versjon git 2019-04-19
    Alvorlighet  protest
   Meldingstype  utelatt
Brukerreferanse  [email protected]
    Dokumentdel  6.1.1.6 (Utvid objekter til andre typer)
     Sidenummer  34
    Linjenummer  n/a
Innsendingsdato  2019-04-20

---

Denne teksten er del av en samling innspill til Noark5-standarden tilgjengelig fra https://github.com/petterreinholdtsen/noark5-tester/.

Beskrivelse

I kapittel 6 vises det hvordan verdier fra kodelister skal representeres i JSON. Det er ikke gjort konsistent. Flere eksempler viser det slik:

"saksstatus": {
    "kode": "R",
    "beskrivelse": "Opprettet av saksbehandler"
},

Et annet eksempel inneholder ikke «beskrivelse» (også lenger ned i den samme JSON-strukturen som bruker både «kode» og «beskrivelse» i overnevnte eksempel):

"graderingskode": {
    "kode": "B"
},

Det er ikke beskrevet når «beskrivelse» skal brukes og når den kan droppes i JSON som representerer en kodelisteverdi. Det er også uklart hvorfor «beskrivelse» er tatt med i hver JSON-representasjon av instanser, når den kan hentes ut fra kodelistene ved behov.

Det er enklere for API-klienter og kortere som JSON (hvilket betyr en mer nettverkseffektiv protokoll) hvis slike henvisninger til kodelisteverdier dropper bruken av JSON-objekt (aka {...}) og i stedet bruker kodeverdien direkte som string, dvs. slik:

"graderingskode": "B",

Dette krever at alle kodeliste-koder er unike for en gitt kodeliste, hvilket bør stå eksplisitt i spesifikkasjonen.

Se forøvrig mangelmelding #147, med forslag om ny attributt «aktiv» for kodelister, hvis bruk antagelig bør beskrives på samme sted hvis det forslaget blir tatt inn i spesifikasjonen.

Ønsket endring

Beskriv i kapittel 6 hvordan JSON-strukturer som bruker kodeliste-verdier skal se ut, hva som skal sendes inn ved oppretting og endring og hva som sendes tilbake når en ber om en eller flere instanser. Endre alle eksempler til å følge denne notasjonen. Beskriv kodeliste-attributten «aktiv» og forklar hvordan klienter skal forholde seg til den ved å ikke bruke verdier der «aktiv» er «false».

Bruk kortformen der kun kode-verdi brukes ved oppretting, endring og opplisting av instanser. Nevn i kapittel 7.2.2 (Kodelister) at alle oppføringer i kodelister må ha unike kode-verdier.

Jeg sender inn konkret forslag til endring som patch via github.

[petterreinholdtsen]

Dette forslaget vil også påvirke OData-søk. Et eksempel fra kapittel 6 viser søk på en bestemt graderingskode slik:

/api/arkivstruktur/mappe/?$filter=gradering/graderingskode/kode eq 'B'

Hvis kun kodeverdien brukes i JSON-instanser, så vil søket i stedet se slik ut:

/api/arkivstruktur/mappe/?$filter=gradering/graderingskode eq 'B'

Det blir dermed ikke nødvendig å fortelle hvilken del av graderingskode-verdiene det skal søkes på, og alle slike søk vil gå mot kode.

[hanber]

Vi skal beholde objekt, vi skal ha mulighet for å bruke POST med bare kode.

[petterreinholdtsen]

Da har jeg oppdatert mitt endringsforslag til å bruke 'inaktiv' i stedet for 'aktiv' samt gjøre det klart at en enten kan oppdatere instanser med kun kode, eller både kode og beskrivelse, i tråd med det som ble diskutert på møtet 5. juni.

Jeg hadde glemt å registrere mitt forslag til endring som endringsforslag, det er nå gjort (#205).

Endringen løser ikke alle utfordringer med kodelister, men jeg mener det er et lite steg i riktig retning.