Skip to content. Skip to navigation

Portal flowmon

Sections
Personal tools
You are here: Home → FlowMon Probe → Development → Configuration → RELAX NG Schema Hints
Document Actions

RELAX NG Schema Hints

by Ladislav Lhotka — last modified 2007-10-22 15:46

Hints are special attributes that are attached to elements of an XML schema written in the RELAX NG language. They provide additional information about the underlying data model and semantics.

Our XML configuration data models are specified using the RELAX NG schema language. A RELAX NG schema is able to capture the hierarchical structure of the data and to some extent also the type of configuration parameters and ranges of their possible values. Applications such as configuration frontends that use XML documents based on these schemas typically need more semantic or formatting information in order to be able to interact effectively with the user, detect configuration errors etc.

Part of this information is necessarily specific to a particular application or user interface (e.g., web form) and should be provided to the application separately, using whatever means appropriate for the application. However, some information is generic and should be observed by all applications. We decided to exploit the extensibility of RELAX NG and bundle such generic information as "hints" - attributes attached to the RELAX NG elements.

An example schema that uses these hints can be found here.

Namespace

The hint attributes are defined in the following namespace:

http://www.liberouter.org/ns/netopeer/hints/1.0

The schema that uses the hints should thus define a prefix for this namespace, typically in the grammar element, such as the h prefix in the following example:

<grammar ns="..."
  xmlns="http://relaxng.org/ns/structure/1.0"
  xmlns:h="http://www.liberouter.org/ns/netopeer/hints/1.0"
  datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">

In the following, we assume such a prefix definition and attach the h prefix to the attribute names.

Hints

The following hints are currently defined:

  • The h:role attribute specifies the role of the parent element. The following two choices are currently available:

    wrapper

    In cases where multiple instances of the same element are allowed, an extra wrapper element marked with the hint attribute h:role="wrapper" is used.

    key

    Each definition of an element that can appear in multiple instances must have exactly one child marked as key by means of the attribute value h:role="key". This key uniquely identifies the parent element. If necessary, two or more child elements can be selected as the key by enclosing these subelements in the group RELAX NG element with the h:role attribute set to key.

  • Hint attribute h:display contains the public name of the parent element that should be presented to the user, e.g., in configuration frontends. The public name of an element that does not have this attribute is by default formed by the "lower camel" words in its element name separated by spaces with the first word capitalised and the following words all lowercase.

  • Hint attribute h:join of a group element containing two or more element definitions instructs the frontends to render the values of the subelements as one string where the values of individual subelements are separated by the string value of the h:join attribute. For example, IP prefix could be rendered as 192.168.1.1/24 even though the IP address and prefix length are stored separately in two elements.

  • Attribute h:status indicates the status of the parent element or pattern. Value advanced means that the corresponding configuration parameter should be acessible only through interfaces intended for advanced users. Value experimental means that the corresponding feature is experimental.

  • Certain elements are marked with the "h:hide="true" attribute indicating that the element should not be displayed by front-ends.