QDML Schema

QDML Schema

A QDML schema describes the various elements and attributes of an XML markup language.

When developing an application using Quick, the first step is to write a QDML schema. The second step is to convert that schema into a QJML binding schema, which binds the XML elements and attributes of an XML markup language to various Java classes.

The utility DTD2QDML can be used to convert a DTD file into a QDML file. Note that this tool will generate warnings when it encounters mixed mode elements or ANY, since these constructs do not convert cleanly into QDML.

The utility QDML2QJML should be used to convert a QDML file into a QJML file, but you should edit the output, replacing the generated names with names of your choosing.

Each QDML element is described as follows:

DTD Fragment Defining the QDML Element
QDML Fragment Defining the QDML Element
Brief Description of the QDML Element
Sample XML
Example QDML for the Sample XML
Brief Explaination of the use of the Example
Attributes of the QDML Element
Content Model

The following color scheme is used:

red identifies the QDML elements being defined;
green identifies the QDML attributes being defined; and
purple identifies the portion of an example being covered.

QDML has 8 elements:

qdml wraps QDML documents;
element defines an element;
attribute defines an attribute;
rem is a comment;
value is used to enumerate attribute values;
child, selection, and sequence define the content model of an element.


ELEMENT: qdml


DTD:

<!ELEMENT qdml (element+)>
<!ATTLIST qdml
    root CDATA #IMPLIED>

QDML:

<element name="qdml">
    <attribute name="root"/>
    <child element="element" repeating="True"/>
</element>

The qdml element is the root element of every QDML schema. It serves the purpose of providing the single root element that is required of a well-formed XML document, as well as identifying the document as a QDML schema.

Sample XML

<timesheet name="Bill la Forge">
    <day date="19990913">
        <entry hours="8" project="quite"/>
    </day>
    <day date="19990914">
        <entry hours="6" project="quite"/>
        <entry hours="2" project="admin"/>
    </day>
    <day date="19990915">
        <entry hours="8" project="quite"/>
    </day>
    <day date="19990916">
        <entry hours="8" project="vacation"/>
    </day>
    <day date="19990917">
        <entry hours="8" project="quite"/>
    </day>
</timesheet>

QDML

<qdml root="timesheet">
.
. <!--timesheet elements-->
.
</qdml>

This is an example of a fragment of a QDML schema. In this example, we are defining a markup language, timesheet, which has a root element of timesheet.

Attributes

A qdml element has an optional attribute, root. This attribute identifies the outermost element of the markup language being defined by the QDML schema.

Content Model

Every qdml element must contain one or more element elements. These subordinate elements specify the various elements that comprise the markup language being defined by the QDML schema.


ELEMENT: element


DTD:

<!ELEMENT element (rem*, attribute*,
                   (child|selection|sequence)*)>
<!ATTLIST element
    name CDATA #REQUIRED
    wild CDATA "False"
    content (PCDATA,BIMODAL,EMPTY)>

QDML:

<element name="element">
    <attribute name="name" status="REQUIRED"/>
    <attribute name="wild" value="False"/>
    <attribute name="content">
        <value>PCDATA</value>
        <value>BIMODAL</value>
        <value>EMPTY</value>
    </attribute>
    <child element="rem" 
           optional="True" repeating="True"/>
    <child element="attribute" 
           optional="True" repeating="True"/>
    <selection optional="True" repeating="True">
        <child element="child"/>
        <child element="selection"/>
        <child element="sequence"/>
   </selection>
</element>

The element element is used to specify an element within the markup language being defined by the QDML schema.

Sample XML

<timesheet name="Bill la Forge">
    <day date="19990913">
        <entry hours="8" project="quite"/>
    </day>
    <day date="19990914">
        <entry hours="6" project="quite"/>
        <entry hours="2" project="admin"/>
    </day>
    <day date="19990915">
        <entry hours="8" project="quite"/>
    </day>
    <day date="19990916">
        <entry hours="8" project="vacation"/>
    </day>
    <day date="19990917">
        <entry hours="8" project="quite"/>
    </day>
</timesheet>

QDML

