2.4 Attribute Declarations

2.4.1 Overview

Attribute declarations are made with AttDef elements nested inside of AttGroup container elements. AttGroup elements may be nested inside of ElementDecl element declarations or XSchema elements. The type of an attribute is defined with an attribute, as is a declaration of whether or not it is required and a possible default value. Values for enumerated types are provided with subelements.

<!ELEMENT AttGroup (Doc?, More?, AttDef*)>
<!ATTLIST AttGroup
    Name NMTOKEN #IMPLIED
    Element NMTOKEN #IMPLIED
    id ID #IMPLIED
    prefix NMTOKEN #IMPLIED
    ns CDATA #IMPLIED>

<!ELEMENT AttDef (Doc?, More?, EnumerationValue*)>
<!ATTLIST AttDef
    Name NMTOKEN #REQUIRED
    Type (CData |
    ID |
    IDRef |
    IDRefs |
    Entity |
    Entities |
    Nmtoken |
    Nmtokens |
    Notation |
    Enumerated) "CData"
    Required (Yes | No) "No"
    AttValue CDATA #IMPLIED>
<!ELEMENT EnumerationValue (Doc?, More?)>
<!ATTLIST EnumerationValue
    Value CDATA #REQUIRED>

In XSchema 1.0, attribute declarations (AttDef elements inside of an AttGroup element) may be nested within the element declaration (ElementDecl element) for the element to which the attribute belongs, or outside of that structure in an XSchema element. If the AttGroup element appears nested inside an ElementDecl element, the Element attribute must be ignored. Similarly, if an AttDef element appears nested inside an AttGroup element, its Element attribute must be ignored in favor of that of the AttGroup. If an AttGroup or AttDef element appears nested under the XSchema element, the Element attribute may contain a name token corresponding to the Name attribute of the element to which this attribute applies. If the Element attribute is missing, that AttDef or AttGroup declaration may only be used by reference.

AttGroup elements are container elements. All of their attributes, except for id, apply to the child AttDef elements and may be overridden by the attributes of those child elements. The Name attribute of the AttGroup element is provided for convenient reference within the XSchema. This attribute should be ignored in conversions to DTDs.

The Name attribute of the AttDef element provides the name by which the attribute will be identified. Attribute names must be unique within the element in which they are declared. A nested declaration is shown below.

<ElementDecl Name="Species">
  ...additionalElementInformation...
  <AttGroup>
    <AttDef Name="status" ...additionalAttributeInformation.../>
  </AttGroup>
</ElementDecl>

This declares an element with the name Species that has an attribute named status. If the status attribute was declared outside of the Species element declaration, the declarations would appear as shown below.

<ElementDecl Name="Species">
    ...additionalElementInformation...
</ElementDecl>
...
<AttDef Name="status" Element="Species" ...additionalAttributeInformation.../>

Merely naming an attribute may be adequate. Attribute declarations may identify types and provide information about whether the attribute is required. By default, attributes will be assumed to contain character data (CData), not be required, and have no default value. This information is declared using additional attributes. The simplest attribute declaration possible identifies an attribute as containing character data (CData) and allows the attribute to be optional, as shown below.

<AttDef Name="sampleAttribute"/>

Applications may also use the id attribute to provide unique identifiers for attribute declarations using values that are unique within the XSchema.

The prefix attribute identifies the prefix that will be applied to this attribute during conversion to DTDs. The ns attribute identifies the URI which functions as the namespace name for this attributes. Namespace processing is covered further in Section 3.0, "XSchema and Namespaces".

2.4.2 Attribute Types

XSchema 1.0 provides equivalents for all of the XML 1.0 DTD attribute types. All of them are declared using attribute values within the AttDef element.

The CData attribute type is one of the most common, permitting an attribute to contain character data as defined by the XML 1.0 specification. If the Species element were to contain an attribute providing the Latin name of the species, the declaration could look like the following. (The Type attribute could actually be omitted in this case, as CData is the default type.)

<ElementDecl Name="Species">
...additionalElementInformation...
    <AttGroup>
        <AttDef name="Latin" Type="CData"/>
    </AttGroup>
</ElementDecl>

This attribute would then be available for use in instances of the Species element:

<Species Latin="Passerina cyanea">...additionalContent...</Species>

The ID attribute type is used to uniquely identify elements in a document for application processing. IDRef and IDRefs attribute types are used to refer to a single ID value in the same document or multiple ID values in the same document, separated by whitespace, respectively. These attribute declarations must be used with the same constraints as apply to ID, IDREF, and IDREFS attribute types in XML 1.0.

