Defining the schema of a content type

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 to such a specific structure.

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

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 a search as its own, but it can be found in the index via the container pages where it is placed on.

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 ar 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 can be saved in multiple languages. All language-specific versions are stored in the same XML file. The multi-language wrapper tells 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 contents 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, tell how elements should be indexed for the search, .... You can read about the various configuration options here.

Besides the special XML structure of the schema definition that is required for schemas that are used for content types, also the naming of elements and types has to comply to a certain scheme. It is best explained at 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 pre- and suffix parts are mandatory, as well as using the same schema type name at all the mentioned places in the schema.

The values of name and type attributes have to comply to the special name scheme at:

• 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 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 defintion of the content's structure for one language, i.e., with the definition of the type used for the elements defined in line 12.

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 contents 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 dp 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.