Vardef

Sist endret

January 31, 2025

Warning

Vardef er foreløpig kun tilgjengelig i test-miljøet og er ikke i produksjon.

Vardef er SSBs system for dokumentasjon av variabler. Vardef består av et sentralt datalager som man kan interagere med via et API. Statistikere og forskere i SSB kan interagere med systemet gjennom Vardef-delen av Python-pakken dapla-toolbelt-metadata.

Brukerdokumentasjonen for Vardef er skrevet i notebooks som er ferdig installert i tjenesten Vardef-forvaltning i Dapla Lab. Det er opprette egne notebooks for typiske arbeidsoppgaver man ønsker å gjøre i Vardef, og brukeren kan kjøre disse uten å skrive kode selv. I notebooks-ene finner man ferdigskrevet kode som bruker dapla-toolbelt-metadata for å jobbe med Vardef. Hvis man ønsker å se innholdet i notebooks uten å starte tjenesten Vardef-forvaltning, så kan gå inn på lenkene til høyre på denne siden.

På denne siden dokumenteres hvordan notebooks’ene i Vardef-forvaltning kan benyttes for å gjøre ulike arbeidsoppgaver knyttet til Vardef.

Forberedelser

For å jobbe med Vardef i Vardef-forvaltning må man først gjøre følgende:

  1. Logge deg inn Dapla Lab
  2. Åpne Tjenestekatalog og trykke Start for Vardef-forvaltning
  3. Under Data velger du hvilket team og tilgangsgruppe du skal representere i tjenesten.
  4. Trykk Start

Siden det er Dapla-team og tilgangsgrupper i teamene som forvalter variabeldefinisjoner i Vardef, så er det svært viktig at man velger riktig under punkt 3. Hvis man skal opprette en ny definisjon så er det teamet man logger seg inn med i Vardef-forvaltning som blir automatisk satt som eier av definisjonen. Tilsvarende er tilfellet for endringer; man må logge seg inn som det teamet som forvalter en variabeldefinisjon for å kunne gjøre endringer.

Funksjonalitet

Under finner dere beskrivelser av hvordan man gjør typiske operasjoner mot Vardef.

Migrere fra Vardok

Ønsker man å migrere en variabeldefinisjon så kan man kjøre notebooken migrer_variabeldefinisjon.ipynb.

Kjør gjennom notebook’en og skriv inn variabeldefinisjonens ID i Vardok når man blir bedt om det. Alle seksjonsledere har oversikt over hvilke ID’er fra Vardok som deres seksjon er ansvarlig for.

Når notebook’en er kjørt gjennom så er variabeldefinisjonen migrert fra Vardok til status Utkast i Vardef. I denne prosessen oppdaterer dapla-toolbelt-metadata all informasjon som kan utledes automatisk, og deretter må brukeren oppdatere gjenværende informasjon før de publiserer den internt eller eksternt.

Oppdatere utkast

Et utkast kan oppdateres ved å kjøre notebooken rediger_utkast_variabeldefinisjon.ipynb. Den skriver variabeldefinisjonen ned til en fil som brukeren kan gjøre endringer i. Når endringene er gjort, så kan man oppdatere utkastet i slutten av notebooken.

Publisere utkast

Når brukeren er fornøyd med utkastet og ønsker å publisere, så kan man velge å publisere internt eller eksternt. Ved migrering av tidligere eksternt publiserte definisjoner fra Vardok, så er hovedregelen at også man publiserer variabeldefinisjonen eksternt i Vardef.

Man kan publisere en variabeldefinisjon eksternt ved å kjøre notebook’en publiser_variabeldefinisjon_eksternt.ipynb.

Man kan publisere en variabeldefinisjon internt ved å kjøre notebook’en publiser_variabeldefinisjon_internt.ipynb.

Ny variabeldefinisjon

For å opprette en ny variabeldefinisjon må man først opprette et utkast, deretter redigere utkastet og til slutt publisere. Da vil man bruke følgende notebooks:

  1. ny_variabeldefinisjon.ipynb
  2. rediger_utkast_variabeldefinisjon.ipynb
  3. publiser_variabeldefinisjon_internt.ipynb eller publiser_variabeldefinisjon_eksternt.ipynb

Ny gyldighetsperiode

Ny gyldighetsperiode i Vardef betyr at man ønsker å gjøre endringer i en eksisterende variabeldefinisjon som gjør at den får en ny betydning. Dette betyr at definisjonsteksten endres, og denne endringen krever at den får en ny gyldighetsperiode. Dette kan kun gjøres på variabeldefinisjoner som allerede er publisert internt eller eksternt.

