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.
- store
- termGroups
- sets
- terms
- 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
Property | Type | Description | Key | Required | ReadOnly |
id | string | Unique identifier of termStore. | Yes | Yes | |
defaultLanguageTag | string | Default language tag for all meta-data in the system. | No | No | |
languageTags | Collection(string) | List of working language tags of termStore. | No | No |
Relationships
Property | Type | Description | Contained Navigation Property | Nullable | ReadOnly |
groups | Collection(microsoft.graph.termStore.group) | Collection of all termsGroups available in the termStore. | Yes | Yes | No |
sets | Collection(microsoft.graph.termStore.set) | Collection of all sets within the termStore. | No | Yes | No |
Supported functionality
Operation | Supported | Method | Success | Notes |
Get | ✓ | GET | 200 | |
Create | X | POST | 201 | |
Update | ✓ | PATCH | 204 | |
Delete | X | DELETE | 204 |
{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
Property | Type | Description | Key | Required | ReadOnly |
id | string | Unique identifier of group. | Yes | Yes | Yes |
createdDateTime | DateTimeOffset | Date and time of group creation. | No | No | Yes |
description | string | Description giving details on the group usage. | No | No | No |
scope | microsoft.graph.termStore.groupScope | Returns type of group. Possible values are global , system and siteCollection. | No | Yes | Yes |
displayName | string | Name of group | No | Yes | No |
Relationships
Property | Type | Description | Contained Navigation Property | Nullable | ReadOnly |
sets | Collection(microsoft.graph.termStore.set) | All sets under the termGroup | Yes | Yes | No |
Supported functionality
Operation | Supported | Method | Success | Notes |
Get | ✓ | GET | 200 | |
Create | ✓ | POST | 201 | |
Update | ✓ | PATCH | 204 | |
Delete | ✓ | DELETE | 204 |
Errors
Scenario | Method | Code | Message |
Trying to delete a System group | DELETE | 405 | Deleting a system group is disallowed |
Trying to delete a group that is not empty | DELETE | 405 | A group cannot be deleted unless it is empty |
Trying to access a group that does not exists | GET | 404 | Cannot find group |
Modify name of group that already exists | PATCH | 409 | Group names must be unique |
Modify property of group which user does not have access to | PATCH | 403 | Current user has insufficient permissions to perform this. |
Trying to create a group while user does not have permission | POST | 403 | Current user has insufficient permissions |
Trying to delete a group while user does not have permissions | DELETE | 403 | Current 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
Property | Type | Description | Key | Required | ReadOnly |
id | string | Unique identifier of set. | Yes | Yes | Yes |
createdDateTime | DateTimeOffset | Date and time of set creation. | No | No | Yes |
description | string | Description giving details on the set usage. | No | No | No |
localizedNames | Collection(microsoft.graph.termStore.localizedName) | Language tag specific name of a set. | No | Yes | No |
properties | Collection(microsoft.graph.keyValue) | custom properties for set. | No | No |
Relationships
Property | Type | Description | Contained Navigation Property | Nullable | ReadOnly |
children | Collection(microsoft.graph.termStore.term) | Terms that form the immediate top-level terms of the set. | Yes | Yes | No |
parentGroup | microsoft.graph.termStore.group | Group containing the particular set. | No | No | No |
relations | Collection(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. | Yes | Yes | No |
terms | Collection(microsoft.graph.termStore.term) | all terms that are present in the set | Yes | No | No |
Supported functionality
Operation | Supported | Method | Success | Notes |
Get | ✓ | GET | 200 | |
Create | ✓ | POST | 201 | |
Update | ✓ | PATCH | 204 | |
Delete | ✓ | DELETE | 204 |
Errors
Scenario | Method | Code | Message |
Trying to delete a System set | DELETE | 405 | Deleting a system set is disallowed |
Trying to access a set that does not exists | GET | 404 | Cannot find set |
Modify name of set that already exists | PATCH | 409 | A term set already exists with name specified. |
Modify property of set which user does not have access to | PATCH | 403 | Current user has insufficient permissions to perform this. |
Trying to create a set while user does not have permission | POST | 403 | Current user has insufficient permissions |
Trying to delete a set while user does not have permissions | DELETE | 403 | Current 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
Property | Type | Description | Key | Required | ReadOnly |
createdDateTime | DateTimeOffset | Date and time of term creation. | No | Yes | |
descriptions | Collection(microsoft.graph.termStore.localizedDescription) | Description about term for each language tag. | No | No | |
id | string | Unique identifier of term. | Yes | Yes | |
labels | Collection(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. | No | No | |
lastModifiedDateTime | DateTimeOffSet | Last date and time of term modification. | No | Yes | |
properties | Collection(microsoft.graph.keyValue) | Collection of properties of a term. | No | No |
Relationships
Property | Type | Description | Contained Navigation Property | Nullable | ReadOnly |
children | Collection(microsoft.graph.termStore.term) | Children of a specific term. | No | Yes | No |
set | microsoft.graph.termStore.set | If the set is not null then the relation is defined with respect to a particular set. | |||
relations | Collection(microsoft.graph.termStore.relation) | Relationship a term has with other terms or sets | Yes | No | No |
Supported functionality
Operation | Supported | Method | Success | Notes |
Get | ✓ | GET | 200 | |
Create | ✓ | POST | 201 | |
Update | ✓ | PATCH | 204 | |
Delete | ✓ | DELETE | 204 |
Errors
Scenario | Method | Code | Message |
Trying to access a term that does not exists | GET | 404 | Cannot find term |
Modify property of term which user does not have access to | PATCH | 403 | Current user has insufficient permissions to perform this. |
Trying to create a term while user does not have permission | POST | 403 | Current user has insufficient permissions |
Trying to delete a term while user does not have permissions | DELETE | 403 | Current 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
Property | Type | Description | Key | Required | ReadOnly |
id | string | Id of relationship. | Yes | Yes | Yes |
relationship | microsoft.graph.termStore.relationType | Indicates the type of the relationship. Possible values are pin and reuse | No | Yes | Yes |
Relationships
Property | Type | Description | Contained Navigation Property | Nullable | ReadOnly |
fromTerm | microsoft.graph.termStore.term | Indicates the “from” term of the relationship. If null then the relationships is with a set directly | No | Yes | Yes |
toTerm | microsoft.graph.termStore.term | Indicates the “to” term of the relationship. | No | No | Yes |
set | microsoft.graph.termStore.set | Indicates the set with respect to which the relationship is defined. If null then indicates the relationship is between the two terms only. | No | Yes | Yes |
Supported functionality
Operation | Supported | Method | Success | Notes |
Get | ✓ | GET | 200 | |
Create | ✓ | POST | 201 |
Errors
Scenario | Method | Code | Message |
Trying to create a relation with invalid parameters or between terms that do not exists | POST | 400 | |
Get relations of a term that does not exists | GET | 404 | Term not found |
Trying to create a relation in a set where the term already has been reused | POST | 400 | A 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
Property | Type | Description | Required | ReadOnly |
isDefault | boolean | Whether the given label is the default label for the languagId | Yes | No |
languageTag | string | Language tag for the label | Yes | No |
name | string | Name of the label | Yes | No |
{microsoft.graph.termStore.localizedDescription}
The description of each term specific to a language tag.
JSON representation
{
"languageTag" : "string",
"description" : "string"
}
Property | Type | Description | Required | ReadOnly |
languageTag | string | Language tag for the description | Yes | No |
description | string | description specific to a language tag | Yes | No |
{microsoft.graph.termStore.localizedName}
Name of a termSet specific to a language tag.
JSON representation
{
"languageTag" : "string",
"name" : "string"
}
Property | Type | Description | Required | ReadOnly |
languageTag | string | Language tag for the name | Yes | No |
name | string | Name of a termSet specific to a language tag | Yes | No |
{microsoft.graph.keyValue}
Key value pair used to make a custom property in a termStore.
JSON representation
{
"key" : "string",
"value" : "string"
}
Properties
Property | Type | Description | Required | ReadOnly |
key | string | key of the property being defined | Yes | No |
value | string | value of the property being defined | Yes | No |
New enums
{microsoft.graph.termStore.groupScope}
The enum defines the various types of groups we can have within the termStore.
Value | Description |
global | Global group in the termStore which is visible across different sites |
system | System 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. |
siteCollection | These 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
Value | Description |
pin | This specifies that a term is related to another term using the pinned relationship. |
reuse | This specifies that a term is related to another term using the reused relationship. |
New permission scopes
ScopeName | DisplayName | Description | Type | Admin Consent? | Entities/APIs covered |
TermStore.Read.All | TermStore.Read | The application can read all data in the termStore | Delegated | Yes | Can use all APIs that allow for read of termStore,groups,sets and terms |
TermStore.ReadWrite.All | TermStore.ReadWrite | The appilication can read or write to any data in the termStore | Delegated | Yes | Can 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”]
}