The Entity and Entities attribute types identify the names of unparsed entities. The use of these attribute types must be made with the same constraints as apply to the ENTITY and ENTITIES attribute types in XML 1.0. If a document is checked directly against an XSchema without a conversion to a DTD, information regarding unparsed entities must be available from the parser for these attribute types to be meaningful.

The Nmtoken and Nmtokens attribute types are used to declare attributes that must contain information conforming to the Nmtoken and Nmtokens productions in XML 1.0.

The Notation and Enumerated attribute types are more complex, requiring Enumeration subelements to identify their possible content. These two declarations use similar syntax, but the allowed values of Notation declarations must match the Notations declared elsewhere in the XSchema document.

If the status attribute of the Species element were to allow the values of extinct, endangered, protected, and non-threatened, an appropriate enumerated type declaration would look like:

<ElementDecl Name="Species">
...additionalElementInformation...
    <AttGroup>
        <AttDef Name="status" Type="Enumerated">
            <EnumerationValue Value="extinct"/>
            <EnumerationValue Value="endangered"/>
            <EnumerationValue Value="protected"/>
            <EnumerationValue Value="non-threatened"/>
        </AttDef>
    </AttGroup>
</ElementDecl>

A Species element created conforming to this declaration might look like:

<Species status="extinct">...additionalContentAboutDodos...</Species>

2.4.3 Attribute Defaults

XSchema requires attribute declarations to provide information about the default value of a given attribute. XSchema provides for the four cases supported by XML 1.0: #REQUIRED, #IMPLIED, #FIXED AttValue, and AttValue, though they are expressed as choices between required and not required with an optional default value. There may be only one default value declaration per attribute.

Required attributes (identified in XML 1.0 by #REQUIRED) are identified by assigning the value "Yes" to the Required attribute of an AttDef element. For instance, if the Latin attribute described above was required by the Species element, the AttDef element would contain a Required attribute with a value of "Yes":

<ElementDecl Name="Species">
...additionalElementInformation...
    <AttGroup>
        <AttDef name="Latin" Required="Yes"/>
    </AttGroup>
</ElementDecl>

Optional attributes (identified in XML 1.0 by #IMPLIED) are identified assigning the value "No" to the Required attribute of an AttDef element and not assigning a value to the AttValue attribute. Implied indicates that there is no default value provided, and also that no value is required. If the Latin attribute is optional, the AttDef element would contain a "No" value for the Required attribute. (Note that this is the default status and the Required declaration does not need to be made explicitly.)

<ElementDecl Name="Species">
...additionalElementInformation...
    <AttGroup>
        <AttDef name="Latin" Required="No"/>
    </AttGroup>
</ElementDecl>

Fixed attributes (identified in XML 1.0 by #FIXED AttValue) are identified through the use of the Required attribute in combination with the AttValue attribute, which must contain the fixed value for the attribute. Attributes declared using fixed value cannot declare a different value for that attribute. Fixed effectively hard codes attribute values into particular elements. If the Required attribute has a value of "Yes", and the AttValue attribute is present, the attribute value should be treated as a #FIXED value in XML 1.0.

For example, to declare a planet attribute for the Species element, a Required attribute given the value of "Yes" would identify the fixed nature of the attribute and the AttValue attribute would provide the value.

<ElementDecl Name="Species">
...additionalElementInformation...
    <AttGroup>
        <AttDef Name="planet" Required="Yes" AttValue="Earth"/>
    </AttGroup>
</ElementDecl>

Attributes may also be provided with a default value that may be overridden by other declarations. These default values are identified through the use of the AttValue attribute. The status attribute of species elements described above would be an appropriate target for such a default value, especially if most species being described fell into a particular category:

<ElementDecl Name="Species">
...additionalElementInformation...
    <AttGroup>
        <AttDef Name="status" Type="Enumerated" Enumeration="extinct endangered protected non-threatened" AttValue="non-threatened"/>
    </AttGroup>
</ElementDecl>

Any default (required, fixed, etc.) may be used with any attribute type, though default values should always correspond to acceptable values for the attribute type.

2.4.4 Combinations of Types, Defaults, and Default Values

This notation also permits the declaration of certain attributes (IDs with defaults, for instance) that are prohibited by the standard XML 1.0 DTD syntax. Developers who use these combinations should test that their documents will behave as expected in DTD-only environments as well as XSchema environments. Additional processing of document instances may be necessary to produce normalized-for-DTD use documents if they included such attributes as default values. The attribute type should always be considered more important than its default values in XSchema to DTD conversion.

The table below summarizes the possible combinations of XSchema attribute defaults and their XML 1.0 DTD equivalents.

Required

AttValue

XML 1.0 Equivalent

Yes

<value>

#FIXED <value>

Yes

--

#REQUIRED

No

<value>

AttValue

No

--

#IMPLIED

(-- indicates an empty or undeclared value)