TAXML Reference

TAXML is an XML-based file format for storing SharePoint Taxonomy objects. Its XML Schema Definition (XSD) is defined in TaxmlFile.xsd from this toolkit.

Basic TAXML Examples

Here is a simple TAXML file that creates a Taxonomy term and child term:

<?xml version="1.0" encoding="utf-8"?>
<TaxmlFile Version="2.1.0.0">
    <TermStore>
        <TermSetGroup Name="Example Group">
            <TermSet Name="Example TermSet">
                <Term Name="Example Term">
                    <Term Name="Child Term" />
                </Term>
            </TermSet>
        </TermSetGroup>
    </TermStore>
</TaxmlFile>

Since the object GUIDs are omitted, they will be randomly assigned. Typically it is recommended to specify the GUIDs to avoid broken references in SharePoint if the file is reimported later. If you use Export-Taxml to export the data imported above, the IDs will be included automatically:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<TaxmlFile Version="2.1.0.0">
    <TermStore>
        <TermSetGroup Name="Example Group" Id="{c6533b67-ec10-420a-bcea-b9eb8b992192}">
            <TermSet Name="Example TermSet" Id="{91ef0721-b8dc-4608-9933-5e180fd1e1c4}">
                <Term Name="Example Term" Id="{8a9dc5b9-df2d-49ce-bb20-3659ab65b89a}">
                    <Term Name="Child Term" Id="{635de542-2163-4254-901b-b1f23399b984}" />
                </Term>
            </TermSet>
        </TermSetGroup>
    </TermStore>
</TaxmlFile>

Here is a more complete syntax example that illustrates most of the XML elements and attributes from the TAXML schema:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<TaxmlFile Version="2.1.0.0">
    <TermStore>
        <SyncAction 
            IfMissing="Create" 
            IfPresent="Update" 
            IfElsewhere="Error" 
            DeleteExtraChildItems="false" />

        <TermSetGroup Name="Example Group" Id="{a6c04701-ca4d-4525-bfdf-5f07ac605107}">

            <Description>Description for TestGroup1</Description>

            <TermSet Name="TermSet A" Id="{f7257f38-b8ed-41d6-b226-d692be5f3a58}" 
                IsAvailableForTagging="false" 
                IsOpenForTermCreation="true" 
                Owner="domain\testuser1" 
                Contact="domain\testuser2">

                <LocalizedName Language="1036">TermSet A - French</LocalizedName>
                <Description>Description for TermSet A</Description>
                <Property Name="Property1">Value1</Property>
                <Property Name="Property2">Value2</Property>
                <Stakeholder>domain\testuser3</Stakeholder>

                <Term Name="Term 1" Id="{77599145-5887-4188-9bdb-fc5cc6c36ffc}" 
                    InOrder="true"
                    Owner="domain\testuser3">

                    <Property Name="Property3">Value3</Property>
                    <LocalProperty Name="LocalProperty4">TermSet A Value</LocalProperty>
                    <LocalizedDescription>Description for Term 1</LocalizedDescription>
                    <LocalizedDescription Language="1036">French Description</LocalizedDescription>
                    <Label>Synonym Label</Label>
                    <Label Language="1036" IsDefaultForLanguage="true">French Label</Label>
                </Term>
                <Term Name="Term 2" Id="{bb898241-487e-4467-916a-65789fa1e75b}"
                    IsDeprecated="true" />
            </TermSet>
            <TermSet Name="TermSet B" Id="{cbff710a-2a9e-415c-b572-75f9c7abad9a}">
                <TermLink NameHint="Term 1" Id="{77599145-5887-4188-9bdb-fc5cc6c36ffc}"
                    IsPinnedRoot="false" 
                    InOrder="true" 
                    IsAvailableForTagging="false">

                    <LocalProperty Name="LocalProperty4">TermSet B Value</LocalProperty>
                </TermLink>
            </TermSet>
        </TermSetGroup>
    </TermStore>
