Search the documentation
 Show GitHub edit links  Hide GitHub edit links
Documented since: 9.5 Latest revision for: 9.5 Valid for OpenCms: 10.5.2

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="SimpleExamples" type="OpenCmsSimpleExamples"/>
	
    <xsd:complexType name="OpenCmsSimpleExamples">
        <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:

  1. 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"/>
  2. 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.
  3. 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.
  4. 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 definition that is required for schemas that are used for content types, 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="SimpleExamples" type="OpenCmsSimpleExamples"/>
    Here the name attribute has to be {schema type}s and the type attribute OpenCms{schema type}s.
  • Line 10: <xsd:complexType name="OpenCmsSimpleExamples">
    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.

How to add 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, than it is the easiest way to use the "Add resource type" function from the administration's "Module management". 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.

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 traditional workplace's 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.

The schema type name should be unique in your OpenCms installation. So please rename types when adjusting a copied schema to make up a new one.
Type and name attributes in schema definitions for content types must follow some naming conventions as described here.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.