search

arkivverket / noark5-tjenestegrensesnitt-standard

6 stars 11 forks source link

Hvordan skal Noark overgang til 5v5 håndteres? #71

Open petterreinholdtsen opened 5 years ago

petterreinholdtsen commented 5 years ago

Dette er en kopi av mangelmelding sendt inn til Arkivverket, se også https://github.com/petterreinholdtsen/noark5-tester/blob/master/mangelmelding/sendt/2019-03-05-noark-5v5.md.

       Prosjekt  NOARK 5 Tjenestegresesnitt
       Kategori  Versjon 1.0 beta
    Alvorlighet  kommentar
   Meldingstype  utelatt
Brukerreferanse  pere@hungry.com
    Dokumentdel  6.1.1.1
     Sidenummer  12
    Linjenummer  n/a
Innsendingsdato  2019-03-05

Beskrivelse

Gjelder også påfølgende sider til og med side 269 og alle dokumentdeler der relasjoner er navngitt.

Det er kommet ny versjon av Noark 5 versjon 5 etter at beta 1.0 av tjenestegrensesnittet ble publisert basert på versjon 4. Det bør dokumenteres hvordan denne nye versjonen skal håndteres i tjenestegrensesnittet. Relasjoner har i dag 'v4' som del av navnet (de starter på http://rel.kxml.no/noark5/v4/api/). Skal alle relasjonsnavn bytte til v5, eller skal en kun få v5-relasjoner der det er forskjell mellom v4 og v5? Hvis en API-implementasjon ønsker å støtte både versjon 4 og versjon 5, hvordan skal det i så fall gjøres? Hvis noen legger inn informasjon i arkivet i tråd med versjon 5, skal det være mulig å hente det ut i tråd med versjon 4? Hva med felter og verdier som ikke har samme semantikk i versjon 4 og versjon 5?

Et eksempel på forskjellen mellom versjon 5 og versjon 4 er at basisregistrering og registrering nå er slått sammen. Et annet eksempel er at det introduseres et nytt arkivenhet som heter arkivnotat. Dette vil ha en tydelig konsekvens på endepunktene til en implementasjon av Noark 5.

Frem til håndtering av versjon 4 versus version 5 er beskrevet er det ikke mulig å støtte Noark 5 versjon 5 i tjenestegrensesnittet.

Eventuelt relasjonsnavnebytte bør ses i sammeneheng med mangelmelding #55 om bytte av DNS-domene for relasjonsnavnene til et DNS-domene under Arkivverkets eierskap.

Ønsket endring

Enten bør hele tjenestegrensesnitt-spesifikasjonen endres til å kun bruke v5-relasjoner, felter og semantikk, eller så må det beskrives hvordan en API-tjeneste skal tilby både v4 og v5-relasjoner og tjenester.

Dagens spesifikasjon er kun et utkast og det finnes ingen aktør som har tatt det i bruk i produksjon. Det gjør det mindre problematisk å bytte alle relasjoner enn om det eksisterte løsninger i produksjon. Det begrenser også behovet for å støtte versjon 4. Men behovet for å oppdatere relasjoner og tilbydte tjenester vil komme igjen, så det er like greit å definere en prossess og metode for å håndtere nye versjoner av Noark 5, slik at sammen tilnærming kan brukes når det kommer ny versjon etter versjon 5 også.

petterreinholdtsen commented 5 years ago

En ide for å håndtere flere versjon er å definere en .well-known URI i tråd med RFC 5785 der en opplyser hvilke versjoner av tjenestegrensesnittet som er tilgjengelig og hvilket startpunkt en skal bruke for hver av dem.

{
  "_links": [
    {
      "rel": "https://api.arkivverket.no/noark5/ts/v5/",
      "href": "http://my-site/noark5api/v5/"
    },
    {
      "rel": "https://api.arkivverket.no/noark5/ts/v6/",
      "href": "http://my-site/noark5api/v6/"
    }
  ]
}

Dette vil tillate API-klienter å velge hvilken versjon de ønsker å forholde seg til, og gjør det mulig for API-tjenester å velge og annonsere hvilken versjon de støtter.

petterreinholdtsen commented 5 years ago

Er det forresten noen som vet hvor XML-skjemaene for versjon 5 ligger? Er http://schema.arkivverket.no/N5/latest/ versjon 5? Den er litt forskjellig fra innholdet i http://schema.arkivverket.no/N5/v4.0/ , men jeg trodde det skulle være større endringer.

joergen-vs commented 5 years ago

De ligger på Arkivverkets github-område, blir lagt ut på schema-serveren når de er ferdige. N5/latest er versjon 4, forskjellen lå i noe brannslukking rundt ekstra tillatte verdier.

petterreinholdtsen commented 5 years ago

Aha. Jeg trodde versjon 5 var ferdig før jul, inklusive XML-skjema, derav min forvirring. Hvis skjemaene ikke er ferdig, kanskje noen kan sikre at mimeType (mangelmelding #77) kommer inn i metadatakatalog.xsd før endelig versjon gis ut?

petterreinholdtsen commented 5 years ago

Jeg ble tipset om at gjeldende utkast til skjema for 5v5, som altså ikke er ferdige, er tilgjengelig fra https://github.com/arkivverket/schemas/tree/avlevering-wip/N5/v5.0 . Det er dermed en god plass å se hva som så langt har kommet inn i de nye skjemaene.

tsodring commented 5 years ago

Dette blir nok litt på siden av diskusjonen her men jeg ser en mismatch mellom XSDen og tjenestegrensesnittet på:

Det virker som om disse mangler i XSD n5v4. Der er det bare:

<xs:complexType name="korrespondansepart">

Det bør kanskje opprettes mangelmelding på dette. Det kan ikke være riktig at XSD'n skal ferdigstilles ved siden av tjenestegrensesnittet og det er en slik mismatch på metadata.

petterreinholdtsen commented 5 years ago

Kan vi spesifisere tjenestegrensesnittet på en måte som fungerer med både v4 og v5? Kan KorrespondansePart arve fra Part, og API-et tillate begge?

tsodring commented 5 years ago

At KorrespondansePart skal arve fra Part er nok riktig. Tror poenget med Part var å kunne slå sammen sakspart og korrespondansePart og slippe to ulike entiteter som peker egentlig til det samme. Problemet er vel at ingen sørget for at KorrespondansepartEnhet, KorrespondansepartPerson og KorrespondansepartIntern ble med i n5v4 og nå n5v5. Men kanskje det er ønskelig å kaste bort ekstra metadata og bare lagre det som står under Part. Men det virker litt rart.

petterreinholdtsen commented 5 years ago

Når jeg studerer dette nærmere, så ser jeg jo at spriket i felter mellom API-parter og deponi-XML-parter også eksisterer for n5v4. F.eks. mangler XML-schema virksomhetsspesifikkeMetadata for korrespondansepart, og både korrespondansepart og sakspart mangler felt for organisasjonsnummer, d-nummer og fødselsnummer. Det er dermed i det blå hvordan denne informasjonen skal avleveres fra API til XML.

Uansett har @monadani nevnt at API-spesifikasjonen skal ferdigstilles mot n5v4, slik at denne problemstillingen nok hører hjemme i en annen mangelmelding.

petterreinholdtsen commented 5 years ago

Jeg opprettet mangelmelding #80 for å diskutere hvordan korrespondansepart og sakspart skal kunne avleveres som XML.

petterreinholdtsen commented 5 years ago

Apropos endring av API, det er ikke bare vi som har den utfordringen:

monadani commented 5 years ago

Veldig bra Petter 😂😂😂

Mvh Arkivverket Mona Danielsen🌸 Sendt fra min iPhone

  1. apr. 2019 kl. 18:25 skrev petterreinholdtsen notifications@github.com<mailto:notifications@github.com>:

Apropos endring av API, det er ikke bare vi som har den utfordringen:

[https://camo.githubusercontent.com/690fc74423efc4ec75edf99832a8ea6bd4c7a50f/68747470733a2f2f7777772e636f6d6d697473747269702e636f6d2f77702d636f6e74656e742f75706c6f6164732f323031392f30342f53747269702d42612d6a74652d6c61692d6469742d3635302d66696e616c656e676c69736856332e6a7067]https://camo.githubusercontent.com/690fc74423efc4ec75edf99832a8ea6bd4c7a50f/68747470733a2f2f7777772e636f6d6d697473747269702e636f6d2f77702d636f6e74656e742f75706c6f6164732f323031392f30342f53747269702d42612d6a74652d6c61692d6469742d3635302d66696e616c656e676c69736856332e6a7067

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/issues/71#issuecomment-481762249, or mute the threadhttps://github.com/notifications/unsubscribe-auth/ArpLluGRSEeyGN_3fK10z-HcMY4ayk20ks5vfhB1gaJpZM4bemqU.

petterreinholdtsen commented 5 years ago

For å få bedre oversikt over hvilke endringer som må gjøres i API-spesifikasjonen for å gjøre den i tråd med Noark 5 versjon 5 i stedet for versjon 4, så har jeg laget en gren i min depotklone med et utkast til endringer.

Jeg har ikke flyttet entiteter mellom pakker, for a gjøre det enklere å se hvilke konkrete endringer som må gjøres i teksten. Det bør gjøres hvis endringen skal tas med i spesifikasjonen. Endringene er basert på endringene i arkivstruktur.xsd mellom version 4.0 og 5.0 slik de er tilgjengelig fra https://github.com/arkivverket/schemas/tree/master/N5/v5.0.

Følgende endringer må gjøres:

Denne inkluderer endringsforslag #159 for mangelmelding #145.

Merk at endringen ikke løser noen av de uløste problemet rundt manglende beskrivelse av nyregistrering, oppdatering og avlevering av entiteter i API-et, kun omstrukturerer API-et til å følge Noark 5 versjon 5.0.

Jeg er ikke overbevist om at det er noe poeng å bytte navn fra Graderingskode til Grad i API-et, men har gjort det for kompletthets skyld i denne gjennomgangen. Avleverings-programmer kan uansett bytte navn på dette feltet ved avlevering, slik at tjenestegrensesnittet godt kan ha et bedre og mer beskrivende navn på feltet enn deponi-XML-en.

Jobben med å finne endringer mellom versjon 4.0 og 5.0 ble vanskeliggjort ved at XSD-skjemaene for både 4.0 og 5.0 har misvisende og mangelfulle endringsoversikter i en kommentar i starten av filene. Det er greit å ha i bakhodet hvis du vil sjekke om jeg har gjort det riktig.

Du finner grenen på https://github.com/petterreinholdtsen/noark5-tjenestegrensesnitt-standard/tree/migrate-to-n5v5 . Jeg har ikke sendt den inn som endringsforslag, da jeg tenker den bør få litt mer korrekturlesing og overnevnte omstrukturering før den er klar til slikt.

-- Vennlig hilsen Petter Reinholdtsen

tsodring commented 5 years ago

Tenker vi bør også sende inn en konkret endringsforslag på å fikse XSD slik at arkivtruktur.xsd kan håndtere de oppdaterte Korrespondansepart utvidelsene. Ikke noe poeng å kaste slik informasjon!

petterreinholdtsen commented 5 years ago

Merk, det meldes i https://github.com/arkivverket/schemas/pull/7 at pronomPUID og pronomMIME var tatt med ved en feiltakelse og nå er fjernet igjen fra XML-skjemaet.

petterreinholdtsen commented 5 years ago

Jeg ser at det er veldig lite endring mellom versjon 4 og versjon 5, slik at det vil være fort gjort å endre spesifikasjonen til å gjelde for versjon 5. Det tok meg ca. 1.5-2 timer å lage endringen i migrate-to-n5v5.

De som vil se konkret hva som er endret, å kan besøke https://github.com/arkivverket/noark5-tjenestegrensesnitt-standard/compare/master...petterreinholdtsen:migrate-to-n5v5?expand=1 .

petterreinholdtsen commented 5 years ago

Det meldes videre at det var en feil i XSD-skjema for versjon 5 at registrering måtte ha minst en korrespondansepart (fikset i går), da den skulle være valgfri. Jeg har oppdatert min migrate-to-n5v5-gren tilsvarende.

Jeg har oppdaget en veldig forvirrende endring i XSD-skjema for versjon 5. En registrering har valgfri kobling til både part og korrespondansepart. Tidligere, var sakspart (i v5 kalt part) kun knyttet til saksmappe, der det gir mening. En part er slik jeg forstår det en juridisk aktør i en sak, og jeg forstår ikke hvorfor et dokument (aka registrering) skal kunne knyttes til parter slik. Noen som vet om det også er en feil i arkivstruktur.xsd for versjon 5?

Så vidt jeg kan se er det ikke noe som hindrer oss å omstrukturere Part/Korrespondansepart i API-et til å gjenbruke en felles entitet der de er like, ala det jeg skisserer i mangelmelding #80. API-et gjør allerede tilsvarende omstruktureringer med EnkelAdresse, og jeg tror det er lurt å gjøre det samme for Part/Korrespondansepart, der kun partrolle og korrespondanseparttype er unikt for Rolle og Korrespondansepart, og resten arves fra en virtuell entitet. Jeg tror jeg avventer tilbakemelding i #80 på avleveringsproblemet før jeg forsøker å formulere en spesifikasjonsendring rundt dette.

petterreinholdtsen commented 5 years ago

Jeg har foreslått å fjerne part fra registrering i https://github.com/arkivverket/schemas/pull/11 .

tsodring commented 5 years ago

Husk at dette vil medføre en tilleggsendring at content-type blir nå

application/vnd.noark5-v5+json

ikke application/vnd.noark5-v4+json

Som vi diskuterte på IRC, kanskje '-4' skal droppes. Er det noe spesiel grunn til å ha versjonnummer i content-type, hvis ikke det skal være mulig kombinere v4 og v5 innhold.

tsodring commented 5 years ago

til orientering. Jeg har nå laget en branch av nikita som implementerer Noark 5v5. Dette tar utganspunkt i listen til @petterreinholdtsen og krysssjekk av Noark 5v5 standarden og relevant XSD-filer. Det var uproblematisk å implentere domenemodellen.

Håper dere kan konkludere at tjenestegrensesnittet kan ferdigstilles på Noark 5v5.

petterreinholdtsen commented 5 years ago

Godt poeng, @tsodring, Content-type må byttes, både for JSON (og XML, med mindre vi kan droppe XML og slippe bruke mer tid der). Jeg foreslår å droppe -v4, slik at en slipper å bytte Content-type når nye Noark5-versjoner tas i bruk. På den andre side, kanskje Content-type er måten å håndtere oppgraderinger til nye Noark5-versjoner, slik at en forteller API-tjener hvilken versjon en støtter ved hjelp av Content-type-versjone. Hva tror dere andre?

tsodring commented 5 years ago

Fordelen er at endringene i standarden blir tydelig. Ulempen er at det kan bli litt uklar. Feks arkivenheten arkivdel vil kanskje ikke endre seg fra en versjon til en annen. La oss ta en hypotetisk oppgradering fra n5v5 til n5v6.

Med versjonnummer: Alle nyttelaster har oppgradert nummer

application/vnd.noark5-v6+json

Ingen versjonnummer: Det er rel'ene som identifiserer versjoner av standarden.

Kombinasjoner versjonnummer: arkivdel -> n5v5 (ingen endring) mappe -> n5v6 (lagt til flere attributter)

Arkivdelen er jo også oppgradert så det kan være litt misvisende å bruke kombinasjoner.

Jeg tror ingen versjonnummer er riktig, men å la rel'ene bestemme versjon av standard og forventet innhold. Bruken av GET på ny-* sammen med versjonnummer i rel bør være dekkende for å gi klienten nok informasjon.

tsodring commented 5 years ago

Jo mer jeg ser på vår oppgradering av nikita til Noark 5v5, jo mer sikker jeg blir at tjenestegrensesnittet må standardiseres på n5v5.

Tenk deg hvis du er en leverandør og får n5v4 i fanget og må bruke masse tid og penger på utforske og implementere tjenestegrensesnittet. Så vet du at du må implementere n5v5 for å få godkjenning. Da hadde ikke jeg giddet å bruke tid på tjenestegrensesnittet! Da hadde jeg ventet til tjenestegrensesnittet også ble oppgradert til n5v5.

petterreinholdtsen commented 5 years ago

Jeg har oppdatert https://github.com/petterreinholdtsen/noark5-tjenestegrensesnitt-standard/tree/migrate-to-n5v5 , og basert den på dagens master med nye relasjonsnøkler. Samlet alle endringer til en felles endring og justerte litt på spesifikasjonsteksten for Registrering i samme slengen.

monadani commented 5 years ago

Er denne ok?