Edit

Compare the XML manifest with the unified manifest for Microsoft 365

  • Article

This article is intended to help readers who are familiar with the XML manifest understand the unified manifest by comparing the two. Readers should also see Office Add-ins with the unified manifest for Microsoft 365 (preview).

Note

The unified manifest is a preview feature of Office Add-ins and is only supported for Outlook on Windows.

Schemas and general points

There is just one schema for the preview unified manifest, in contrast to the current XML manifest which has a total of seven schemas.

Conceptual mapping of the preview unified and current XML manifests

This section describes the preview unified manifest for readers who are familiar with the current XML manifest. Some points to keep in mind:

  • The unified manifest is JSON-formatted.

  • JSON doesn't distinguish between attribute and element value like XML does. Typically, the JSON that maps to an XML element makes both the element value and each of the attributes a child property. The following example shows some XML markup and its JSON equivalent.

    <MyThing color="blue">Some text</MyThing>

    "myThing" : {
    "color": "blue",
    "text": "Some text"
}

  • There are many places in the current XML manifest where an element with a plural name has children with the singular version of the same name. For example, the markup to configure a custom menu includes an <Items> element which can have multiple <Item> element children. The JSON equivalent of these plural elements is a property with an array as its value. The members of the array are anonymous objects, not properties named "item" or "item1", "item2", etc. The following is an example.

    "items": [
    {
        -- markup for a menu item is here --
    },
    {
        -- markup for another menu item is here --
    }
]

Top-level structure

The root level of the preview unified manifest, which roughly corresponds to the <OfficeApp> element in the current XML manifest, is an anonymous object.

The children of <OfficeApp> are commonly divided into two notional categories. The <VersionOverrides> element is one category. The other consists of all the other children of <OfficeApp>, which are collectively referred to as the base manifest. So too, the preview unified manifest has a similar division. There is a top-level "extensions" property that roughly corresponds in its purposes and child properties to the <VersionOverrides> element. The preview unified manifest also has over 10 other top-level properties that collectively serve the same purposes as the base manifest of the XML manifest. These other properties can be thought of collectively as the base manifest of the unified manifest.

Base manifest

The base manifest properties specify characteristics of the add-in that any type of extension of Microsoft 365 is expected to have. This includes Teams tabs and message extensions, not just Office add-ins. These characteristics include a public name and a unique ID. The following table shows a mapping of some critical top-level properties in the preview unified manifest to the XML elements in the current manifest, where the mapping principle is the purpose of the markup.

JSON property Purpose XML elements Comments
"$schema" Identifies the manifest schema. attributes of <OfficeApp> and <VersionOverrides> None.
"id" GUID of the add-in. <Id> None.
"version" Version of the add-in. <Version> None.
"manifestVersion" Version of the manifest schema. attributes of <OfficeApp> None.
"name" Public name of the add-in. <DisplayName> None.
"description" Public description of the add-in. <Description> None.
"accentColor" None. None. This property has no equivalent in the current XML manifest and isn't used in the preview of the unified manifest. But it must be present.
"developer" Identifies the developer of the add-in. <ProviderName> None.
"localizationInfo" Configures the default locale and other supported locales. <DefaultLocale> and <Override> None.
"webApplicationInfo" Identifies the add-in's web app as it is known in Azure Active Directory. <WebApplicationInfo> In the current XML manifest, the <WebApplicationInfo> element is inside <VersionOverrides>, not the base manifest.
"authorization" Identifies any Microsoft Graph permissions that the add-in needs. <WebApplicationInfo> In the current XML manifest, the <WebApplicationInfo> element is inside <VersionOverrides>, not the base manifest.

The <Hosts>, <Requirements>, and <ExtendedOverrides> elements are part of the base manifest in the current XML manifest. But concepts and purposes associated with these elements are configured inside the "extensions" property of the preview unified manifest.

"extensions" property

The "extensions" property in the preview unified manifest primarily represents characteristics of the add-in that wouldn't be relevant to other kinds of Microsoft 365 extensions. For example, the Office applications that the add-in extends (such as, Excel, PowerPoint, Word, and Outlook) are specified inside the "extensions" property, as are customizations of the Office application ribbon. The configuration purposes of the "extensions" property closely match those of the <VersionOverrides> element in the current XML manifest.

Note

The <VersionOverrides> section of the current XML manifest has a "double jump" system for many string resources. Strings, including URLs, are specified and assigned an ID in the <Resources> child of <VersionOverrides>. Elements that require a string have a resid attribute that matches the ID of a string in the <Resources> element. The "extensions" property of the preview unified manifest simplifies things by defining strings directly as property values. There is nothing in the unified manifest that is equivalent to the <Resources> element.

The following table shows a mapping of some high level child properties of the "extensions" property in the preview unified manifest to XML elements in the current manifest. Dot notation is used to reference child properties.

JSON property Purpose XML elements Comments
"requirements.capabilities" Identifies the requirement sets that the add-in needs to be installable. that the add-in needs to be installable. <Requirements> and <Sets> None.
"requirements.scopes" Identifies the Office applications in which the add-in can be installed. <Hosts> None.
"ribbons" The ribbons that the add-in customizes. <Hosts>, ExtensionPoints, and various *FormFactor elements The "ribbons" property is an array of anonymous objects that each merge the purposes of the these three elements. See "ribbons" table.
"alternatives" Specifies backwards compatibility with an equivalent COM add-in, XLL, or both. <EquivalentAddins> See the EquivalentAddins - See also for background information.
"runtimes" Configures the embedded runtimes that the add-in uses, including various kinds of add-ins that have little or no UI, such as custom function-only add-ins and function commands. <Runtimes>. <FunctionFile>, and <ExtensionPoint> (of type CustomFunctions) None.
"autoRunEvents" Configures an event handler for a specified event. <ExtensionPoint> (of type LaunchEvent) None.

"ribbons" table

The following table maps the child properties of the anonymous child objects in the "ribbons" array onto XML elements in the current manifest.

JSON property Purpose XML elements Comments
"contexts" Specifies the command surfaces that the add-in customizes. various *CommandSurface elements, such as PrimaryCommandSurface and MessageReadCommandSurface None.
"tabs" Configures custom ribbon tabs. <CustomTab> The names and hierarchy of the descendant properties of "tabs" closely match the descendants of <CustomTab>.

For a full sample unified manifest, see Sample preview unified manifest.

Next steps