PRE-RELEASE Taxonomy Graph APIs documentation preview

This resource is intended as a preview of the taxonomy APIs, which are not yet released or final.  Production documentation for all Graph APIs can be found at https://developer.microsoft.com/en-us/graph/ .   When the taxonomy APIs are released, all documentation will be released there.

Taxonomy API design

Scenarios and personas

These APIs are designed for basic create/read/update/delete (CRUD) operations of the taxonomy service within Project Cortex. The scenarios include providing basic functionality so that some functionality of the UI for the term store can be built around the APIs. In addition, the APIs can be used by third party developers so that they could do CRUD on the term store. Scenarios like creating a term, modifying its properties and deleting a term are to be supported.

CRUD operations for Taxonomy

The APIs cover basic CRUD operation for taxonomy term store in SharePoint.

Details and schema changes

There are 5 main entities that we define.

1. store
2. termGroups
3. sets
4. terms
5. relations

The above entities allows the user to perform operations that relevant to the taxonomy service. Details of these entities are below.

New entity types

{microsoft.graph.termStore.store}
This is the top-level entity containing the resources to manage a taxonomy (meta-data tagging) for a tenant.

{
"id": "string",
"defaultLanguageTag" : "string",
"languageTags" : ["string"],

/* relationships */
“groups” : [{“@odata.type” : “microsoft.graph.termStore.group”}] ,
“sets” : [{“@oData.type” : “microsoft.graph.termStore.set”}]
}

Properties

Relationships

Supported functionality

{microsoft.graph.termStore.group}

Here is a JSON representation of a termGroup resource.

{
"id": "string",
"createdDateTime": "string (timestamp)",
"description": "string",
"scope" : "microsoft.graph.termStore.groupScope",
"displayName": "string",

/* relationships */
“sets” : [{“@odata.type” : “microsoft.graph.termStore.set”}]
}

This is a container for various sets. Some termGroups are restricted for a particular site-collection whereas others are visible globally.

Properties

Relationships

Supported functionality

Errors

{microsoft.graph.termStore.set}

This is the container for a collection of terms. Typically the set may contain terms in a hierarchy that could define a specific taxonomy.

Here is a JSON representation of a set resource.

{
"id": "string",
"createdDateTime": "string (timestamp)",
"description": "string",
"localizedNames": [{"@odata.type": "microsoft.graph.termStore.localizedName"}],
"properties": [{"@odata.type": "microsoft.graph.keyValue"}],

/* relationships */
“children” : [{“@odata.type” : “microsoft.graph.termStore.term”}],
“parentGroup” : {“odata.type” : “microsoft.graph.termStore.group”},
“relations” : [{“@odata.type” : “microsoft.graph.termStore.relation”}] ,
“terms” : [{“@odata.type” : “microsoft.graph.termStore.term”}]
}

Properties

Relationships

Supported functionality

Errors

{microsoft.graph.termStore.term}

This is the taxonomy term entity. This is the entity that can be used add metadata on files/items etc. A term can have multiple labels for each language tag in the termStore. Here is a JSON representation of a term resource.

{
"createdDateTime": "string (timestamp)",
"descriptions": [{"@odata.type" : "microsoft.graph.termStore.localizedDescription"}],
"id": "string",
"labels" : [{"@odata.type": "microsoft.graph.termStore.localizedLabel"}],
"lastModifiedDateTime": "string (timestamp)",
"properties": [{"@odata.type": "microsoft.graph.keyValue"}],

/* relationships */
“children” : [{“@odata.type” : “microsoft.graph.termStore.term”}],
“set” : {“@odata.type” : “microsoft.graph.termStore.set”},
“relations” : [{“@odata.type” : “microsoft.graph.termStore.relation”}],
}

Properties

Relationships

Supported functionality

Errors

{microsoft.graph.termStore.relation}

This is the taxonomy term-relation entity. We model how terms are related to other terms or sets. Here is a JSON representation of a relation resource.

{
"id": "string",
"relationship" : "microsoft.graph.termStore.relationType" ,

/* relationships */
“fromTerm” : { “@odata.type” : “microsoft.graph.termStore.term”},
“toTerm” : { “@odata.type” : “microsoft.graph.termStore.term”},
“set” : { “@odata.type” : “microsoft.graph.termStore.set”}
}

Properties

Relationships

Supported functionality

Errors

New complex types

Below are list of complex types for taxonomy service.

{microsoft.graph.termStore.localizedLabel}

Identifies the labels associated with a given term. Inherits from microsoft.graph.termStore.localizedName

JSON representation

{
"isDefault" : "boolean",
"languageTag" : "string",
"name" : "string"
}

