Structure of a content XSD document

In OpenCms contents are stored as XML files. Thus, the structure of a content of specific type, but also much of its behavior, is specified in an XML schema definition (XSD). Those XSDs themselves must comply with a special structure. In this topic you'll learn about the general structure of such schemas and learn how to create a new schema in OpenCms.

The structure of the XML schema for content types

The structure of content types and much of the type's behavior is specified via XML schema definitions (XSDs). In general, an XSD specifies the structure of an XML document, but it usually also has to comply with a predefined structure. The XSDs that are used to define a content type must comply with such a specific structure.

Here is a very simple example XSD defining a schema for a content type:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

    <!-- Include schema definitions -->	
    <xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>
    <!-- Add includes for nested contents here -->

    <!-- define the multi-language wrapper -->		
    <xsd:element name="SimpleExampleData" type="OpenCmsSimpleExampleData"/>
	
    <xsd:complexType name="OpenCmsSimpleExampleData">
        <xsd:sequence>
            <xsd:element name="SimpleExample" type="OpenCmsSimpleExample" minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
    </xsd:complexType>

    <!-- define the structure of the content for a single language -->
    <xsd:complexType name="OpenCmsSimpleExample">
        <xsd:sequence>
            <xsd:element name="Title" type="OpenCmsString" />
            <!-- add more elements -->
        </xsd:sequence>
        <xsd:attribute name="language" type="OpenCmsLocale" use="required"/>
    </xsd:complexType>

    <!-- configure the content's behavior (optional) -->
    <xsd:annotation>
        <xsd:appinfo>
            <!-- place configuration here -->
            <searchsettings containerPageOnly="true"/>
        </xsd:appinfo>
    </xsd:annotation> 

</xsd:schema>

The schema definition for the content type includes various <xsd:element> and <xsd:complexType> nodes to define the structure of a content. The complex type that defines the structure of the content for one language, we call the schema type. In the above example, the schema type is named "SimpleExample". The structure of the schema type, and thus of the contents, is defined in the node <xsd:complexType name="OpenCmsSimpleExample">. In the example, the content has just one (schema) element, named Title.

The above schema definition has a second section wrapped in xsd:annotation/xsd:appinfo. In this optional section, content specific behavior is specified. In the example, it is configured that the content should not be indexed for searching in its own right, but it can be found in the index via the container pages in which it is placed.

The example highlights the basic structure of a schema definition for a content type. The whole definition is wrapped by the <xsd:schema> node. This node is always the same for each content type definition. The attributes specify the namespace of the schema definition, i.e., which nodes are available and how they can be nested.

Inside the <xsd:schema> node, the content type definition consists of four parts:

Inclusion of other XSDs. Here it is necessary to include the opencms-xmlcontent.xsd, as done in the example. This XSD exposes the definition of types that are predefined in OpenCms, e.g., OpenCmsString in the above example.
Note that the XSD is not a "real" file in the VFS. The include is handled in a special way by OpenCms.
You can include further XSDs here. In particular, you can nest content definitions and make the type of a nested content available via <xsd:include schemaLocation="opencms://root/path/to/the/contentDefintion.xsd"/>
Definition of the multi-language wrapper. Content in OpenCms is by default multi-lingual. Each content item can be saved in multiple languages. All language-specific versions are stored in the same XML file. The multi-language wrapper tells us that the content exists in zero to (potentially) unlimited language-specific versions. The wrapper is mandatory and needs to have exactly the structure presented above.
Definition of the structure of the content for a single language. This part is really specific to your content. In the example, the content has just one element of type OpenCmsString, i.e., an element that stores a string. Read more about the structure part here.
Configuration of the content's behavior. Optionally, the content item's behavior can be configured. E.g., you can configure how content elements should appear in the content editor, map content elements to properties, etc., define default values for elements, say how elements should be indexed for the search, and so on. You can read about the various configuration options here.

Naming conventions for types in the schema

