PxAPI-2.yml

openapi: "3.0.2"
info:
  title: PxApi
  version: "2.0"
  description: |
    This api lets you: Find a table and extract table metadata and data.

tags:
  - name: Tables
    description: See information about  tables and extract table data.
  - name: Saved Queries
    description: Save a query for later use.
  - name: Codelists
    description: See information about  codelists.

paths:
  /tables:
    get:
      tags:
        - Tables
      summary: Get all Tables.
      operationId: ListAllTables
      parameters:
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/query"
        - $ref: "#/components/parameters/pastDays"
        - $ref: "#/components/parameters/includeDiscontinued"
        - $ref: "#/components/parameters/pageNumber"
        - $ref: "#/components/parameters/pageSize"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TablesResponse"
              examples:
                tables:
                  $ref: "./examplesAsYml/tablesResponse.yml#/tablesResponse"
  /tables/{id}:
    get:
      tags:
        - Tables
      summary: Get Table by {id}.
      operationId: GetTableById
      parameters:
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TableResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

  /tables/{id}/metadata:
    get:
      tags:
        - Tables
      summary: Get metadata about table by {id}.
      description: |
        **Used for listing detailed information about a specific table**
        * List all variables and values and all other metadata needed to be able to fetch data
      operationId: GetMetadataById
      parameters:
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/id"
        - in: query
          name: defaultSelection
          schema:
            type: boolean
            default: false
          description: |
            This is a technical parameter that is used by PxWeb for initial loading of tables.
            If metadata should be included as if default selection would have been applied see /tables{id}/defaultselection endpoint.
        - in: query
          name: savedQuery
          schema:
            type: string
            nullable: true
          description: |
            This is a technical parameter that is used by PxWeb for initial loading of tables.
            Id for a saved query that should be be applied before metadata is returned see /savedqueries.
        - in: query
          name: codelist
          description: |
            This is a technical parameter that is used by PxWeb.
            The identifier of the codelist that should be applied to the metadata.
            If not specified no codelist will be applied.
          schema:
            type: object
            additionalProperties:
              type: string
            example: |
              [
                {"variable_1": "NUTS_2008"}
              ]
          style: deepObject
          explode: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dataset"
              examples:
                Dataset-meta:
                  $ref: "./examplesAsYml/dataset-meta.yml#/dataset-meta"
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

  /tables/{id}/defaultselection:
    get:
      tags:
        - Tables
      summary: Get the default selection for table by {id}.
      description: |
            This is a technical parameter that is used by PxWeb for initial loading of tables.
            Get information about the default selection for the /tables/{id}/data endpoint.
      operationId: GetDefaultSelection
      parameters:
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SelectionResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

  /tables/{id}/data:
    get:
      tags:
        - Tables
      summary: Get data for table by {id}.
      description: |
        **Used for fetching data from a table**
        * Get data from a table by id.
        * The data can be filtered by variable codes and values.
        * The response can be formatted in different formats.
        * The placement of the variables can be customized with heading and stub variables.
        * If no selection is specified for filtering the data the default selection will be applied.
      operationId: GetTableData
      parameters:
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/id"
        - in: query
          name: valuecodes
          schema:
            type: object
            additionalProperties:
              type: array
              items:
                type: string
            example: |
              [
                {"variable_1": "1,2,3"},
                {"variable_2": "top(5)"}
              ]
          style: deepObject
          explode: true
        - in: query
          name: codelist
          schema:
            type: object
            additionalProperties:
              type: string
            example: |
              [
                {"variable_1": "NUTS_2008"}
              ]
          style: deepObject
          explode: true
        - $ref: "#/components/parameters/outputFormat"
        - $ref: "#/components/parameters/outputFormatParams"
        - in: query
          name: heading
          style: form
          explode: false
          required: false
          description: Comma separated list of variable codes that should be placed in the heading in the resulting data
          schema:
            type: array
            items:
              type: string
        - in: query
          name: stub
          style: form
          explode: false
          required: false
          description: Comma separated list of variable codes that should be placed in the stub in the resulting data
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: string
            text/plain:
              schema:
                type: string
            application/xml:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "403":
          $ref: "#/components/responses/ErrorResponse403"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

    post:
      tags:
        - Tables
      summary: Get data for table by {id}.
      operationId: GetTableDataByPost
      parameters:
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/outputFormat"
        - $ref: "#/components/parameters/outputFormatParams"
      requestBody:
        description: A selection in JSON format for filtering the data. If no selection is specified the default selection will be applied.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VariablesSelection"

      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: string
            text/plain:
              schema:
                type: string
            application/xml:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "403":
          $ref: "#/components/responses/ErrorResponse403"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

  /codelists/{id}:
    get:
      tags:
        - Codelists
      summary: Get codelist by {id}.
      operationId: GetCodelistById
      parameters:
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CodelistResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

  /config:
    get:
      tags:
        - Configuration
      summary: Get API configuration.
      operationId: GetApiConfiguration
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

  /savedqueries:
    post:
      tags:
        - Saved Queries
      summary: Save a query for later use.
      operationId: CreateSaveQuery
      requestBody:
        description: A saved query in JSON format without an Id.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SavedQuery"
      responses:
        "201":
          description: Saved query created and returned with the id specified.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SavedQueryResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

  /savedqueries/{id}:
    get:
      tags:
        - Saved Queries
      parameters:
        - $ref: "#/components/parameters/id"
      summary: Retrieves the content of a saved query.
      description: |
        **Used for retrieving a saved query**
        * Get the saved query by id.
        * The saved query contains the selection and other parameters that were used when the query was created.
      operationId: GetSaveQuery
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SavedQueryResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

  /savedqueries/{id}/data:
    get:
      tags:
        - Saved Queries
      parameters:
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/outputFormat"
        - $ref: "#/components/parameters/outputFormatParams"
      summary: Retrieves the data by running the saved query.
      description: |
        **Used for retrieving data by running a saved query**
        * Get the data by running the saved query.
        * The saved query contains the selection and other parameters that were used when the query was created.
      operationId: RunSaveQuery
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: string
            text/plain:
              schema:
                type: string
            application/xml:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "403":
          $ref: "#/components/responses/ErrorResponse403"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"

  /savedqueries/{id}/selection:
    get:
      tags:
        - Saved Queries
      parameters:
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/id"
      summary: Retrieves the selection that the saved query will result in. Selection expressions will be transformed into actual value codes.
      operationId: GetSavedQuerySelection
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SelectionResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse400"
        "403":
          $ref: "#/components/responses/ErrorResponse403"
        "404":
          $ref: "#/components/responses/ErrorResponse404"
        "429":
          $ref: "#/components/responses/ErrorResponse429"
