What does the Office add-in manifest actually do?

The manifest is a configuration file that tells Office how to load and present your add-in. It declares the add-in's unique ID and name, the HTTPS URLs where its web files are hosted, the ribbon buttons and task panes it adds, the permissions and Microsoft Graph scopes it needs, and the API requirement sets it depends on. Office reads the manifest, wires up the UI, and loads your web app.

An Office add-in is a web app plus a manifest. The web app is your HTML, CSS, and JavaScript hosted on a server. The manifest is how Office discovers and presents it. When a user installs the add-in, Office reads the manifest, adds the buttons and panes it describes, and loads your web files into a sandboxed webview. Change the manifest and you change what the user sees; change the web files and you change what the add-in does.

Because the manifest is the contract between your add-in and Office, small errors have outsized effects. A wrong URL means a blank pane. A missing requirement-set declaration means an API call that works on your machine and throws on a colleague's older build. An icon at the wrong size or a non-HTTPS link can fail store validation outright. It is worth treating the manifest as a first-class part of the project, not an afterthought you generate once and forget.

How does the XML add-in-only manifest work?

The XML add-in-only manifest is the format Office add-ins have used for years. It is structured in two notional halves. The base manifest carries the add-in's core identity: its ID, name, description, icons, provider, permissions, and the Hosts and Requirements elements that say which Office apps and API versions it targets. The VersionOverrides section carries the modern UI: the ribbon buttons, menus, and commands, defined through a system of resources and IDs.

One quirk worth knowing is the double-jump for strings. In VersionOverrides, strings and URLs are defined once in a Resources element and given an ID, and the elements that need them reference that ID with a resid attribute. It is more indirection than feels necessary, but it is how localisation and reuse work in the XML format.

The reason the XML manifest still matters in 2026 is reach. It supports the full set of platforms: Windows desktop, Mac, Office on the web, and mobile. For an add-in that needs to run everywhere today, the XML manifest is still the safe default, and for store submission with the add-in-only manifest you target schema version 1.1.

<!-- XML add-in-only manifest (abridged) -->
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
           xsi:type="MailApp">
  <Id>00000000-0000-0000-0000-000000000000</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Orfys Technologies</ProviderName>
  <DisplayName DefaultValue="Sample Add-in" />
  <IconUrl DefaultValue="https://example.com/icon-64.png" />
  <SupportUrl DefaultValue="https://example.com/support" />
  <Hosts><Host Name="Mailbox" /></Hosts>
  <Requirements>
    <Sets><Set Name="Mailbox" MinVersion="1.10" /></Sets>
  </Requirements>
  <!-- VersionOverrides defines ribbon buttons and commands -->
</OfficeApp>

What is the unified JSON manifest, and how is it different?

The unified manifest is a JSON file based on the Microsoft Teams app schema. It lets you describe an Office add-in, a Teams app, and other Microsoft 365 extensions in a single manifest and ship them as one installable unit. It replaces the XML format's two-part structure with top-level base properties plus an extensions property that holds the Office-specific UI.

The unified manifest is where Microsoft is heading. There is just one schema for it, compared with the seven the XML format accumulated, and it shares the Teams app schema, so a single package can contain an Office add-in alongside other Microsoft 365 extensions. The $schema property even gives you IDE validation and IntelliSense as you edit.

Structurally it mirrors the XML split without the ceremony. Over ten top-level properties serve the role of the old base manifest: id, name, description, icons, developer, and so on. A single extensions property serves the role of VersionOverrides, holding the things specific to Office add-ins, including which apps you extend, the ribbon definitions, and the requirement sets. The string double-jump is gone; values are defined directly where they are used. Authorization and Microsoft Graph permissions move into a declarative model rather than the old Permissions element.

The catch is platform support. The unified manifest does not yet run everywhere. Outlook on Windows picked it up from build 16626, and Excel, Word, and PowerPoint on Windows from version 2501, but OneNote and Project do not support it at all, and full cross-platform coverage is still landing. Two more practical limits: Visual Studio does not build unified-manifest add-ins, so that path runs through the Office Yeoman generator or the Microsoft 365 Agents Toolkit, and sideloading a unified-manifest add-in needs Office version 2304 or later.

// Unified manifest extensions block (abridged)
"extensions": [
  {
    "requirements": {
      "scopes": ["mail"],
      "capabilities": [{ "name": "Mailbox", "minVersion": "1.10" }]
    },
    "ribbons": [ /* groups, controls, buttons */ ]
  }
]

XML or unified manifest: which should I use?

Use the XML add-in-only manifest when you need the widest platform coverage today, including Mac, web, mobile, OneNote, or Project. Use the unified manifest when you want to package an add-in with a Teams app or other Microsoft 365 extensions, and your target platforms support it. Many teams ship both and use the alternates property to prefer one per platform.

The decision comes down to reach versus future-fit. If your add-in must run on every platform now, or it targets OneNote or Project, the XML manifest is still the pragmatic choice. If you are building something that benefits from being one package with a Teams app, or you are starting fresh on the supported Windows builds, the unified manifest is the direction of travel and worth adopting.

You are not forced to pick once and forever. To get modern packaging and full coverage at the same time, teams sometimes ship two versions of the same add-in, one with each manifest, and use the unified manifest's alternates property to hide or prefer a version per platform based on requirements. It is more to maintain, but it lets you adopt the new format where it works without abandoning users where it does not.

Migrating an existing XML add-in to the unified format is supported by tooling rather than hand-editing. The office-addin-project convert command, or the office-addin-manifest-converter for projects not made with the Office generator, handles most of the conversion. One thing to check first: if your add-in has custom functions, their JSON metadata is validated strictly under the unified manifest, so function names and ids need at least three characters and each function needs a result definition before conversion will pass.

How do requirement sets work in the manifest?

Requirement sets are how the manifest says which Office APIs the add-in needs. Each set has a version, such as Mailbox 1.10 or ExcelApi 1.x, and a given client supports up to a certain version. If you declare a minimum set that a user's Office build does not meet, the add-in will not be offered for installation on that client at all, which is usually what you want for a hard dependency.

The more interesting use is selective feature gating. In the unified manifest you can require a baseline set at the top of the extensions property, then require a higher set on a specific ribbon button. If a client does not meet the button's requirement, that node is stripped from the manifest before install, so the rest of the add-in still works and only the unsupported feature disappears. The rule is not to declare a less restrictive requirement deeper than a more restrictive one above it, because the add-in could not install there anyway.

Getting requirement sets right is the difference between an add-in that degrades gracefully on an older client and one that throws an error and looks broken. It pairs with a runtime check using isSetSupported for anything above your declared baseline. We cover the API side of this in our field guide to Office.js.

What manifest mistakes fail AppSource validation?

When a submission bounces, the manifest is often the reason. The recurring culprits are boringly avoidable. Localhost URLs are rejected, because the reviewer cannot reach your machine; every endpoint must point to a hosted HTTPS location with valid TLS. Icons must be present and correctly sized. The ID must be unique, except when you are updating an existing add-in, in which case it must stay the same. The manifest must validate against its schema, and for the add-in-only format that means schema version 1.1.

Beyond the manifest file itself, the listing needs valid, live support, privacy, and license URLs that do not return a 404, and the privacy policy must reference the add-in specifically rather than just your website. If the add-in uses single sign-on you must include a fallback flow, and if it has custom functions you must provide test instructions for at least one of them. None of this is hard, but it is the kind of detail that turns a three-to-five-day review into a multi-week back-and-forth. Our AppSource publishing guide walks through the full checklist.

XML add-in-only manifest vs unified manifest (2026)

Frequently asked questions