In an Office add-in manifest, why must <Permissions> immediately follow <FormSettings/>?

Question

This issue is best demonstrated by example. Consider the following:

In the first example, my <Permissions/> element is placed immediately after the <FormSettings/> block:

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:mailappor="http://schemas.microsoft.com/office/mailappversionoverrides/1.0" xsi:type="MailApp">
  <Id>464672b2-35a8-44a1-8c06-3ad07ed893a7</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Example</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Example A"/>
  <Description DefaultValue="This is an example add-in."/>
  <IconUrl DefaultValue="https://placehold.it/64x64"/>
  <HighResolutionIconUrl DefaultValue="https://placehold.it/64x64"/>
  <SupportUrl DefaultValue="https://example.com/"/>
  <Hosts>
    <Host Name="Mailbox"/>
  </Hosts>
  <Requirements>
    <Sets>
      <Set Name="MailBox" MinVersion="1.1"/>
    </Sets>
  </Requirements>
  <FormSettings>
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <SourceLocation DefaultValue="https://example.com"/>
      </DesktopSettings>
    </Form>
  </FormSettings>
  <Permissions>ReadWriteMailbox</Permissions>
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
  </Rule>
</OfficeApp>

I am able to successfully add this manifest to my Exchange Admin Center's organization add-ins list.

However, if I move the <Permissions/> element anywhere else in the manifest, the manifest fails validation when attempting to add it:

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:mailappor="http://schemas.microsoft.com/office/mailappversionoverrides/1.0" xsi:type="MailApp">
  <Id>464672b2-35a8-44a1-8c06-3ad07ed893a7</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Example</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Example A"/>
  <Description DefaultValue="This is an example add-in."/>
  <IconUrl DefaultValue="https://placehold.it/64x64"/>
  <HighResolutionIconUrl DefaultValue="https://placehold.it/64x64"/>
  <SupportUrl DefaultValue="https://example.com/"/>
  <Hosts>
    <Host Name="Mailbox"/>
  </Hosts>
  <Requirements>
    <Sets>
      <Set Name="MailBox" MinVersion="1.1"/>
    </Sets>
  </Requirements>
  <FormSettings>
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <SourceLocation DefaultValue="https://example.com"/>
      </DesktopSettings>
    </Form>
  </FormSettings>
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
  </Rule>
  <Permissions>ReadWriteMailbox</Permissions>
</OfficeApp>

Attempting to add this manifest to my Exchange Admin Center's organization add-ins list produces the following error:

This app can't be installed. The manifest file doesn't conform to the schema definition. The element 'OfficeApp' in namespace 'http://schemas.microsoft.com/office/appforoffice/1.1' has invalid child element 'Permissions' in namespace 'http://schemas.microsoft.com/office/appforoffice/1.1'. List of possible elements expected: 'DisableEntityHighlighting' in namespace 'http://schemas.microsoft.com/office/appforoffice/1.1' as well as 'VersionOverrides' in namespace 'http://schemas.microsoft.com/office/mailappversionoverrides' as well as any element in namespace 'http://www.w3.org/2000/09/xmldsig#'...

It is only through trial and error were we able to find the root cause of this validation failure.

My question: Why does ordering matter? Why can the <Permissions/> element not appear anywhere within the same nesting level in the manifest?

Context

This validation failure occurs in hosted Exchange (Office 365), and also when attempting to submit an add-in to the Office Store, at the step where a manifest is requested.

Answer 1

Order of the tags defined by schema file. Unfortunately this is not well documented and we are working to improve this documentation. Order matters when defining a manifest for Outlook web add-ins because of the way we validate the schema for installation. We realize this can be a hassle especially since it's not well documented but the main reason we require a specific order is because it allows us to validate the manifest content quickly and increase performance of the service.

Thank you for providing this feedback on our documentation.

Answer 2

Why does ordering matter?

Order of the tags defined by schema file. In your case you have included in the manifest http://schemas.microsoft.com/office/appforoffice/1.1 Schema. Try to find in the schema <Permissions/> element and you will see the following definition ...

<xs:complexType name="MailApp">
 <xs:complexContent>
   <xs:extension base="OfficeApp">
     <xs:sequence>
       <xs:element name="Requirements" type="MailAppRequirements" minOccurs="1" maxOccurs="1"/>
       <xs:element name="FormSettings" type="FormSettings" minOccurs="1" maxOccurs="1"/>
       <xs:element name="Permissions" minOccurs="0" maxOccurs="1" type="ST_Permissions2"/>
       <xs:element name="Rule" type="Rule" minOccurs="1" maxOccurs="1"/>
       <xs:element name="DisableEntityHighlighting" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
       <xs:element ref="mailor:VersionOverrides" minOccurs="0" maxOccurs="1"/>
       <xs:any id="MailAppSignature" minOccurs="0" maxOccurs="1" namespace="http://www.w3.org/2000/09/xmldsig#" processContents="lax"/>
     </xs:sequence>
   </xs:extension>
 </xs:complexContent>

Element <Permissions/> is in the <sequence/> which means it must be in order defined by this element and it's right after <FormSettings/> and nowhere elese.