</TaxmlFile>

Reused Terms

The SharePoint Taxonomy supports a concept of "reusing" a term, i.e. allowing it to belong to more than one term set. One of the instances must be designated as the "source term" which is used for certain security checks. All instances have the same GUID. Most data properties are also shared between instances, e.g. if the term's name or description is changed, all instances will immediately reflect this change. However there are also some "local" properties (e.g. IsAvailableForTagging) whose value is tracked separately for each reused instance. The user-definable custom properties also support shared and local storage (via the Property and LocalProperty TAXML elements).

To avoid accidentally specifying the same property in more than one place, TAXML uses the special TermLink element to represent the local properties; the Term element is only used for the source term.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<TaxmlFile Version="2.1.0.0">
    <TermStore>
        <TermSetGroup Name="Example Group">
            <TermSet Name="TermSet A">
                <!-- the source term -->
                <Term Name="Reused Term" Id="{8a9dc5b9-df2d-49ce-bb20-3659ab65b89a}">
                    <Property Name="SharedData">Shared Value</Property>
                    <LocalProperty Name="LocalData">Value A</LocalProperty>
                </Term>
            </TermSet>
            <TermSet Name="TermSet B">
                <!-- a reused instance -->
                <TermLink NameHint="Reused Term" Id="{8a9dc5b9-df2d-49ce-bb20-3659ab65b89a}">
                    <LocalProperty Name="LocalData">Value B</LocalProperty>
                </TermLink>
            </TermSet>
            <TermSet Name="TermSet C">
                <!-- another reused instance -->
                <TermLink NameHint="Reused Term" Id="{8a9dc5b9-df2d-49ce-bb20-3659ab65b89a}">
                    <LocalProperty Name="LocalData">Value C</LocalProperty>
                </TermLink>
            </TermSet>
        </TermSetGroup>
    </TermStore>
</TaxmlFile>

In the above example, the reused instances are found by matching the GUID. (The NameHint is an optional attribute used only for documentation purposes.) As an alternative, the TermLinkSourcePath attribute provides a way to specify the source term by name. The parent object names must also be included in the path. The name is matched using the default language for the term store. Here is an example:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<TaxmlFile Version="2.1.0.0">
    <TermStore>
        <TermSetGroup Name="Example Group">
            <TermSet Name="TermSet A">
                <!-- the source term -->
                <Term Name="Reused Term">
                    <Property Name="SharedData">Shared Value</Property>
                    <LocalProperty Name="LocalData">Value A</LocalProperty>
                </Term>
            </TermSet>
            <TermSet Name="TermSet B">
                <!-- a reused instance -->
                <TermLink TermLinkSourcePath="Example Group;TermSet A;Reused Term">
                    <LocalProperty Name="LocalData">Value B</LocalProperty>
                </TermLink>
            </TermSet>
        </TermSetGroup>
    </TermStore>
</TaxmlFile>

If the TermLink's source term cannot be found in the TAXML file, the importer will look for a pre-existing object on the server. This is referred to as an "external reference" in the toolkit documentation. It is supported with both the Id and TermLinkSourcePath approaches.

Updating using SyncAction

The above examples assumed that the TAXML objects we being initially created and did not yet exist on the SharePoint server. The SyncAction element specifies the policy that the importer should follow for objects that already exist on the server. It can be applied to the TermStore, TermSetGroup, TermSet, Term, and TermLink elements. If it is omitted, the importer will inherit the policy of the closest parent object that has a SyncAction. If there is no such parent, then the default action is used.

The SyncAction describes the action to take if the object is completely "missing", if it is "present" in the expected location, or if it exists "elsewhere". By "elsewhere" we mean a term set that belongs to the wrong group, or a term instance that is in the correct term set but under the wrong parent. (If the term exists in a different term set, TAXML assumes that the intent is to create a reused term instance.)