For opprette en ny gyldighetsperiode kan man kjøre gjennom notebooken ny_gyldighetsperiode_variabeldefinisjon.ipynb.

Her blir man bedt om å oppgi kortnavnet til variabeldefinisjonen som skal ha ny gyldighetsperiode, deretter skrives den til en fil hvor endringer kan gjøres. Til slutt oppdateres variabeldefinisjonen i Vardef.

Patch

En patch i Vardef er en mindre endring som ikke endrer betydningen av variabeldefinisjonen. Man kan opprette en patch ved å kjøre notebook’en rediger_publisert_variabeldefinisjon.ipynb.

Lese ut informasjon

For å hente ut informasjon fra Vardef finnes det ulike notebooks avhengig av hva man ønsker å hente ut.

En variabeldefinisjon

Notebooken les_variabeldefinisjon.ipynb lar deg hente ut informasjon om en konkret variabeldefinisjon. Man kan hente ut all informasjon om variabeldefinisjonen, eller hente ut noen få informasjonselementer.

Alle variabeldefinisjoner

Notebooken les_variabeldefinisjoner.ipynb lar deg hente ut informasjon om alle variabeldefinisjoner og filtrere disse basert på ulike kriterier.

Ledige kortnavn

Notebooken sjekk_kortnavn_variabeldefinisjon.ipynb lar deg sjekke om et kortnavn er tatt eller ikke. Kortnavn i Vardef må være unikem, så det kan være lurt å sjekke om ønsket kortnavn er ledig før man prøver å publisere.

Arbeide med YAML-filer

Caution

Fargene i YAML-eksemplene er kun veiledende og kan variere fra verktøy til verktøy, ettersom de settes av automatisk syntaksutheving.

YAML-filstruktur

YAML-filene følger samme grunnstruktur, med små variasjoner avhengig av bruk.

Mal

Denne filen genereres når du vil opprette en ny variabeldefinisjon.

# --- Variabeldefinisjon mal ---
Filnavn mal

Lagres som variable_definition_template_<timestamp>.yaml

NB! Innholder eksempelverdier som må endres 
contact:
    title:
        nb: |-
            generert tittel
        nn:
        en:

I noen tilfeller settes verdien automatisk av systemet. For eksempel:

variable_status: DRAFT

Variabeldefinisjon

Dette er en YAML-fil med alle lagrede verdier for en variabeldefinisjon.

# --- Variabeldefinisjon ---
Filnavn variabeldefinisjon

Lagres som variable_definition_<kortnavn>_<id>_<timestamp>.yaml

Redigere YAML-filen

Enkle verdier

  • Verdien skrives på samme linje som feltnavn (nøkkel)
  • Bruk doble fnutter ""
Felt med enkle verdier
  • classification_reference
  • measurement_type
  • external_reference_uri
  • owner.team
Korrekt plassering og format 
short_name: "landbak"

measurement_type: "03"
Vanlige feil enkle verdier
Feil plassering av verdi 
measurement_type: 
"03"
Feil innrykk mellom nøkkel og verdi 
classification_reference:"91"
Mangler kolon 
short_name"landbak"
Feil verdi type 
# Hvis fnuttene fjernes vil verdien tolkes som et tall og validering vil feile.
measurement_type: 03

Flerspråklige felt

  • Et blokk symbol |- følger feltnavn(nøkkel).
  • Teksten må starte rett under blokk-symbolet
  • Riktig innrykk er viktig
  • Formattering (avsnitt/linjeskift) lagres.
Flerspråklige felt
  • name
  • definition
  • comment
  • contact.title
Korrekt plassering av tekst under blokk-symbol 
contact:
    title:
        nb: |-
            Her starter teksten akkurat under blokk symbolet og vil lagres uten feil.
        nn:
        en:
    email: generert@ssb.no
Korrekt lagring av avsnitt 
comment:
    nb: |-
        Her er det en god plan, først er det en beskrivelse som innledning.

        Deretter bevisst en blank linje:
          - Liste-element 1
          - Liste-element 2
    nn:
    en:
Bruk av spesialtegn 
name:
    nb: |-
        Her er kan vi lagre spesialtegn som : men det kan føre til feil syntaksutheving.
    nn:
    en:
