Taxonomy versions

Every time modifications are made to the taxonomy, those modifications are released in the form of a version. The released versions form a linear history of the taxonomy with every version being identified by an integer. The first version is 1 and every new version is assigned a version number that is an increment by one from the previous version number. The last released version as of this writing is version 22.

The various API endpoints optionally provide a version parameter in order to explicitly specify which version of the taxonomy to use. If the version parameter is not specified, it will by default be assumed that the last published version is requested. A good reason for explicitly providing a version parameter is to make sure that a system that uses the taxonomy works exactly the same irrespective of updates made to the taxonomy.

Concepts in the taxonomy are never deleted from one version to the next. Instead they become deprecated. By default, the API will not return deprecated concepts from a given version–but it does exist in the database. If a deprecated concept has been replaced by some other concept, there will be a relation of type replaced-by from the deprecated concept to the new concept.

Versions in the GraphQL API

Visit the interactive page https://taxonomy.api.jobtechdev.se/v1/taxonomy/graphiql to explore the GraphQL API. To list available versions, use the following query:

query MyQuery {
  versions {
    id
    timestamp
  }
}

which will return a json-encoded response with data about versions:

{
  "data": {
    "versions": [
      {
        "id": 1,
        "timestamp": "2021-03-05T13:38:02.440Z"
      },
      
      ...

      {
        "id": 22,
        "timestamp": "2024-02-21T16:16:00.195Z"
      }
    ]
  }
}

In order to query a concept from a specific version, specify the version parameter in the query. For example, the following query will get the concept with id AWt8_idw_DYJ from version 10:

query MyQuery {
  concepts(version: 10, id: "AWt8_idw_DYJ") {
    id
    preferred_label
  }
}

and return the following result:

{
  "data": {
    "concepts": [
      {
        "id": "AWt8_idw_DYJ",
        "preferred_label": "Odlare av trädgårds- och jordbruksväxter, frukt och bär"
      }
    ]
  }
}

But if we request the same concept in version 14, that is

query MyQuery {
  concepts(version: 14, id: "AWt8_idw_DYJ") {
    id
    preferred_label
  }
}

we get an empty result. However, this does not mean that the concept does not exist in version 14: It only means that it has been deprecated. In order to get the concept in version 14, set the include_deprecated parameter to true:

query MyQuery {
  concepts(version: 14, id: "AWt8_idw_DYJ", include_deprecated: true) {
    id
    preferred_label
    replaced_by {
      id
    }
  }
}

Note that we also include the field replaced_by. We obtain the following result:

{
  "data": {
    "concepts": [
      {
        "id": "AWt8_idw_DYJ",
        "preferred_label": "Odlare av trädgårds- och jordbruksväxter, frukt och bär",
        "replaced_by": [
          {
            "id": "Wv97_wRL_3LS"
          }
        ]
      }
    ]
  }
}

From this result, we read that in version 14, the concept with id Wv97_wRL_3LS is meant to be used instead of the concept with id AWt8_idw_DYJ.

Versions in the REST API

In order to get a list of all published versions, send a GET request to the following address: https://taxonomy.api.jobtechdev.se/v1/taxonomy/main/versions

It will return a list of versions and timestamps in json-format:

[{"taxonomy/version":1,"taxonomy/timestamp":"2021-03-05T13:38:02.440Z"},

 ...
 
 {"taxonomy/version":22,"taxonomy/timestamp":"2024-02-21T16:16:00.195Z"}]

Many of the REST endpoints accept a version parameter. Here is an example where we request concept with id AWt8_idw_DYJ and version 10:

https://taxonomy.api.jobtechdev.se/v1/taxonomy/main/concepts?id=AWt8_idw_DYJ&version=10

The response will have the following json-coded body:

[
  {
    "taxonomy/type": "forecast-occupation",
    "taxonomy/definition": "Ett prognosyrke beskriver en eller fler ihopslagna yrkesgruppers konkurrensläge på arbetsmarknaden. Ett prognosyrke riktas aldrig mot en lägre nivå i SSYK-strukturen än SSYK 4 men kan däremot bestå av en eller fler SSYK grupper på 4 eller 3 siffernivå. \n\nDetta prognosyrke består av följande SSYK 4-grupper: \n·\t6112 - Trädgårdsodlare\n·\t6111 - Odlare av jordbruksväxter, frukt och bär",
    "taxonomy/id": "AWt8_idw_DYJ",
    "taxonomy/preferred-label": "Odlare av trädgårds- och jordbruksväxter, frukt och bär"
  }
]

However, if we request a later version, say 14, with address https://taxonomy.api.jobtechdev.se/v1/taxonomy/main/concepts?id=AWt8_idw_DYJ&version=14, we will get an empty result: []. The reason for that is that in version 14, the concept with id AWt8_idw_DYJ has been deprecated and, by default, will not be returned by the API. To get the data of this concept, specify the included-deprecated parameter to be true: https://taxonomy.api.jobtechdev.se/v1/taxonomy/main/concepts?id=AWt8_idw_DYJ&include-deprecated=true&version=14. This will return the concept with id AWt8_idw_DYJ in version 14:

[
  {
    "taxonomy/type": "forecast-occupation",
    "taxonomy/definition": "Ett prognosyrke beskriver en eller fler ihopslagna yrkesgruppers konkurrensläge på arbetsmarknaden. Ett prognosyrke riktas aldrig mot en lägre nivå i SSYK-strukturen än SSYK 4 men kan däremot bestå av en eller fler SSYK grupper på 4 eller 3 siffernivå. \n\nDetta prognosyrke består av följande SSYK 4-grupper: \n·\t6112 - Trädgårdsodlare\n·\t6111 - Odlare av jordbruksväxter, frukt och bär",
    "taxonomy/id": "AWt8_idw_DYJ",
    "taxonomy/replaced-by": [
      {
        "taxonomy/id": "Wv97_wRL_3LS",
        "taxonomy/definition": "Ett prognosyrke beskriver en eller fler ihopslagna yrkesgruppers konkurrensläge på arbetsmarknaden. Ett prognosyrke riktas aldrig mot en lägre nivå i SSYK-strukturen än SSYK 4 men kan däremot bestå av en eller fler SSYK grupper på 4 eller 3 siffernivå.\n\nDetta prognosyrke består av följande SSYK 4-grupper:\n\n·\t6130 - Växtodlare och djuruppfödare, blandad drift\n·\t6112 - Trädgårdsodlare\n·\t6111 - Odlare av jordbruksväxter, frukt och bär",
        "taxonomy/type": "forecast-occupation",
        "taxonomy/preferred-label": "Odlare av trädgårds- och jordbruksväxter samt djuruppfödare blandad drift"
      }
    ],
    "taxonomy/preferred-label": "Odlare av trädgårds- och jordbruksväxter, frukt och bär",
    "taxonomy/deprecated": true
  }
]

Note the presence of the key "taxonomy/replaced-by". It means that in version 14, the concept has been replaced by another concept with id Wv97_wRL_3LS.

Summary

In both the GraphQL API and the REST API, a version parameter can be provided in order to get data from a specific version. Concepts are never deleted from the taxonomy, they are only deprecated. To include deprecated concepts, use the include_deprecated parameter in the GraphQL API and the included-deprecated query parameter in the REST API. In the GraphQL API, include the replaced_by field in a concept query to see which concept replaces a deprecated concept. In the REST API, deprecated concepts will contain the taxonomy/replaced-by key listing any concept that replaces the returned concept.