The XML attributes for SyncAction are:
  • IfMissing:
    • Create: Create the missing object and assign all properties as specified in TAXML
    • DoNothing: (not yet implemented)
    • Error: Report an error and abort the import operation
  • IfPresent:
    • Update: Reassign all properties of the object to exactly match the TAXML file; any extra properties will be deleted.
    • OnlyUpdateChildItems: Make no changes to the object, but proceed with processing any child objects
    • DeleteAndRecreate: (not yet implemented)
    • DoNothing: (not yet implemented)
    • Error: Report an error and abort the import operation
  • IfElsewhere:
    • MoveAndUpdate: (not yet implemented)
    • DeleteAndRecreate: (not yet implemented)
    • DoNothing: (not yet implemented)
    • Error: Report an error and abort the import operation
  • DeleteExtraChildItems:
    • true: (not yet implemented)
    • false: If the current object has any child objects on the server that were not specified in the TAXML file, ignore them (i.e. do not delete them). |

The default action is to fail unless we are creating the objects for the first time, and not to delete any extra items:

<SyncAction IfMissing="Create" IfPresent="Error" IfElsewhere="Error"
    DeleteExtraChildItems="false" />

Here's an example showing how to find and update a specific child term, without altering any of its parents:

<?xml version="1.0" encoding="utf-8"?>
<TaxmlFile Version="2.1.0.0">
    <TermStore>
        <SyncAction
            IfMissing="Error"
            IfPresent="OnlyUpdateChildItems"
            IfElsewhere="Error"
            DeleteExtraChildItems="false" />

        <!-- No changes will be made to this group -->
        <TermSetGroup Name="Example Group">
            <!-- No changes will be made to this term set -->
            <TermSet Name="Example TermSet">
                <!-- No changes will be made to this term -->
                <Term Name="Example Term">
                    <Term Name="Child Term">
                        <SyncAction
                            IfMissing="Error"
                            IfPresent="Update"
                            IfElsewhere="Error"
                            DeleteExtraChildItems="false" />
                        <!-- 
                            Note that IfPresent=Update doesn't perform any merging; any
                            other custom properties will be deleted, and all other
                            properties of this term (e.g. description, labels, etc)
                            will be reset to the default values.
                        -->
                        <Property Name="Property1">Value1</Property>
                    </Term>
                </Term>
            </TermSet>
        </TermSetGroup>
    </TermStore>
</TaxmlFile>

Custom Sort Order

By default, the SharePoint Taxonomy displays terms sorted in alphabetical order, according to the term names in the currently selected language. (For example, the display order may change if you switch the Term Store Manager locale from English to French.) If you need to manually specify the ordering, SharePoint supports an optional custom sort order. It is stored with the parent object (a term or term set), and consists of a list of child term GUIDs in the order they should be displayed. Any extra terms that aren't mentioned in this list will be displayed in alphabetical order after the terms that do match. If the list contains extra GUIDs that don't match any child terms, they will be ignored by SharePoint, but may take effect if the missing child terms are created later.

The custom sort order applies to both Term and TermLink elements. TAXML provides two different representations for specifying it.

The CustomSortOrder element

This specifies the list of GUIDs explicitly. It has the advantage of supporting the advanced case of extra GUIDs (described above), but the disadvantage of being somewhat verbose.