Properties

{microsoft.graph.termStore.localizedDescription}

The description of each term specific to a language tag.

JSON representation

{
"languageTag" : "string",
"description" : "string"
}

{microsoft.graph.termStore.localizedName}

Name of a termSet specific to a language tag.

JSON representation

{
"languageTag" : "string",
"name" : "string"
}

{microsoft.graph.keyValue}

Key value pair used to make a custom property in a termStore.

JSON representation

{
"key" : "string",
"value" : "string"
}

Properties

New enums

{microsoft.graph.termStore.groupScope}

The enum defines the various types of groups we can have within the termStore.

{microsoft.graph.termStore.relationType}

The enum defines the type of relationships we can have between terms

New permission scopes

Example REST operations

In general the operations here should allow for basic CRUD operations on the termStore.

Use case: Create term under another term

Post a new term under the children collection of a term.

POST https://graph.microsoft.com/v1.0/termStore/sets/{id}/terms/{id}/children
{
"labels" : [
{
"name" : "Cat",
"isDefault" : true,
"languageTag" : "en-US"
}
]
}

HTTP/1.1 200 OK
{
“id”: “96e3a5ab-b96e-4130-ac08-06630ca5dd0b”,
“labels” : [
{
“name” : “Cat”,
“isDefault” : true,
“languageTag” : “en-US”
}
]
}

Use Case: Create a child term of a set. This is a top-level term of a termSet

Create a term as a child of the termSet making a top-level term for the termSet.

POST https://graph.microsoft.com/v1.0/termStore/sets/{id}/children
{
"labels" : [
{
"name" : "Cat",
"isDefault" : true,
"languageTag" : "en-US"
}
]
}

HTTP/1.1 200 OK
{
“id”: “96e3a5ab-b96e-4130-ac08-06630ca5dd0b”,
“labels” : [
{
“name” : “Cat”,
“isDefault” : true,
“languageTag” : “en-US”
}
]
}

Use case: Get term

Get a term.

GET https://graph.microsoft.com/v1.0/termStore/groups/{id}/sets/{id}/terms/{id}
GET https://graph.microsoft.com/v1.0/termStore/sets/{id}/terms/{id}

HTTP/1.1 200 OK
{
“id”: “96e3a5ab-b96e-4130-ac08-06630ca5dd0b”,
“labels” : [
{
“name” : “Cat”,
“isDefault” : true,
“languageTag” : “en-US”
}
]
}

Use case: Delete term

Deletes a term and all relations associated with that term.

DELETE https://graph.microsoft.com/v1.0/termStore/sets/{id}/terms/{id}

HTTP/1.1 204 NO CONTENT

Use case: Patch term

Used for updating labels, or other term properties.

PATCH https://graph.microsoft.com/v1.0/termStore/sets/{id}/terms/{id}
{
"labels" : [
{
"name" : "Cat",
"isDefault" : true,
"languageTag" : "en-US"
}
]
}

HTTP/1.1 200 OK
{
“id”: “96e3a5ab-b96e-4130-ac08-06630ca5dd0b”,
“labels” : [
{
“name” : “Cat”,
“isDefault” : true,
“languageTag” : “en-US”
}
]
}

Use Case: Create a pinned relationship between terms. Reused relations can be made similarly by changing the relationType.

In this case the term gets pinned under the target term.

POST https://graph.microsoft.com/v1.0/termStore/sets/{id}/terms/{id}/relations
{
"relationship" : "pin",
"fromTerm" : {
"id" : "b49f64b3-4722-4336-9a5c-56c326b344d4"
},
"set" : {
"id" : "95e553ae-a91a-4670-a139-67a6cea285b3"
}
}

HTTP/1.1 200 OK
{
“id”: “ca51a6b8-9aaf-4c05-8b73-b4273b876296”,
“relationship” : “pin”,
“fromTerm” : {
“id” : “b49f64b3-4722-4336-9a5c-56c326b344d4”
},
“toTerm” : {
“id” : “226e8ee3-f4b6-49d7-92d5-ec9d5475eec5”
},
“set” : {
“id” : “95e553ae-a91a-4670-a139-67a6cea285b3”
}
}

Use Case: Create a pinned relationship between term and termSet.

In this case no fromTerm is specified as relation is between term and termSet.

POST https://graph.microsoft.com/v1.0/termStore/sets/{id}/terms/{id}/relations
{
"relationship" : "pin",
"set" : {
"id" : "95e553ae-a91a-4670-a139-67a6cea285b3"
}
}

