Magento Stack Exchange is a question and answer site for users of the Magento e-Commerce platform. It's 100% free, no registration required.

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

In Magento 2, some layout handle XML files open with the


root tag. Others open with the


root tag. Does using either of the above tags introduce any functionality differences to a layout handle XML file? Or is this pure window dressing? Or something in between.

Two examples

<!-- File: vendor/magento/module-weee/view/frontend/layout/default.xml -->
<page xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">


<!-- File: vendor/magento/module-widget/view/adminhtml/layout/adminhtml_widget_loadoptions.xml -->
<layout xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/layout_generic.xsd">
share|improve this question
up vote 11 down vote accepted

These matters due to a different XSD configurations. The <layout xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/layout_generic.xsd"> declaration says that we want to use layout with XSD definition provided in the lib/internal/Magento/Framework/View/Layout/etc/layout_generic.xsd

In the layout_generic.xsd file it provides definition for layout node with genericLayout element type.

<xs:complexType name="genericLayout">
    <xs:sequence minOccurs="0" maxOccurs="unbounded">
        <xs:element ref="referenceContainer" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="container" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="block" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="referenceBlock" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="update" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="move" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="uiComponent" minOccurs="0" maxOccurs="unbounded"/>

Having that, the layout file has been validated by the XSD when xml is loaded. In addition to this it highlights all possible nodes and node attributes in the layout.xml file.

Same with page_configuration.xsd definition for <page /> node. This XSD describes nodes which can be used to describe page.

Hope it helps.

share|improve this answer
hat helps some, +1 for that, but it's still not clear why the difference exists. Is layout just unconverted legacy? Or does the distinction exists for a good reason. – Alan Storm Jan 16 at 0:36
It exists for a reason. Just imagine flexibility when instead of creating phtml or html file and if you need some modification to existing file you have to copy it, you have declarative way of defining a page. With it's html, body and head elements. Layout - it is just another, different layer of configuration, where you opera with pieces of content such as block, component, container etc. – Max Pronko Jan 16 at 0:42
Not sure I see the distinction -- can't the inner nodes of a <layout/> file be included in a <page/> <body/> for the same effect? Or am I missing something? – Alan Storm Jan 16 at 1:23
Consider this approach as a separation of concerns. Including many other places where Magento 2 split classes, configuration, layouts etc. – Max Pronko Jan 16 at 11:04

Layout files which open with <layout></layout> are page layouts that declare the wireframe of a page inside the <body> section, for example one-column layout or two-column layout.

The layout files which open with <page></page> are page configuration files that add content to the wireframe defined in a page layout file.

Here is the official doc about it, please let us know if it can be improved:

share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.