Vanlige feil flerspråklige felt
Uønsket tekstoppsett (linjeskift midt i ord) 
name:
    nb: |-
        Her deles teksten opp
        plutselig. Og den vil lagres akku-
        rat slik du ser den.
    nn:
    en:
Feil indentering (mangler korrekt innrykk) 
name:
    nb: |-
Her er teksten ikke indentert og vil føre til feil når du lagrer.
    nn:
    en:
Mangler blokk-symbolet 
comment:
    nb: Her er blokk symbolet fjernet og tekst med ':' vil feile.
    nn:
    en: Also text with paragraphs
    will not be saved correctly.

Lister

  • Verdien skrives på samme linje som liste-symbolet -
  • Bruk doble fnutter ""
Felt med lister
  • unit_types
  • subject_fields
  • related_variable_definition_uris
  • owner.groups
Korrekt listeformat og indentering 
unit_types:
    - "20"
Vanlige feil lister
Feil type i listeelementer 
unit_types:
    - 01
    - 02
Feil indentering på liste-symbol 
unit_types:
- "20"
Feil indentering ved listeverdi 
subject_fields:
  -"bf"

Andre typer

Dato 
valid_from: 2003-01-01
Boolean 
contains_special_categories_of_personal_data: true
Variabel status 

variable_status: DRAFT

variable_status: PUBLISHED_INTERNAL

variable_status: PUBLISHED_EXTERNAL

YAML-fil: Ny variabeldefinisjon

# --- Variabeldefinisjon mal ---
name:
    nb: |-
        Buss
    nn:
    en:
short_name: "bus"
definition:
    nb: |-
        Buss er en motorvogn som er spesialkonstruert for å frakte mange passasjerer.
    nn:
    en:
classification_reference:
unit_types:
    - "15"
subject_fields:
    - "tr01"
contains_special_categories_of_personal_data: false
measurement_type:
valid_from: 2025-04-01
valid_until:
external_reference_uri:
comment:
related_variable_definition_uris:
contact:
    title:
        nb: |-
            Seksjon for Nærings- og miljøstatistikk
        nn:
        en:
    email: s400@ssb.no

# --- Statusfelt. Verdi 'DRAFT' før publisering. Ikke rediger hvis du oppretter en ny variabeldefinisjon. ---
variable_status: DRAFT

# --- Eierteam og grupper. Ikke rediger hvis du oppretter en ny variabeldefinisjon, verdien genereres ---
owner:
    team: "aordning-register"
    groups:
        - "aordning-register-developers"

# --- Maskin-genererte felt. Ikke rediger. ---
id: "wypvb3wd"
patch_id: 1
created_at: 2025-01-11 08:15:19.038000+00:00
created_by: "ano@ssb.no"
last_updated_at: 2025-01-11 08:15:19.038000+00:00
last_updated_by: "ano@ssb.no"

YAML-fil: Redigere utkast

Endre:

  • short_name
  • contains_special_categories_of_personal_data

Legge til:

  • classification_reference
  • external_reference_uri
  • subject_fields
# --- Variabeldefinisjon ---
name:
    nb: |-
        Buss
    nn:
    en:
short_name: "reg_bus"
definition:
    nb: |-
        Buss er en motorvogn som er spesialkonstruert for å frakte mange passasjerer.
    nn:
    en:
classification_reference: "111"
unit_types:
    - "15"
subject_fields:
    - "tr01"
    - "tr04"
contains_special_categories_of_personal_data: true
measurement_type:
valid_from: 2025-01-01
valid_until:
external_reference_uri: "https://www.norges-motorvignforbund.no"
comment:
related_variable_definition_uris:
contact:
    title:
        nb: |-
            Seksjon for Nærings- og miljøstatistikk
        nn:
        en:
    email: s400@ssb.no

# --- Statusfelt. Verdi 'DRAFT' før publisering. Ikke rediger hvis du oppretter en ny variabeldefinisjon. ---
variable_status: DRAFT

# --- Eierteam og grupper. Ikke rediger hvis du oppretter en ny variabeldefinisjon, verdien genereres ---
owner:
    team: "aordning-register"
    groups:
        - "aordning-register-developers"

# --- Maskin-genererte felt. Ikke rediger. ---
id: "wypvb3wd"
patch_id: 1
created_at: 2025-01-11 08:15:19.038000+00:00
created_by: "ano@ssb.no"
last_updated_at: 2025-01-11 08:15:19.038000+00:00
last_updated_by: "ano@ssb.no"

YAML-fil: Redigere publisert

Endre:

  • Rette skrivefeil i external_reference_uri