<qdml root="timesheet">

    <element name="timesheet">
    .
    . <!--attribute, child, selection, and sequence elements-->
    .
    </element">

    <element name="day">
    .
    . <!--attribute, child, selection, and sequence elements-->
    .
    </element">

    <element name="entry" content="EMPTY">
    .
    . <!--attribute elements-->
    .
    </element">

</qdml>

In this fragment of the QDML schema for the timesheet markup language, we have now specified that the markup language has three elements: timesheet, day, and entry.

The assignment of EMPTY to the content attribute on the specification of the entry element indicates that this element will contain neither text nor elements.

Attributes

An element element has the following attributes:

name

The name attribute is used to identify the element being defined.

This attribute is required.

wild

The wild attribute is used when processing opaque data, where the names of the elements being processed are unknown.

This attribute defaults to "False".

content

In XML, the content of an element can be text (PCDATA), one or more elements, or a mix of text and elements (MIXED). An element can also have no content (EMPTY).

Quick does not support mixed content, but it does allow elements to contain either text or elements (BIMODAL). (BIMODAL is not part of standard XML terminology.)

The content attribute is used to specify the type of content held by an element.

This is an optional attribute. The values allowed are PCDATA, BIMODAL, and EMPTY.

Content Model

An element element contains the following elements:

rem

The rem elements are comments which describe the element being defined.

The rem elements are optional and repeating. (Any number of rems are allowed.) Each rem contains a single line of text.
attribute

The attribute elements are used to specify the attributes of the element being defined.

The attribute elements are optional and repeating. (Any number of attributes are allowed.) The order of the attribute elements is not significant, since attributes can appear in any order.

Quick does not support attributes on elements specified with a content of PCDATA. (Use BIMODAL instead of PCDATA if you need to use attributes with text content.)
child, selection, and sequence

The child, selection, and sequence elements are used to specify the content model of the element being defined.

These elements are optional, repeatable, and can occur in any order. Their order is significant, since the content model determines the allowable order of the elements held by the element being defined.

If the element being defined has a content of PCDATA or EMPTY, then none of these elements may occur.

And if the element being defined has no content attribute specified, then at lease one of these elements must be present.


ELEMENT: attribute


DTD:

<!ELEMENT attribute (rem*,value*)>
<!ATTLIST attribute
    name CDATA #REQUIRED
    type (id,idref) #IMPLIED
    status (REQUIRED,FIXED) #IMPLIED
    value CDATA #IMPLIED>

QDML:

<element name="attribute">
    <attribute name="name" status="REQUIRED"/>
    <attribute name="type" field="type">
        <value>id</value>
        <value>idref</value>
    </attribute>
    <attribute name="status">
        <value>REQUIRED</value>
        <value>FIXED</value>
    </attribute>
    <attribute name="value"/>
    <child element="rem" 
           optional="True" repeating="True"/>
    <child element="value" 
           optional="True" repeating="True"/>
</element>

The attribute element is used to specify the attributes of an element.

Sample XML

<timesheet name="Bill la Forge">
    <day date="19990913">
        <entry hours="8" project="quite"/>
    </day>
    <day date="19990914">
        <entry hours="6" project="quite"/>
        <entry hours="2" project="admin"/>
    </day>
    <day date="19990915">
        <entry hours="8" project="quite"/>
    </day>
    <day date="19990916">
        <entry hours="8" project="vacation"/>
    </day>
    <day date="19990917">
        <entry hours="8" project="quite"/>
    </day>
</timesheet>

QDML

<qdml root="timesheet">

    <element name="timesheet">
        <attribute name="name" status="REQUIRED"/>
    .
    . <!--child, selection, and sequence elements-->
    .
    </element">

    <element name="day">
        <attribute name="date" status="REQUIRED"/>
    .
    . <!--child, selection, and sequence elements-->
    .
    </element">

    <element name="entry"
             content="EMPTY">
        <attribute name="hours" status="REQUIRED"/>
        <attribute name="project" status="REQUIRED"/>
    </element">

</qdml>

This QDML fragment specifies the attributes used in the timesheet markup language:

