Skip to content

Taxonomy (Managed Metadata)

SharePoint's managed metadata system for consistent tagging across sites using hierarchical term stores, term groups, term sets, and terms.

Prerequisites

Requirement Description Reference
Read access to the term store Required to browse terms. Term Store Administrator role to create groups and term sets. SharePoint admin roles

How taxonomy is structured

graph TD
    Store["Term Store\n(tenant-level)"]
    Group["Term Group\n(e.g. Departments)"]
    TermSet["Term Set\n(e.g. Locations)"]
    Term["Term\n(e.g. Seattle)"]
    SubTerm["Sub Term\n(e.g. Downtown)"]

    Store --> Group
    Group --> TermSet
    TermSet --> Term
    Term --> SubTerm

The Term Store is the root, accessed via TaxonomyService. It contains groups, which contain term sets, which contain terms (which can nest).

Examples

Explore the term store

Step Operation File Required role API reference
1 Get term store info get_term_store_info.py Read access Taxonomy REST API
2 Get a term group by name get_group_by_name.py Read access Taxonomy REST API
3 Get a term set get_term_set.py Read access Taxonomy REST API
4 Get a term by ID get_term_by_id.py Read access Taxonomy REST API
5 Search terms search_term.py Read access Taxonomy REST API
6 Export term store to file export_term_store.py Read access Taxonomy REST API

Taxonomy fields

Step Operation File Required role API reference
7 Create taxonomy field on a list create_field.py Member on list Taxonomy REST API
8 Get taxonomy field value get_field_value.py Read access Taxonomy REST API
9 Set taxonomy field value set_field_value.py Contribute on item Taxonomy REST API

Quick start

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.taxonomy.service import TaxonomyService

ctx = ClientContext("https://contoso.sharepoint.com/sites/team").with_client_certificate(
    "contoso.onmicrosoft.com", client_id="client_id", thumbprint="thumbprint", cert_path="./cert.pem"
)

# Access the term store
tax_service = TaxonomyService(ctx)
store = tax_service.term_stores.get().execute_query()
print(f"Term Store: {store.name}  (default language: {store.default_language})")

# List term groups
for group in store.groups:
    print(f"  Group: {group.name}")

API reference