Legge til:

  • verdier på norsk nynorsk og engelsk:
    • name
    • definition
    • contact.title
  • owner.groups
  • related_variable_definition_uris
  • measurement_type
# --- Variabeldefinisjon ---
name:
    nb: |-
        Buss 
    nn: |-
        Buss
    en: |-
        Bus
short_name: "reg_bus"
definition:
    nb: |-
        Buss er en motorvogn som er spesialkonstruert for å frakte mange passasjerer.
    nn: |-
        Buss er eit køyretøy som er spesialkonstruert for å frakte mange passasjerar.
    en: |-
        A bus is a motor vehicle that is specially designed to carry many passengers.
classification_reference: "111"
unit_types:
    - "15"
subject_fields:
    - "tr01"
    - "tr04"
contains_special_categories_of_personal_data: true
measurement_type: "02"
valid_from: 2025-01-01
valid_until:
external_reference_uri: "https://www.norges-motorvognforbund.no"
comment:
related_variable_definition_uris:
    - "https://example.com/"
contact:
    title:
        nb: |-
            Seksjon for Nærings- og miljøstatistikk
        nn: |-
            Seksjon for Nærings- og miljøstatistikk
        en: |-
            Section for Industrial and Environmental Statistics
    email: s400@ssb.no

# --- Statusfelt. Verdi 'DRAFT' før publisering. Ikke rediger hvis du oppretter en ny variabeldefinisjon. ---
variable_status: PUBLISHED_INTERNAL

# --- Eierteam og grupper. Ikke rediger hvis du oppretter en ny variabeldefinisjon, verdien genereres ---
owner:
    team: "aordning-register"
    groups:
        - "aordning-register-developers"
        - "arbmark-aku-developers"

# --- Maskin-genererte felt. Ikke rediger. ---
id: "wypvb3wd"
patch_id: 1
created_at: 2025-01-11 08:15:19.038000+00:00
created_by: "ano@ssb.no"
last_updated_at: 2025-03-25 10:15:19.038000+00:00
last_updated_by: "ano@ssb.no"

YAML-fil: Ny gyldighetsperiode

Legge til:

  • comment

Endre:

  • valid_from
  • definition
# --- Variabeldefinisjon ---
name:
    nb: |-
        Buss 
    nn: |-
        Buss
    en: |-
        Bus
short_name: "reg_bus"
definition:
    nb: |-
        Buss er en motorvogn som er spesialkonstruert for å frakte flere enn 
        16 passasjerer.
    nn: |-
        Buss er eit køyretøy som er spesialkonstruert for å frakte flere enn 
        16 passasjerar.
    en: |-
        A bus is a motor vehicle that is specially designed to carry more than 
        16 passengers.
classification_reference: "111"
unit_types:
    - "15"
subject_fields:
    - "tr01"
    - "tr04"
contains_special_categories_of_personal_data: true
measurement_type: ""
valid_from: 2025-06-01
valid_until:
external_reference_uri: "https://www.norges-motorvognforbund.no"
comment:
    nb: |-
        Krav til spesifikasjon av antall passasjerer i en buss for å skille "buss" fra "minibuss".
    nn: |-
        Krav til spesifikasjon av talet på passasjerar i ein buss for å skilje 
        mellom «buss» og «minibuss».
    en: |-
        Requirements for specification of the number of passengers in a bus to distinguish 
        "bus" from "minibus".
related_variable_definition_uris:
    - "https://example.com/"
contact:
    title:
        nb: |-
            Seksjon for Nærings- og miljøstatistikk
        nn: |-
            Seksjon for Nærings- og miljøstatistikk
        en: |-
            Section for Industrial and Environmental Statistics
    email: s400@ssb.no

# --- Statusfelt. Verdi 'DRAFT' før publisering. Ikke rediger hvis du oppretter en ny variabeldefinisjon. ---
variable_status: PUBLISHED_INTERNAL

# --- Eierteam og grupper. Ikke rediger hvis du oppretter en ny variabeldefinisjon, verdien genereres ---
owner:
    team: "aordning-register"
    groups:
        - "aordning-register-developers"
        - "arbmark-aku-developers"

# --- Maskin-genererte felt. Ikke rediger. ---
id: "wypvb3wd"
patch_id: 2
created_at: 2025-01-11 08:15:19.038000+00:00
created_by: "ano@ssb.no"
last_updated_at: 2025-04-05 11:15:19.038000+00:00
last_updated_by: "ano@ssb.no"