SDB:KIWI Cookbook RelaxNG Schema

Find out how you can develop and customize the KIWI RELAX NG Schema which is used for validating the XML configuration file.

All of KIWI edit

This procedure was tested on at least Kiwi version 3.25 ( kiwi --version ) - older version did not support all shown features Version

Adding a New Element into the KIWI RELAX NG Schema

In previous examples we have modified the config.xml file to control the image created by Kiwi. As part of the Kiwi execution this XML file is validated against a schema and if you happened to have a typo in your XML file when you made modifications you already encountered the validation process in the form of an error message. The schema governing the config.xml file is implemented in RELAX NG and you can see the latest schema here.

Unlike our previous examples which focused on the use of Kiwi to create an image, this example is more developer focused as it shows how to make modifications to the schema governing the config.xml file.

A note about Kiwi development

The Kiwi project is hosted at berlios.de and the project code is managed in a git repository. You can clone the source tree via anonymous git access from the following url: git://git.berlios.de/kiwi . For more information about git see the git project page.

Overview

RELAX NG is a schema language used to define XML schema. Unlike the DTD (Document Type Definition) or W3C XML Schema implementation for schema definition Relax NG (pronounced relaxing) has the advantage that the definition of the schema may be authored in XML or in a compact syntax. Visit the RELAX NG Home page for information about Relax NG. The KIWI schema is developed in the compact syntax (also known as RNC).

Adding New Elements to The KIWI Schema

It is recommended that you take the following steps prior to making changes to the Kiwi schema:

1. Have a basic understanding of git
2. Basic working knowledge of XML and RELAX NG (check out the tutorials at RELAX NG
3. Consider general applicability and necessity of the element, would an attribute on an existing element suffice?
4. Check with the developer community on the KIWI developers list kiwi-devel at lists.berlios.de

The following steps outline the general procedure to add a new element once you have established that it is necessary.

1. Using your favorite editor edit the compact syntax file (modules/KIWISchema.rnc)
2. Use the template below as your guide and adapt it to the needs of the new element. Try to reuse existing patterns as much as possible.
3. Add your new element as a child to a parent element. Your new element may be a child of the image element or another element.
4. Validate the KIWI schema with the RELAX NG schema. Use Jing to validate it and correct all reported errors:

jing -c relaxng.rng KIWISchema.rnc

1. Modify the KIWI documentation to document the new element.
2. Create a patch and sent it to the KIWI developer list (kiwi-devel at lists.berlios.de)

Structure of a KIWI Element

Each element in the RNC schema contains the following parts:

• A name, beginning with k., k.image for example
  • This name is used as a reference and to collect your element pattern.
• A short RELAX NG annotation
• A DocBook 5 para element for more verbose documentation
• The corresponding element definition

The definition of attributes is similar to the element definition. Attributes do not have a DocBook 5 documentation element.

Naming Convention

The RNC uses a naming convention in an effort to facilitate consistency. In the conventions outlined below, replace the placeholders in italic with the appropriate value for your changes/additions.

• Element pattern: k.ELEMENTNAME
  Contains the complete definition of the given element, including attributes and content model. For example: k.image for the image element.
• Attribute pattern: k.ELEMENTNAME.ATTRNAME.attribute
  Contains an attribute definition for a given element, for example: k.image.name.attribute for the name attribute of the image element.
• Attribute pattern for shared attributes: k.ATTRNAME.attribute
  Used for attributes shared between multiple elements, for example: k.id.attribute for the id attribute.
• Attribute collection: k.ELEMENTNAME.attlist
  Collects all attributes for a given element, for example: k.image.attlist contains all attributes from the image element.
• Content pattern: k.ELEMENTNAME.content
  Contains the supported values and datatypes in this context.

KIWI Element Template

With the preliminaries out of the way lets take a detailed look at the basic template for an element definition in the RNC format. for your own element definition replace foo with the appropriate name. The numbers (x) are not part of the template and are referenced in the detailed explanation below the template.

# ==========================================
# The element <foo>
#
div { # (1)
  # (2)
  k.foo.name.attribute = k.name.attribute

  # (3)
  k.foo.bar.attribute =
    ## The bar attribute does a very important task ...
    attribute bar { text }
  
  # (4)
  k.foo.attlist =
    k.foo.name.attribute
    & k.foo.bar.attribute?

  # (5)
  k.foo = 
    ## A useful foo element
    [
      db:para [ "Insert a more descriptive text, examples, ..." ]
    ]
    element foo 
    { 
      k.foo.attlist, text 
    }
}

# (6)

Detailed template explanation:

1. Wrap each element definition into a div { ... } construct
2. Name your attribute(s) according to the convention above. Use existing attributes whenever possible.
3. Define your own attributes and insert an annotation with ## and the corresponding attribute.
4. Define a collection of all your defined attributes in the .attlist name. If an attribute is optional, flag it with the ? character. As attributes have no order, use the interleave pattern indicated by the & character.
5. Define the element. Add the annotation (##), the documentation (db:para), and the element definition. Depending on the content model (relationships and structure) you may need to define additional elements in a similar way. Do not forget to insert the .attlist name.
6. Integrate the newly defined element into the content model of another element.

Do not forget to update the KIWI documentation with a description of the new element.

Creating the XML Format from the Compact Syntax

The KIWI schema is developed in RNC, but can be converted to the XML syntax using trang:

trang KIWISchema.rnc KIWISchema.rng

The XML syntax format and the compact syntax format are equivalent. The XML format, generated as part of the KIWI build process it may be used for further processing. For example, extracting the documentation to generate an HTML page.

Additional information

In addition to adding new elements to the schema by enhancing KIWI it is possible to customize the schema. This is explained in the KIWI RELAX NG Schema Explained blog.