The timesheet element has a name attribute, which must be present on all timesheet elements.
The day element has a date attribute, which must be present on all day elements.
The entry element has a date attribute, which must be present on all entry elements.
The entry element also has a project attribute, which must be present on all entry elements.

Attributes

An attribute element has the following attributes:

name

The name attribute is used to identify the attribute being defined.

There is one special case, when name has an assigned value of #ANY. In this case, the attribute being defined will match to attributes without reference to the attribute name.

This attribute is required.

type

The type attribute is used to specify that the attribute being defined is an id or idref:

An id attribute is used to assign an identifier to an element in a document. The value assigned to an element's id attribute is the identifier for that element. Within the context of a document, id values must be unique.

An idref attribute is used to reference another element in the same document. The value assigned to an idref attribute is the identifier of the element being referenced.

This is an optional attribute. The values allowed are id and type.

status

The status attribute is used to specify that the attribute being defined must be present:

A status of REQUIRED indicates that the attribute being defined must always be present. (By default, attributes are optional.)

A status of FIXED indicates that the attribute being defined has a fixed value that can not be changed, though the attribute is not required to be present.

This is an optional attribute. The values allowed are REQUIRED and FIXED.

value

The value attribute is used to supply the default value of an attribute.

This attribute is required when the status of the attribute being defined is FIXED.

This attribute must not be present when the status of the attribute being defined is REQUIRED.

Content Model

An attribute element may contain rem and value elements. The rem elements are comments which describe the attribute. The value elements enumerate the legal values that may be assigned to the attribute being defined.

Both rem and value elements are optional, and there may be more than one.


ELEMENT: rem


DTD:

<!ELEMENT rem (#PCDATA)>

QDML:

<element name="rem" content="PCDATA"/>

The rem element is used to describe an element or attribute.

Sample QDML

<attribute name="color">
    <rem>The only colors supporte are blue and yellow</rem>
</attribute>

In this QDML fragment, the color attribute is specified as optional (not REQUIRED), with only three acceptable values: red, blue, and yellow.

Attributes: none

Content Model

A rem element contains a single line of text. It contains no elements.


ELEMENT: value


DTD:

<!ELEMENT value (#PCDATA)>

QDML:

<element name="value" content="PCDATA"/>

The value element enumerates through the legal values of an attribute.

Sample XML

<ball color="red"/>

QDML

<attribute name="color">
    <value>red</value>
    <value>blue</value>
    <value>yellow</value>
</attribute>

In this QDML fragment, the color attribute is specified as optional (not REQUIRED), with only three acceptable values: red, blue, and yellow.

Attributes: none

Content Model

A value element contains text. It contains no elements.


ELEMENT: child


DTD:

<!ELEMENT child EMPTY>
<!ATTLIST child
    element CDATA #REQUIRED
    optional CDATA "False"
    repeating CDATA "False">

QDML:

<element name="child" content="EMPTY";>
    <attribute name="element" status="REQUIRED"/>
    <attribute name="optional" value="False"/>
    <attribute name="repeating" value="False"/>
</element>

A child element is used to specify an element that is contained within the content model of another element.

Sample XML

<timesheet name="Bill la Forge">
    <day date="19990913">
        <entry hours="8" project="quite"/>
    </day>
    <day date="19990914">
        <entry hours="6" project="quite"/>
        <entry hours="2" project="admin"/>
    </day>
    <day date="19990915">
        <entry hours="8" project="quite"/>
    </day>
    <day date="19990916">
        <entry hours="8" project="vacation"/>
    </day>
    <day date="19990917">
        <entry hours="8" project="quite"/>
    </day>
</timesheet>

QDML

<qdml root="timesheet">

    <element name="timesheet">
        <attribute name="name"
                   status="REQUIRED"/>
        <child element="day"
               repeating="True"/>
    </element">

    <element name="day">
        <attribute name="date"
                   status="REQUIRED"/>
        <child element="entry"
               repeating="True"/>
    </element">

    <element name="entry"
             content="EMPTY">
        <attribute name="hours"
                   status="REQUIRED"/>
        <attribute name="project"
                   status="REQUIRED"/>
    </element">

</qdml>

Here we have the complete QDML schema for the timesheet markup language. We have added the content model specification for the timesheet and day elements:

Each timesheet element must contain one or more day elements.
Each day element must contain one or more entry elements.

Attributes

element

The element attribute provides the name of the element being included in the content model of another element.

This attribute is required.

optional and repeating

The optional and repeating attributes are used to control the number of allowed occurances of an element within the content model:

optional repeating Number of Occurances

True True Zero or more

False False Exactly one

True False No more than one

False True One or more

These attributes both default to False when not present.

Content Model: EMPTY


ELEMENT: selection


DTD:

<!ELEMENT selection ((child|selection|sequence)+)>
<!ATTLIST selection
    optional CDATA "False"
    repeating CDATA "False">

QDML:

<element name="selection">
    <attribute name="optional" value="False"/>
    <attribute name="repeating" value="False"/>
    <selection repeating="True">
        <child element="child"/>
        <child element="selection"/>
        <child element="sequence"/>
   </selection>
</element>

The selection element is used to introduce alternatives into a content model.

Sample XML

    <automobile>
        <standardTransmission/>
    </automobile>

QDML

    <element name="automobile">
        <selection>
            <child element="standardTransmission"/>
            <child element="automaticTransmission"/>
        </selection>
    </element">

Here we see a QDML fragment which specifies that an automobile element must contain either a standardTransmission element or an automaticTransmission element.

Attributes

The optional and repeating attributes are used to control the number of allowed occurances of the alternatives specified by the child and sequence elements contained in the selection element:

optional repeating Number of Occurances

True True Zero or more

False False Exactly one

True False No more than one

False True One or more

These attributes both default to False when not present.

Content Model

The child, selection, and sequence elements are used to specify alternative content models.

These elements are optional, repeatable, and can occur in any order, so long as there is at least one element present in the selection element's content.


ELEMENT: sequence


DTD:

<!ELEMENT sequence ((child|selection|sequence)+)>
<!ATTLIST sequence
    optional CDATA "False"
    repeating CDATA "False">

QDML:

<element name="sequence">
    <attribute name="optional" value="False"/>
    <attribute name="repeating" value="False"/>
    <selection repeating="True">
        <child element="child"/>
        <child element="selection"/>
        <child element="sequence"/>
   </selection>
</element>

The sequence element lets us define sequences in the content model.

Sample XML

<map name="Bill la Forge">
    <key>Fred Smith</key>
    <ssn>101-33-9320</ssn>
    <key>John Spade</key>
    <ssn>221-56-7890</ssn>
    <key>Big Little, Inc.</key>
    <cid>04-98789234</cid>
</map>

QDML

<qdml root="map">

    <element name="map">
        <sequence optional="True"
                  repeating="True">
            <child element="key"/>
            <selection>
                <child element="ssn"/>
                <child element="opaque"/>
            </selection>
        </sequence>
    </element>

    <element name="key"
             content="PCDATA"/>

    <element name="ssn"
             content="PCDATA"/>

    <element name="opaque"
             wild="True">
             content="BIMODAL">
        <attribute name="#ANY"/>
        <child element="opaque"
               optional="True" 
               repeating="True"/>
    </element>

</qdml>

Here we see the QDML schema for a MAP markup language. The content of the map element is specified as a repeating sequence of key/value pairs, where the value is either a ssn element or some undefined element.

Attributes

The optional and repeating attributes are used to control the number of allowed occurances of the sequence specified by the child, selection, and sequence elements contained in the sequence element:

optional repeating Number of Occurances

True True Zero or more

False False Exactly one

True False No more than one

False True One or more

These attributes both default to False when not present.

Content Model

The child, selection, and sequence elements are used to specify alternative content models.

These elements are optional, repeatable, and can occur in any order, so long as there is at least one child, selection, or sequence element present in the sequence element content.

optional	repeating	Number of Occurances
True	True	Zero or more
False	False	Exactly one
True	False	No more than one
False	True	One or more