HTTP/1.1 200 OK
{
“id”: “ca51a6b8-9aaf-4c05-8b73-b4273b876296”,
“relationship” : “pin”,
“toTerm” : {
“id” : “226e8ee3-f4b6-49d7-92d5-ec9d5475eec5”
},
“set” : {
“id” : “95e553ae-a91a-4670-a139-67a6cea285b3”
}
}

Use Case: Get all terms relation type reuse or pin under a term

Get all terms that have a pinned or reused relation with the given term.

GET https://graph.microsoft.com/v1.0/termStore/sets/{id}/terms/{id}/relations?$filter=(relationship eq 'pin' or relationship eq 'reuse')

HTTP/1.1 200 OK
{
“value”: [
{
“id” : “226e8ee3-f4b6-49d7-92d5-ec9d5475eec5”,
“relationship” : “pin”,
“toTerm” :{
“id” : “95e553ae-a91a-4670-a139-67a6cea285b3”
},
“fromTerm” :{
“id” : “310b04e0-b627-413f-9284-c770f1e24b47”
}
}
]
}

Use Case: Get all children of a term

Get all the children of a term.

GET https://graph.microsoft.com/v1.0/termStore/sets/{id}/terms/{id}/children

HTTP/1.1 200 OK
{
“value” :[
{
“id” : “95e553ae-a91a-4670-a139-67a6cea285b3”,
“labels” : [
{
“name” : “Cat”,
“isDefault” : true,
“languageTag” : “en-US”
}
]
}
]
}

Use Case: Create set

Creates a new set.

POST https://graph.microsoft.com/v1.0/termStore/sets/
{
"localizedNames" : [
{
"languageTag" : "en-US",
"name" : "Department"
}
],
"parentGroup" : {
"id" : "226e8ee3-f4b6-49d7-92d5-ec9d5475eec5"
}
}

HTTP/1.1 200 OK
{
“createdDateTime”: “2019-06-21T20:01:37Z”,
“description”: “Starting term Set”,
“id”: “8ed8c9ea-7052-4c1d-a4d7-b9c10bffea6f”,
“localizedNames” : [
{
“languageTag” : “en-US”,
“name” : “Department”
}
]
}

Use Case : Get a set

GET https://graph.microsoft.com/v1.0/termStore/groups/{id}/sets/{id}
GET https://graph.microsoft.com/v1.0/termStore/sets/{id}

HTTP/1.1 200 OK
{
“createdDateTime”: “2019-06-21T20:01:37Z”,
“description”: “Starting term Set”,
“id”: “8ed8c9ea-7052-4c1d-a4d7-b9c10bffea6f”,
“localizedNames” : [
{
“languageTag” : “en-US”,
“name” : “Department”
}
]
}

Use Case : Delete a set

DELETE https://graph.microsoft.com/v1.0/termStore/sets/{id}

HTTP/1.1 204 NO CONTENT

Use Case: Get all sets within a termGroup

GET https://graph.microsoft.com/v1.0/termStore/groups/{id}/sets/

HTTP/1.1 200 OK
{
“value”: [
{
“createdDateTime”: “2019-06-21T20:01:37Z”,
“description”: “Starting term Set”,
“id”: “8ed8c9ea-7052-4c1d-a4d7-b9c10bffea6f”,
“localizedNames” : [
{
“languageTag” : “en-US”,
“name” : “Department”
}
]
}
]
}

Use Case: Create a termGroup

POST https://graph.microsoft.com/v1.0/termStore/groups
{
"displayName" : "myGroup",
"description" : "My term group"
}

HTTP/1.1 200 OK
{
“createdDateTime”: “2019-06-21T20:01:37Z”,
“description”: “My term group”,
“scope” : “global”,
“id”: “b5f6c1f3-d345-4854-82ca-a63f71360bde”,
“displayName”: “myGroup”
}

Use Case: Get a termGroup

GET https://graph.microsoft.com/v1.0/termStore/groups/{id}

HTTP/1.1 200 OK
{
“createdDateTime”: “2019-06-21T20:01:37Z”,
“description”: “My term group”,
“scope” : “global”,
“id”: “b5f6c1f3-d345-4854-82ca-a63f71360bde”,
“dislayName”: “myGroup”
}

Use Case: Delete a termGroup

DELETE https://graph.microsoft.com/v1.0/termStore/groups/{id}

HTTP/1.1 204 NO CONTENT

Use Case: Get a termStore

GET https://graph.microsoft.com/v1.0/termStore/

HTTP/1.1 200 OK
{
“id” : “b5f6c1f3-d345-4854-82ca-a63f71360bde”,
“defaultLanguageTag” : “en-US”,
“languageTags” : [“en-US”, “de-DE”, “fr-FR”]
}