Besides the special XML structure of the schema, the naming of elements and types must also follow some coventions. This is best exemplified in the above example, where the schema type "SimpleType" is defined. In the description below, "SimpleType" can be replaced by any possible name you want give to your schema type. But the prefix and suffix parts are mandatory, as well as using the same schema type name in all the aforementioned places in the schema.

The values of name and type attributes must follow these conventions:

Line 8: <xsd:element name="SimpleExampleData" type="OpenCmsSimpleExampleData"/>
Here the name attribute has to be {schema type}Data and the type attribute OpenCms{schema type}Data.
Line 10: <xsd:complexType name="OpenCmsSimpleExampleData">
Here the name has to be the type attribute from line 8, because you define that type in the <xsd:complexType> node.
Line 12: <xsd:element name="SimpleExample" type="OpenCmsSimpleExample" minOccurs="0" maxOccurs="unbounded" />
Here the name attribute has to be {schema type name} and the type attribute OpenCms{schema type name}. Also minOccurs and maxOccurs must always be given as in the example. Reading the schema from line 10 to 14, you can identify the "multi-language" wrapper: the lines say that we have zero or more (language specific) versions of a content item stored.
Line 17: <xsd:complexType name="OpenCmsSimpleExample">Use OpenCms{schema type name} for the name attribute here. In the node starting at line 17 you begin with the definition of the structure of the content item for one language, i.e., with the definition of the type used for the elements defined in line 12.

Adding a new schema definition

Schema definitions for content types are usually shipped with modules and placed in the module's subfolder named schemas/. If you want to define a content type that should be exposed by a module, i.e., if you want to create content of that type via the "Add wizard" of the page editor, then it is the easiest way to use the Resource types app in the launchpad. This will create a schema definition in the respective folder of your module (and does a lot more). To get the content type you want, just adjust the created example XSD and example formatters.

If you want to add a new schema that should not make up a new content type, then the XSD file can be added via the Explorer. Schemas that do not directly make up a new content type are usually definitions of nested contents. Such schemas are by convention placed in the module's subfolder schemas/nested/. XSDs are just text files (type plain). Click "New" and choose "Text file" in the explorer. Best practice is to copy the content of an existing XSD to your new file and adjust it to your needs.

Examples

Unlike other content management systems, a fresh OpenCms installation does not provide any predefined content type—such as a blog entry or an article—to the content editor unless you provide one with your template.

There is no need though to build all the content types for a website from scratch. Since content types are defined by XSD documents, they can be simply copied from one template into another. OpenCms' default template Mercury, for example, provides a rich set of content types which we will shortly introduce here and which you should consider to reuse.

Mercury's display oriented content types

A typical website project at first needs some display oriented types with which content editors can build up web pages in a free layout and with a free combination of texts, links, images, and other media. Mercury among others provides the following types in this area:

Content section element that can be formatted in many ways to place text, images or a combination thereof everywhere on a page.
Media element for referencing to external media files. e.g., to YouTube videos.
Slider element that allows the content manger to create image slideshows or logo carousels.
Image series element that create gallery like image series with support for zooming individual images.
Link sequence element to simple bullet point lists for navigation and other purposes.
Layout element to realize responsive page layouts.

Mercury's semantic content types

Content types in OpenCms can also be structured data easying the automatic generation of HTML Markup optimized for search engine optimization. Mercury in this area offers the following types inspired by the Schema.org initiative:

Article element that supports tags, all kind of sort options as well as archive display.
Event element including support for recurring events.
Person element.
Organization element.
Point of interest (POI) to describe locations with geo coordinates.
FAQ entry element to build basic lists for FAQs.
Job advertisement element to create job ads.
Meta info element that can be dropped to add SEO meta information for a whole page.

The rest of the data model a website project needs is mostly domain specific, for example, the model of a very specific product or a very specific event type. These types can be defined from scratch with the techniques described in the next chapters.