For example:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<TaxmlFile Version="2.1.0.0">
    <TermStore>
        <TermSetGroup Name="Example Group" Id="{c6533b67-ec10-420a-bcea-b9eb8b992192}">
            <TermSet Name="Example TermSet" Id="{91ef0721-b8dc-4608-9933-5e180fd1e1c4}">
                <!-- Override to sort in reverse order:  "Term 3", "Term 2", "Term 1" -->
                <CustomSortOrder>
                    <Item Id="{b217c2ac-4ce8-43d8-a99f-e88133c6179e}" />
                    <Item Id="{b1e64065-3959-4e0c-b52f-91ef638d1326}" />
                    <Item Id="{68226ab0-9e06-486f-aad4-bc725b21f92c}" />
                </CustomSortOrder>

                <Term Name="Term 1" Id="{68226ab0-9e06-486f-aad4-bc725b21f92c}" />
                <Term Name="Term 2" Id="{b1e64065-3959-4e0c-b52f-91ef638d1326}" />
                <Term Name="Term 3" Id="{b217c2ac-4ce8-43d8-a99f-e88133c6179e}" >
                    <!-- 
                        Term 1 Child 3 comes first, the others sort in alphabetical order.
                        English:  "Child 3", "Child 1", "Child 2"
                        French:   "Child 3", "Child Two", "First Child"
                    -->
                    <CustomSortOrder>
                        <Item Id="{ec69a972-a7af-426b-895b-f59b29fc61d5}" />
                    </CustomSortOrder>

                    <Term Name="Child 1" Id="{1731958e-aab5-4bfd-a973-1086a015225c}">
                        <Label Language="1036" IsDefaultForLanguage="true">First Child</Label>
                    </Term>
                    <Term Name="Child 2" Id="{fd26afa2-fbde-4bb5-904e-6b13f5514142}">
                        <Label Language="1036" IsDefaultForLanguage="true">Child Two</Label>
                    </Term>
                    <Term Name="Child 3" Id="{ec69a972-a7af-426b-895b-f59b29fc61d5}" />
                </Term>
            </TermSet>
        </TermSetGroup>
    </TermStore>
</TaxmlFile>

The InOrder attribute

This is a convenient shorthand that avoids the need to enter each GUID in two places. Even though the custom sort order is actually a property of the parent object, the InOrder attribute is specified on the child objects in the TAXML file. As such, it has the disadvantage that it cannot be used for the advanced case of extra GUIDs that don't appear in the TAXML file.

In the future, the importer may support usage of the InOrder attribute when the Id attribute is omitted (i.e. assigned by the importer), but currently it is just an alternative syntax. This example is exactly equivalent to the above example:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<TaxmlFile Version="2.1.0.0">
    <TermStore>
        <TermSetGroup Name="Example Group" Id="{c6533b67-ec10-420a-bcea-b9eb8b992192}">
            <TermSet Name="Example TermSet" Id="{91ef0721-b8dc-4608-9933-5e180fd1e1c4}">
                <!-- Override to sort in reverse order:  "Term 3", "Term 2", "Term 1" -->
                <Term Name="Term 3" Id="{b217c2ac-4ce8-43d8-a99f-e88133c6179e}" InOrder="true">
                    <!-- 
                        Term 1 Child 3 comes first, the others sort in alphabetical order.
                        English:  "Child 3", "Child 1", "Child 2"
                        French:   "Child 3", "Child Two", "First Child"
                    -->
                    <Term Name="Child 1" Id="{1731958e-aab5-4bfd-a973-1086a015225c}">
                        <Label Language="1036" IsDefaultForLanguage="true">First Child</Label>
                    </Term>
                    <Term Name="Child 2" Id="{fd26afa2-fbde-4bb5-904e-6b13f5514142}">
                        <Label Language="1036" IsDefaultForLanguage="true">Child Two</Label>
                    </Term>
                    <Term Name="Child 3" Id="{ec69a972-a7af-426b-895b-f59b29fc61d5}" InOrder="true" />
                </Term>
                <Term Name="Term 2" Id="{b1e64065-3959-4e0c-b52f-91ef638d1326}" InOrder="true" />
                <Term Name="Term 1" Id="{68226ab0-9e06-486f-aad4-bc725b21f92c}" InOrder="true" />
            </TermSet>
        </TermSetGroup>
    </TermStore>
</TaxmlFile>

NOTE: Except for elements with InOrder=true, the order that objects are declared in the TAXML file does not affect the order in which they are displayed by SharePoint. It does influence the order in which they are created by the importer.


Last edited Sep 28, 2015 at 5:15 AM by pgonzal, version 10