components:
  parameters:
    lang:
      name: lang
      in: query
      description: The language if the default is not what you want.
      required: false
      schema:
        type: string
        nullable: true
      examples:
        X1:
          value: en
          summary: For english
        X2:
          value: dk
          summary: For danish
    id:
      name: id
      in: path
      description: Id
      required: true
      schema:
        type: string
    codelistId:
      name: codelistId
      in: path
      description: Identifier for a codelist
      required: true
      schema:
        type: string
    query:
      name: query
      in: query
      description: Selects only tables that that matches a criteria which is specified by the search parameter.
      required: false
      schema:
        type: string
      examples:
        X1:
          value: population
          summary: Search for tables containing `population` in its metadata.
    pastDays:
      name: pastDays
      in: query
      description: Selects only tables that was updated from the time of execution going back number of days stated by the parameter pastDays. Valid values for past days are positive integers.
      required: false
      schema:
        type: integer
        minimum: 1
      examples:
        X1:
          value: 5
          summary: Search for tables which has been updated in the last 5 days
    includeDiscontinued:
      name: includeDiscontinued
      in: query
      description: Decides if discontinued tables are included in response.
      required: false
      schema:
        type: boolean
        default: false
        example: false
    pageNumber:
      name: pageNumber
      in: query
      description: "Pagination: Decides which page number to return"
      required: false
      schema:
        type: integer
        default: 1
    pageSize:
      name: pageSize
      in: query
      description: "Pagination: Decides how many tables per page"
      required: false
      schema:
        type: integer
    outputFormat:
      name: outputFormat
      in: query
      schema:
        $ref: "#/components/schemas/OutputFormatType"
    outputFormatParams:
      name: outputFormatParams
      in: query
      required: false
      schema:
        type: array
        items:
          $ref: "#/components/schemas/OutputFormatParamType"
  schemas:
    OutputFormatType:
      type: string
      enum:
        - px
        - json-stat2
        - csv
        - xlsx
        - html
        - json-px
        - parquet

    OutputFormatParamType:
      type: string
      enum:
        - UseCodes
        - UseTexts
        - UseCodesAndTexts
        - IncludeTitle
        - SeparatorTab
        - SeparatorSpace
        - SeparatorSemicolon
        - ExcludeZerosAndMissingValues
      description: |
        Parameters for the output format.
        * UseCodes: Can not be combined with UseTexts and UseCodesAndTexts. And only applicable for csv, html and xlsx output format.
        * UseTexts: Can not be combined with UsedCodes and UseCodesAndTexts. And only applicable for csv, html and xlsx output format.
        * UseCodesAndTexts: Can not be combined with UseCodess and UseTexts. And only applicable for csv, html and xlsx output format.
        * IncludeTitle: Only applicable for csv, html and xlsx output format.
        * SeparatorTab: Can not be combined with SeparatorSpace and SeparatorSemicolon. And only applicable for csv output format.
        * SeparatorSpace: Can not be combined with SeparatorTab and SeparatorSemicolon. And only applicable for csv output format.
        * SeparatorSemicolon: Can not be combined with SeparatorTab and SeparatorSpace. And only applicable for csv output format.
        * ExcludeZerosAndMissingValues: Can be used by all formats but only have effect on csv, html and xlsx output format.
    SavedQueryResponse:
      type: object
      required:
        - "language"
        - "id"
        - "savedQuery"
        - "links"
      properties:
        language:
          type: string
          description: The language code for the language requested
        id:
          type: string
          description: The id of the saved query
        savedQuery:
          $ref: "#/components/schemas/SavedQuery"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"


    SavedQuery:
      type: object
      required:
        - "selection"
        - "language"
        - "tableId"
      properties:
        id:
          type: string
          description: The id of the saved query
        selection:
          $ref: "#/components/schemas/VariablesSelection"
        language:
          type: string
          description: language code for the language used in this response
        tableId:
          type: string
          description: which table the query is for
        outputFormat:
          $ref: "#/components/schemas/OutputFormatType"
        outputFormatParams:
          type: array
          items:
            $ref: "#/components/schemas/OutputFormatParamType"

    VariablesSelection:
      type: object
      required:
        - "selection"
      properties:
        selection:
          type: array
          items:
            $ref: "#/components/schemas/VariableSelection"
        placement:
          $ref: "#/components/schemas/VariablePlacementType"

    VariablePlacementType:
      type: object
      properties:
        heading:
          description: List of variables that should be placed in the heading in the resulting data
          type: array
          items:
            type: string
        stub:
          description: List of variables that should be placed in the stub in the resulting data
          type: array
          items:
            type: string
    SelectionResponse:
      allOf:
        - $ref: "#/components/schemas/VariablesSelection"
      type: object
      required:
        - "language"
        - "links"
      properties:
        language:
          type: string
          description: The language code for the language used in this response
          example: sv
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"

    VariableSelection:
      type: object
      required:
        - "variableCode"
        - "values"
      properties:
        variableCode:
          type: string
          description: The variable code.
        codelist:
          type: string
          description: The identifier of the codelist that should be applied
          nullable: true
        valueCodes:
          type: array
          description: An array of string that specifies wich values sould be selected. Either as value codes or value expressions
          items:
            type: string
    ConfigResponse:
      type: object
      description: API configuration
      required:
        - "apiVersion"
        - "appVersion"
        - "languages"
        - "defaultLanguage"
        - "maxDataCells"
        - "maxCallsPerTimeWindow"
        - "timeWindow"
        - "license"
        - "defaultDataFormat"
        - "dataFormats"
      properties:
        apiVersion:
          type: string
          description: The version of the API spesification
        appVersion:
          type: string
          description: The version of the API implementation
        languages:
          type: array
          description: A list of language that exists for the data.
          items:
            $ref: "#/components/schemas/Language"
        defaultLanguage:
          type: string
          description: The id of the language that is the default language.
        maxDataCells:
          type: integer
          description: A threshold of how many datacells that can be fetched in a single API call
          minimum: 0
        maxCallsPerTimeWindow:
          type: integer
          description: The maximum number of call to the API for a time window indicated by timeWindow.
          minimum: 1
        timeWindow:
          type: integer
          description: The time window restricting how many call that can be done. Note that this time window is for fetching data from the API and that different endpoints might have different limits.
          minimum: 1
        license:
          type: string
          description: The license that the data is provided.
        sourceReferences:
          type: array
          description: A list of how the data should be cite for diffrent languages.
          items:
            $ref: "#/components/schemas/SourceReference"
        defaultDataFormat:
          type: string
          description: The default data format to used when no format is specified in the request.
        dataFormats:
          type: array
          description: List of available data formts for fetching data in.
          items:
            type: string
        features:
          type: array
          description: A list of features for the API
          items:
            $ref: "#/components/schemas/ApiFeature"

    Language:
      type: object
      description: Language information
      required:
        - "id"
        - "label"
      properties:
        id:
          type: string
          description: The language ISO code
        label:
          type: string
          description: The name of the language

    SourceReference:
      type: object
      description: How data should be cite for a specific language
      required:
        - "language"
        - "text"
      properties:
        language:
          type: string
          description: The language id
        text:
          type: string
          description: The text that should be displayed

    ApiFeature:
      type: object
      required:
        - "id"
      properties:
        id:
          type: string
          description: The identifyer for the feature
        params:
          type: array
          items:
            $ref: "#/components/schemas/KeyValuePair"

    KeyValuePair:
      type: object
      required:
        - "key"
        - "value"
      properties:
        key:
          type: string
          description: The key
        value:
          type: string
          description: The value associated with the key

    TableResponse:
      allOf:
        - $ref: "#/components/schemas/Table"
      required:
        - "language"
      properties:
        language:
          type: string
          description: The language code (ISO 639) for this response

    PathElement:
      type: object
      required:
        - "id"
        - "label"
      properties:
        id:
          type: string
          description: The identity of the PathElement
        label:
          type: string
          description: A textual name for the PathElement
        sortCode:
          type: string
          description: A string for sorting the PathElement among its siblings

    Table:
      type: object
      description: Table item
      required:
        - "id"
        - "label"
        - "updated"
        - "firstPeriod"
        - "lastPeriod"
        - "variableNames"
        - "links"
      properties:
        id:
          type: string
          nullable: false
        label:
          type: string
          nullable: true
          description: Display text
        description:
          type: string
          nullable: true
          description: Longer text describing node.
        sortCode:
          type: string
          description: String for sorting the contents in folder
        tags:
          type: array
          items:
            type: string
            description: tag for table
        updated:
          type: string
          description: Date and time when the figures in the table was last updated, in UTC time.
          pattern: "^((19|20)\\d\\d)\\-(0?[1-9]|1[012])\\-(0?[1-9]|[12][0-9]|3[01])$"
          format: date-time
          nullable: true
        firstPeriod:
          type: string
          description: First period
          example: 2017
          nullable: true
        lastPeriod:
          type: string
          description: Last period
          example: 2022
          nullable: true
        category:
          $ref: "#/components/schemas/TableCategory"
        variableNames:
          type: array
          description: List of varibles name
          items:
            type: string
        discontinued:
          $ref: "#/components/schemas/Discontinued"
        source:
          type: string
          description: The source of the table
        subjectCode:
          type: string
          description: The subject code of the table
        timeUnit:
          $ref: "#/components/schemas/TimeUnit"
          description: The time unit for the table

        paths:
          type: array
          items:
            type: array
            items:
              $ref: "#/components/schemas/PathElement"
          description: The path to the table
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
          description: Links to ...
          nullable: true

    Discontinued:
      description: If the table is discontinued or not. That is if it no longer updated with new figures.
      type: boolean
      nullable: true

    PageInfo:
      type: object
      required:
        - "pageNumber"
        - "pageSize"
        - "totalElements"
        - "totalPages"
      properties:
        pageNumber:
          type: integer
          description: The current page number.
          format: int32
          minimum: 1
        pageSize:
          type: integer
          format: int32
          description: The maximal number of elements in a page
          example: 100
          minimum: 1
        totalElements:
          type: integer
          format: int32
          description: the Total number of elements
          minimum: 0
        totalPages:
          type: integer
          format: int32
          description: The total number of pages
          minimum: 1
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"

    TablesResponse:
      type: object
      required:
        - "language"
        - "tables"
        - "page"
      properties:
        language:
          type: string
          description: The language code (ISO 639) for this response
        tables:
          type: array
          items:
            $ref: "#/components/schemas/Table"
        page:
          $ref: "#/components/schemas/PageInfo"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"


    Note:
      type: object
      required:
        - "text"
      properties:
        mandatory:
          type: boolean
          default: false
          description: Must be shown to end user if true
        text:
          type: string
    CodelistInformation:
      type: object
      required:
        - "id"
        - "label"
        - "type"
        - "links"
      properties:
        id:
          type: string
          description: The identity of the codelist
        label:
          type: string
          description: A textual name for the codelist
        type:
          $ref: "#/components/schemas/CodelistType"
        links:
          type: array
          description: Links to associated information about the code list
          items:
            $ref: "#/components/schemas/Link"
    Contact:
      type: object
      required:
        - "raw"
      properties:
        name:
          type: string
          example: Inga Svensson
        organization:
          type: string
          example: Statistics Sweden
        phone:
          type: string
          example: "+46101111111"
        mail:
          type: string
          example: testmail@testmail.com
        raw:
          type: string
          description: Raw contact information for compatability with PX files
    CodelistsResponse:
      type: object
      required:
        - "language"
      properties:
        language:
          type: string
          description: The language code for the language used in this response
          example: sv
        codelists:
          type: array
          items:
            $ref: "#/components/schemas/CodelistMetadata"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
    CodelistMetadata:
      type: object
      required:
        - "id"
        - "label"
        - "type"
        - "links"
      properties:
        id:
          type: string
          description: The identiyer for the codelist
          example: agg_RegionNUTS2_2008
        label:
          type: string
          description: The textual name  for the codelist.
          example: NUTS2 fr.o.m 2008
        type:
          $ref: "#/components/schemas/CodelistType"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"

    CodelistType:
      type: string
      description: Type of codelist
      enum:
        - Aggregation
        - Valueset

    CodelistResponse:
      type: object
      required:
        - "id"
        - "label"
        - "language"
        - "languages"
        - "type"
        - "values"
        - "links"
      properties:
        id:
          type: string
          description: The identiyer for the codelist
          example: agg_RegionNUTS2_2008
        label:
          type: string
          description: The textual name  for the codelist.
          example: NUTS2 fr.o.m 2008
        language:
          type: string
          description: The language code for the language used in this response
          example: sv
        languages:
          type: array
          items:
            type: string
          description: The languages that the codelist is available in
        elimination:
          type: boolean
          default: false
          description: If the codelist is eliminatable
        eliminationValueCode:
          type: string
          description: The value code that should be used for elimination. If not set the variable will be eliminated by summing up all values.
        type:
          $ref: "#/components/schemas/CodelistType"
        values:
          type: array
          items:
            $ref: "#/components/schemas/ValueMap"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"

    ValueMap:
      type: object
      required:
        - "code"
        - "label"
        - "valueMap"
      properties:
        code:
          type: string
          description: The code for the value.
          example: "SE22"
        label:
          type: string
          description: The textual representation for the value
          example: Sydsverige
        valueMap:
          type: array
          description: An array of codes from the origial codelist for the variable that cand be mapped to this value
          example: '["10", "12"]'
          items:
            type: string
        notes:
          type: array
          description: Optional notes that are associated with the value
          items:
            $ref: "#/components/schemas/Note"

    Link:
      type: object
      required:
        - "rel"
        - "hreflang"
        - "href"
      properties:
        rel:
          type: string
          nullable: false
          description: the link relation, see https://www.iana.org/assignments/link-relations/link-relations.xhtml
        hreflang:
          type: string
          description: The language that is used for the link, see https://moz.com/learn/seo/hreflang-tag
        href:
          type: string
          nullable: false
          description: the link to the resource

    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          default: about:blank
          example: https://zalando.github.io/problem/constraint-violation
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: Connection to database timed out
        instance:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.

    strarray:
      type: array
      items:
        type: string
      uniqueItems: true
    updated:
      description: See https://json-stat.org/full/#updated
      type: string
      pattern: "^((19|20)\\d\\d)\\-(0?[1-9]|1[012])\\-(0?[1-9]|[12][0-9]|3[01])$"
    href:
      description: Specification on json-stat.org -> [here](https://json-stat.org/full/#href)
      type: string
      format: uri
    label:
      description: Specification on json-stat.org -> [here](https://json-stat.org/full/#label)
      type: string
    source:
      description: Specification on json-stat.org -> [here](https://json-stat.org/full/#source)
      type: string
    extension-root:
      description: extension at root level
      type: object
      properties:
        noteMandatory:
          $ref: "#/components/schemas/jsonstat-noteMandatory"
        px:
          description: |
            Properties corresponds to keywords in the px-file.

            See [PX file format](https://www.scb.se/en/services/statistical-programs-for-px-files/px-file-format/)
          type: object
          properties:
            infofile:
              description: Name of a file containing more information for the statistics**
              type: string
            tableid:
              description: A text that is the identity of the table
              type: string
            decimals:
              description: The number of decimals in the table cells
              type: integer
            official-statistics:
              description: Indicates if the data table is included in the official statistics of the organization
              type: boolean
            aggregallowed:
              description: If the contents of the table cannot be aggregated
              type: boolean
            copyright:
              description: If the table is protected by copyright
              type: boolean
            language:
              description: code (two characters) for language
              type: string
            contents:
              description: Information about the contents, which makes up the first part of a title created when retrieving tables from PC-Axis.
              type: string
            description:
              description: See _description_ in [PX file format](https://www.scb.se/en/services/statistical-programs-for-px-files/px-file-format/)
              type: string
            descriptiondefault:
              description: For some languages it is difficult to build a table title dynamically. The keyword descriptiondefault = True; means that the text after keyword Description will be used as title for the table
              type: boolean
            heading:
              description: List of suggested variables for table head
              type: array
              items:
                type: string
            stub:
              description: List of suggested variables for table stub
              type: array
              items:
                type: string
            matrix:
              description: The name of the matrix
              type: string
            subject-code:
              description: Subject area code
              type: string
            subject-area:
              description: Subject area
              type: string
            nextUpdate:
              description: Date for next update
              $ref: "#/components/schemas/updated"
            survey:
              description: Survey for table
              type: string
            link:
              description: Links for tables
              type: string
            updateFrequency:
              description: How often a table is updated
              type: string
        firstPeriod:
          description: Earliest time period in table
          type: string
        lastPeriod:
          description: Latest time period in table
          type: string
        tags:
          description: Tag for table
          type: array
          items:
            type: string
        discontinued:
          $ref: "#/components/schemas/Discontinued"
        contact:
          type: array
          description: A list of contacts associated with the table.
          items:
            $ref: "#/components/schemas/Contact"
    extension:
      description: extension at some level
      type: object
    extension-dimension:
      description: extension at dimension
      type: object
      properties:
        elimination:
          description: Can dimension be elminated
          type: boolean
        eliminationValueCode:
          description: Elimination value code
          type: string
        noteMandatory:
          $ref: "#/components/schemas/jsonstat-noteMandatory"
        categoryNoteMandatory:
          description: Describes which value note are mandatory
          type: object
          additionalProperties:
            $ref: "#/components/schemas/jsonstat-noteMandatory"
        refperiod:
          description: Text with information on the exact period for the statistics
          type: object
          additionalProperties:
            type: string
        show:
          description: Information about how variables are presented
          type: string
        codelists:
          $ref: "#/components/schemas/Codelists"
        measuringType:
          description: Indicates if data is stock, flow or average.
          type: object
          additionalProperties:
            $ref: "#/components/schemas/MeasuringType"
        priceType:
          description: Indicates if data is in current or fixed prices.
          type: object
          additionalProperties:
            $ref: "#/components/schemas/PriceType"
        adjustment:
          description: Describes adjustments made to the data
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Adjustment"
        basePeriod:
          description: Base period for, for instance index series. Is shown with the footnote. If there is a contents variable the keyword is repeated for each value of the contents variable.
          type: object
          additionalProperties:
            $ref: "#/components/schemas/BasePeriod"
        alternativeText:
          description: An alternative text for the dimension value
          type: object
          additionalProperties:
            type: string
    strarray-by-str-dict:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
        uniqueItems: true
    jsonstat-link:
      type: object
      additionalProperties:
        type: array
        items:
          type: object
          title: jsonstatLink
          properties:
            type:
              type: string
            href:
              "$ref": "#/components/schemas/href"
          additionalProperties: false
    jsonstat-extension-link:
      type: object
      properties:
        describedby:
          type: array
          items:
            type: object
            title: DimensionExtension
            properties:
              extension:
                description: A extension object
                type: object
                additionalProperties:
                  description: A string
                  type: string

            additionalProperties: false
      additionalProperties: false
    jsonstat-note:
      description: Spesification on json-stat.org -> [here](https://json-stat.org/full/#note)
      type: array
      items:
        type: string
    jsonstat-noteMandatory:
      description: Describes if a note of a certain index is mandatory.
      type: object
      additionalProperties:
        type: boolean
        default: true
    jsonstat-category:
      type: object
      properties:
        index:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#index)
          type: object
          additionalProperties:
            type: integer
        label:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#label)
          type: object
          minProperties: 1
          additionalProperties:
            type: string
        note:
          description: Notes for values
          type: object
          additionalProperties:
            "$ref": "#/components/schemas/jsonstat-note"
        child:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#child)
          "$ref": "#/components/schemas/strarray-by-str-dict"
        unit:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#unit)
          type: object
          additionalProperties:
            type: object
            properties:
              base:
                description: It is the base unit (person, gram, euro, etc.).
                type: string
              decimals:
                description: Number of decimals
                type: integer
      additionalProperties: false

    Role:
      description: Specification on json-stat.org -> [here](https://json-stat.org/full/#role)
      type: object
      properties:
        time:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#time)
          $ref: "#/components/schemas/strarray"
        geo:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#geo)
          $ref: "#/components/schemas/strarray"
        metric:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#metric)
          $ref: "#/components/schemas/strarray"
      additionalProperties: false

    Dimension:
      description: Specification on json-stat.org -> [here](https://json-stat.org/full/#dimension)
      type: object
      additionalProperties:
        type: object
        properties:
          label:
            description: Specification on json-stat.org -> [here](https://json-stat.org/full/#label)
            $ref: "#/components/schemas/label"
          note:
            description: Notes for variable
            $ref: "#/components/schemas/jsonstat-note"
          category:
            description: Specification on json-stat.org -> [here](https://json-stat.org/full/#category)
            $ref: "#/components/schemas/jsonstat-category"
          extension:
            $ref: "#/components/schemas/extension-dimension"
          link:
            $ref: "#/components/schemas/jsonstat-extension-link"
        additionalProperties: false

    Codelists:
      description: Available codelists for this dimension
      type: array
      items:
        $ref: "#/components/schemas/CodelistInformation"

    Adjustment:
      description: WorkOnly means that data is adjusted e.g. to take into account the number of working days. SesOnly means that data is seasonally adjusted.
      type: string
      default: None
      enum:
        - None
        - SesOnly
        - WorkOnly
        - WorkAndSes

    PriceType:
      description: Indicates if data is in current or fixed prices.
      type: string
      enum:
        - NotApplicable
        - Current
        - Fixed

    MeasuringType:
      description: Indicates if data is stock, flow or average.
      type: string
      default: Other
      enum:
        - Stock
        - Flow
        - Average
        - Other

    TimeUnit:
      description: Indicates the time scale for the variable.
      type: string
      enum:
      - Annual
      - Quarterly
      - Monthly
      - Weekly
      - Other

    BasePeriod:
      description: Base period for, for instance index series. Is shown with the footnote. If there is a contents variable the keyword is repeated for each value of the contents variable.
      type: string

    TableCategory:
      type: string
      description: Mostly for internal use. Which category table belongs to. internal, public, private or section.
      default: public
      enum:
        - internal
        - public
        - private
        - section

    Dataset:
      title: JSON-stat 2.0 Dataset Schema
      description: |
        Representation of TableMetaData/TableData according to JSON-stat 2.0 Dataset Schema (2018-09-05 10:55), see full specification of JSON-stat format [here](https://json-stat.org/full/)

        Properties in **extension** are mostly from PX-file format, see [PX file format](https://www.scb.se/en/services/statistical-programs-for-px-files/px-file-format/)
      type: object
      properties:
        version:
          description: JSON-stat version 2.0
          type: string
          enum:
            - "2.0"
          default: "2.0"
        class:
          "$ref": "#/components/schemas/ClassType"
          # description: "Is always dataset"
          # type: string
          # enum:
          #   - dataset
          # default: dataset
        href:
          "$ref": "#/components/schemas/href"
        label:
          "$ref": "#/components/schemas/label"
        source:
          "$ref": "#/components/schemas/source"
        updated:
          "$ref": "#/components/schemas/updated"
        link:
          "$ref": "#/components/schemas/jsonstat-link"
        note:
          description: Note for table
          $ref: "#/components/schemas/jsonstat-note"
        role:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#role)
          "$ref": "#/components/schemas/Role"
        id:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#id)
          "$ref": "#/components/schemas/strarray"
        size:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#size)
          type: array
          items:
            type: integer
        dimension:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#dimension)
          "$ref": "#/components/schemas/Dimension"
        extension:
          "$ref": "#/components/schemas/extension-root"
        value:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#value)
          type: array
          nullable: true
          items:
            type: number
            format: double
            nullable: true
        status:
          description: Specification on json-stat.org -> [here](https://json-stat.org/full/#status)
          type: object
          additionalProperties:
            type: string
      additionalProperties: false
      required:
        - version
        - class
        - value
        - id
        - size
        - dimension

    ClassType:
      description: "Is always dataset"
      type: string
      enum:
        - dataset
      default: dataset

  responses:
    ErrorResponse429:
      description: Error response for 429
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
            #Reference:
            # https://dzone.com/articles/rest-api-error-handling-problem-details-response
            # https://datatracker.ietf.org/doc/html/rfc7807
            # https://nordicapis.com/best-practices-api-error-handling/
          example:
            title: Too many requests
            status: 429
            detail: You have reach the threshold for request limiting. 30 request per minute.

    ErrorResponse400:
      description: Error response for 400
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            title: Bad Request
            status: 400
            detail: Value, xxx is not a valid value code for variable yyy

    ErrorResponse403:
      description: Error response for 403
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            title: Forbiden
            status: 403
            detail: The query resulted in cell that exceeds the number of allowed.

    ErrorResponse404:
      description: Error response for 404
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            title: Not Found
            status: 404
            detail: Node with id, xxx can not be found