Skip to main content

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

PropertyTypeDescriptionKeyRequiredReadOnly
idstringUnique identifier of termStore.YesYes
defaultLanguageTagstringDefault language tag for all meta-data in the system.NoNo
languageTagsCollection(string)List of working language tags of termStore.NoNo

Relationships

PropertyTypeDescriptionContained Navigation PropertyNullableReadOnly
groupsCollection(microsoft.graph.termStore.group)Collection of all termsGroups available in the termStore.YesYesNo
setsCollection(microsoft.graph.termStore.set)Collection of all sets within the termStore.NoYesNo

Supported functionality

OperationSupportedMethodSuccessNotes
GetGET200
CreateXPOST201
UpdatePATCH204
DeleteXDELETE204

{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

PropertyTypeDescriptionKeyRequiredReadOnly
idstringUnique identifier of group.YesYesYes
createdDateTimeDateTimeOffsetDate and time of group creation.NoNoYes
descriptionstringDescription giving details on the group usage.NoNoNo
scopemicrosoft.graph.termStore.groupScopeReturns type of group. Possible values are global , system and siteCollection.NoYesYes
displayNamestringName of groupNoYesNo

Relationships

PropertyTypeDescriptionContained Navigation PropertyNullableReadOnly
setsCollection(microsoft.graph.termStore.set)All sets under the termGroupYesYesNo

Supported functionality

OperationSupportedMethodSuccessNotes
GetGET200
CreatePOST201
UpdatePATCH204
DeleteDELETE204

Errors

ScenarioMethodCodeMessage
Trying to delete a System groupDELETE405Deleting a system group is disallowed
Trying to delete a group that is not emptyDELETE405A group cannot be deleted unless it is empty
Trying to access a group that does not existsGET404Cannot find group
Modify name of group that already existsPATCH409Group names must be unique
Modify property of group which user does not have access toPATCH403Current user has insufficient permissions to perform this.
Trying to create a group while user does not have permissionPOST403Current user has insufficient permissions
Trying to delete a group while user does not have permissionsDELETE403Current user has insufficient permissions

{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

PropertyTypeDescriptionKeyRequiredReadOnly
idstringUnique identifier of set.YesYesYes
createdDateTimeDateTimeOffsetDate and time of set creation.NoNoYes
descriptionstringDescription giving details on the set usage.NoNoNo
localizedNamesCollection(microsoft.graph.termStore.localizedName)Language tag specific name of a set.NoYesNo
propertiesCollection(microsoft.graph.keyValue)custom properties for set.NoNo

Relationships

PropertyTypeDescriptionContained Navigation PropertyNullableReadOnly
childrenCollection(microsoft.graph.termStore.term)Terms that form the immediate top-level terms of the set.YesYesNo
parentGroupmicrosoft.graph.termStore.groupGroup containing the particular set.NoNoNo
relationsCollection(microsoft.graph.termStore.relation)relations that are directly attached to the Set than to a specific term. The target terms of the relation are top-level terms of the Set.YesYesNo
termsCollection(microsoft.graph.termStore.term)all terms that are present in the setYesNoNo

Supported functionality

OperationSupportedMethodSuccessNotes
GetGET200
CreatePOST201
UpdatePATCH204
DeleteDELETE204

Errors

ScenarioMethodCodeMessage
Trying to delete a System setDELETE405Deleting a system set is disallowed
Trying to access a set that does not existsGET404Cannot find set
Modify name of set that already existsPATCH409A term set already exists with name specified.
Modify property of set which user does not have access toPATCH403Current user has insufficient permissions to perform this.
Trying to create a set while user does not have permissionPOST403Current user has insufficient permissions
Trying to delete a set while user does not have permissionsDELETE403Current user has insufficient permissions

{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

PropertyTypeDescriptionKeyRequiredReadOnly
createdDateTimeDateTimeOffsetDate and time of term creation.NoYes
descriptionsCollection(microsoft.graph.termStore.localizedDescription)Description about term for each language tag.NoNo
idstringUnique identifier of term.YesYes
labelsCollection(microsoft.graph.termStore.localizedLabel)The labels that can be present on a term. Labels can be language tag specific, and for a given language tag one default label is allowed.NoNo
lastModifiedDateTimeDateTimeOffSetLast date and time of term modification.NoYes
propertiesCollection(microsoft.graph.keyValue)Collection of properties of a term.NoNo

Relationships

PropertyTypeDescriptionContained Navigation PropertyNullableReadOnly
childrenCollection(microsoft.graph.termStore.term)Children of a specific term.NoYesNo
setmicrosoft.graph.termStore.setIf the set is not null then the relation is defined with respect to a particular set.
relationsCollection(microsoft.graph.termStore.relation)Relationship a term has with other terms or setsYesNoNo

Supported functionality

OperationSupportedMethodSuccessNotes
GetGET200
CreatePOST201
UpdatePATCH204
DeleteDELETE204

Errors

ScenarioMethodCodeMessage
Trying to access a term that does not existsGET404Cannot find term
Modify property of term which user does not have access toPATCH403Current user has insufficient permissions to perform this.
Trying to create a term while user does not have permissionPOST403Current user has insufficient permissions
Trying to delete a term while user does not have permissionsDELETE403Current user has insufficient permissions

{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

PropertyTypeDescriptionKeyRequiredReadOnly
idstringId of relationship.YesYesYes
relationshipmicrosoft.graph.termStore.relationTypeIndicates the type of the relationship. Possible values are pin and reuseNoYesYes

Relationships

PropertyTypeDescriptionContained Navigation PropertyNullableReadOnly
fromTermmicrosoft.graph.termStore.termIndicates the “from” term of the relationship. If null then the relationships is with a set directlyNoYesYes
toTermmicrosoft.graph.termStore.termIndicates the “to” term of the relationship.NoNoYes
setmicrosoft.graph.termStore.setIndicates the set with respect to which the relationship is defined. If null then indicates the relationship is between the two terms only.NoYesYes

Supported functionality

OperationSupportedMethodSuccessNotes
GetGET200
CreatePOST201

Errors

ScenarioMethodCodeMessage
Trying to create a relation with invalid parameters or between terms that do not existsPOST400
Get relations of a term that does not existsGET404Term not found
Trying to create a relation in a set where the term already has been reusedPOST400A term cannot be shared multiple times in same term set.

 

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

PropertyTypeDescriptionRequiredReadOnly
isDefaultbooleanWhether the given label is the default label for the languagIdYesNo
languageTagstringLanguage tag for the labelYesNo
namestringName of the labelYesNo

{microsoft.graph.termStore.localizedDescription}

The description of each term specific to a language tag.

JSON representation

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

PropertyTypeDescriptionRequiredReadOnly
languageTagstringLanguage tag for the descriptionYesNo
descriptionstringdescription specific to a language tagYesNo

{microsoft.graph.termStore.localizedName}

Name of a termSet specific to a language tag.

JSON representation

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

PropertyTypeDescriptionRequiredReadOnly
languageTagstringLanguage tag for the nameYesNo
namestringName of a termSet specific to a language tagYesNo

{microsoft.graph.keyValue}

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

JSON representation

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

Properties

PropertyTypeDescriptionRequiredReadOnly
keystringkey of the property being definedYesNo
valuestringvalue of the property being definedYesNo

 

New enums

{microsoft.graph.termStore.groupScope}

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

ValueDescription
globalGlobal group in the termStore which is visible across different sites
systemSystem groups are defined and created for every tenant at the time of provisioning. These groups have certain properties that cannot be changed by the user.
siteCollectionThese term-groups are specific to a share-point site.

{microsoft.graph.termStore.relationType}

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

ValueDescription
pinThis specifies that a term is related to another term using the pinned relationship.
reuseThis specifies that a term is related to another term using the reused relationship.

 

New permission scopes

ScopeNameDisplayNameDescriptionTypeAdmin Consent?Entities/APIs covered
TermStore.Read.AllTermStore.ReadThe application can read all data in the termStoreDelegatedYesCan use all APIs that allow for read of termStore,groups,sets and terms
TermStore.ReadWrite.AllTermStore.ReadWriteThe appilication can read or write to any data in the termStoreDelegatedYesCan use all APIs that allow for read/write of termStore,groups,sets and terms

 

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”]
}