Element and Attribute Declarations

Elements and attributes are the most basic components of an XML document. The catalog schema has a declaration for each of the different kinds of elements and attributes in the catalog, such as product, number, and dept. Elements are declared in the schema by using an xs:element element, while attributes are declared with xs:attribute.

Element and attribute declarations can be declared globally or locally. The catalog and product element declarations are global, meaning that they appear as a child of xs:schema in the schema document. The other element declarations, along with the attribute declaration, are local, and their scope is the type (ProductType) in which they are declared. If you’re writing a schema with XQuery in mind, you should use a global declaration for any elements that you want to validate separately. That’s because you can only start validation by using a global element declaration.

Types

Every element and attribute is associated with a type. Types are used to specify a class of elements (or attributes), including their allowed values, the structure of their content, and/or their attributes.

<colorChoices>navy black</colorChoices>

doc("catalog.xml")//product[colorChoices = 'navy']

Namespaces and XML Schema

When a target namespace is indicated in a schema, all of the globally declared elements and attributes take on that target namespace as part of their name. Example 14-2 shows the beginning of the catalog schema, which specifies a target namespace, http://datypic.com/prod, using the targetNamespace attribute on the xs:schema element.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           targetNamespace="http://datypic.com/prod"
           xmlns:prod="http://datypic.com/prod">
  <xs:element name="catalog" type="prod:CatalogType"/>
  <xs:complexType name="CatalogType">
  <!-- ... -->
  </xs:complexType>
</xs:schema>

Using this schema, the catalog element would have to be associated with a namespace in an instance document (and in any queries on that instance document). In addition, named type definitions also have names that are qualified by the target namespace. To refer to CatalogType, you use its qualified name—for example, prod:CatalogType if the prefix prod is bound to the namespace http://datypic.com/prod.

Where Do In-Scope Schema Definitions Come From?

Definitions for the built-in types are automatically included in the ISSD. A processor may include additional schema declarations and definitions in the ISSD according to implementation-defined rules. For example, it may have a set of built-in schemas that are always present. Processors that support schema validation may add definitions from the schema with which an input document is validated. Additionally, some implementations will allow you to specify programmatically or as a parameter—outside the scope of the query—what schemas to import.

Schema Imports

A schema import is used in XQuery to add a schema to the ISSD for a module. When a schema is imported, all of its global element and attribute declarations and type definitions are added.

A schema import, which appears in the query prolog, specifies the target namespace and, optionally, the schema location. For example:

import schema "http://datypic.com/prod"
           at "prod.xsd";

imports the schema document at prod.xsd whose target namespace is http://datypic.com/prod.

The syntax of a schema import is shown in Figure 14-1. The schema location and namespace must be literal values in quotes (not evaluated expressions).

Figure 14-1. Syntax of a schema import

For convenience, it is also possible to include a namespace declaration as part of the schema import. For example:

import schema namespace prod = "http://datypic.com/prod"
              at "prod.xsd";

binds the prod prefix to the namespace, in addition to importing it. Additionally, a default namespace declaration can be included in a schema import, as in:

import schema default element namespace "http://datypic.com/prod"
              at "prod.xsd";

This has the effect of making http://datypic.com/prod the default element namespace, in addition to importing the schema with that target namespace.

If the at keyword and schema location are left off, it is assumed that the processor knows where to locate the schema for the specified namespace. The processor is even allowed to ignore the provided location if it has another method of locating the schema.

Schema import is not supported by all implementations, only those that support the Schema Aware feature. If a schema import is used but is not supported by the implementation, error XQST0009 is raised.

import schema "" at "prod_nons.xsd";

import schema default element namespace ""
              at "prod_nons.xsd";

import schema "http://datypic.com/prod"
              at "prod.xsd", "prod2.xsd";

declare variable $strings:LetterA as strings:smallString := "A";

The Validate Expression

A validate expression can be used to validate a document or element node, which may come from an input document or be constructed in the query. It will validate the node according to a schema declaration if that declaration is in scope (i.e., if it is in the ISSD). For example:

validate strict { <product dept="ACC">
  <number>563</number>
  <name language="en">Floppy Sun Hat</name>
</product> }

validates the product element using a global product element declaration from the in-scope schema definitions, if one exists. This includes validating its attributes and descendants.

The syntax of a validate expression is shown in Figure 14-2.

Figure 14-2. Syntax of a validate expression

Starting in version 3.0, it is possible to specify the type name against which you wish to validate the element. In this case, you use the keyword type followed by the qualified name of the type. For example, the following validate expression will validate the product element against the type ProductType:

validate type ProductType { <product dept="ACC">
  <number>563</number>
  <name language="en">Floppy Sun Hat</name>
</product> }

The type must be among the in-scope schema definitions. If the type name is in a namespace, that namespace must be declared in the query, either as the default element namespace or using a prefix that is then used in the type name.

The expression to be validated must be either a single element node or a single document node that has exactly one element child.

The value of a validate expression is a new document or element node (with a new identity) annotated with the appropriate type indicated in the element declaration.

As with all schema validation, it also fills in default or fixed values and normalizes whitespace. When a document node is being validated, full schema validation is performed. When an element node is being validated, certain validation constraints are skipped. These omitted constraints include checking xs:ID values for uniqueness, and ensuring that xs:ENTITY, xs:NOTATION, and xs:IDREF values have matching entities, notations, and IDs.

Only implementations that support the optional Schema Aware Feature implement the validate expression. If this feature is used but is not supported by the implementation, error XQST0075 is raised.

Validation Mode

The validation mode controls how strictly an element or document is validated. There are two possible validation modes:

strict

When it is strict, the processor requires that a declaration be present for the element in the validate expression and that it be valid according to those declarations. If the element is not valid or a declaration cannot be found for it, an error is raised.

lax

When it is lax, the processor validates the element if it can find a declaration for it. It may not be able to find declarations if, for example, the schema was not imported or provided by the processor. If a declaration is found, the element or attribute must be valid according to it, or an error is raised. If no declaration is found, the processor will attempt to recursively validate the element’s children and attributes, and the process repeats. If no declarations are found in the entire tree or no validation errors are encountered, no error is raised.

In a validate expression, the validation mode can be specified just after the validate keyword. For example:

validate lax
 {<number>563</number>}

results in lax validation on the number element. If it is not specified, the default mode strict is used.

Assigning Type Annotations to Nodes

It is worth taking a closer look at how the validation process assigns type annotations to elements and attributes. If the node is valid according to the type designated in its declaration, it is usually quite straightforward. For example, the product element in the previous example would be assigned the type ProductType. However, there are some special cases.

An element or attribute is assigned a generic type (xs:untyped for elements, and xs:untypedAtomic for attributes) if:

• No schema validation was attempted.

• It was not validated because it was included as part of a wildcard (xs:any or xs:anyAttribute) that does not require validation.

• It is the result of an element constructor, and construction mode is set to strip. Construction mode is described in “Types and Newly Constructed Elements and Attributes”.

• It is the result of a validate expression, but it was not validated against an in-scope schema definition. This might happen if the validation mode is lax with no relevant declaration in scope.

Another generic type, xs:anyType, is used in a few other cases. The difference between xs:anyType and xs:untyped is that an element of type xs:anyType may contain other elements that have specific types. Elements of type xs:untyped, on the other hand, always have children that are untyped. An element is assigned the type xs:anyType if:

• When an input document was accessed, validation was attempted but the element was found to be invalid (or partially valid). Some implementations may allow the query evaluation to continue even if validation fails.

• It is the result of an element constructor, and construction mode is set to preserve.

A node that is declared to have a union type is assigned the specific member type for which it was validated (which is the first one to which it conforms). For example, if the <a>12</a> element is validated using a union type whose member types are xs:integer and xs:string, in that order, it is assigned the type xs:integer, not the union type itself.

An element that uses the XML Schema attribute xsi:type for type substitution is assigned the type specified by xsi:type if it is valid according to that type definition.

Nodes and Typed Values

In most cases, you can retrieve the typed value of an element or attribute by using the data function. Usually, it is simply the string value of the node, cast to the type of the element or attribute. For example, if the number element has the type xs:integer, the string value is 784 (type xs:string), while the typed value is 784 (type xs:integer). If the number element is untyped, its typed value is 784 (type xs:untypedAtomic).

There are two exceptions to this rule:

• Elements whose types have element-only content (that is, they allow only children and not text) do not have typed values, even if that particular element does not have any children. For example, the product element does not have a typed value if it is annotated with a type other than xs:untyped.

• The typed value of an element or attribute whose type is a list type is a sequence of atomic values, one for each item in the list. For example, if the element <colorChoices>navy black</colorChoices> has a type that is a list of strings, the typed value is a sequence of two strings, navy and black. The type of each atomic value is the item type of the list.

An element’s typed value will be the empty sequence in two cases:

• Its type is a complex type with an empty content model.

• It has been nilled, meaning that it has an attribute xsi:nil="true".

The typed value will not be the empty sequence just because the element has no content. For example, the typed value of <name></name> is the value "" (type xs:untypedAtomic) if name is untyped, and a zero-length string (type xs:string) if name has a complex type with mixed content but happens to be empty.

A summary of the rules for the typed values of elements and attributes appears in Table 14-2.

Types and Newly Constructed Elements and Attributes

Newly constructed nodes don’t automatically take on the type of their content. For example, the expression <abc>{2}</abc> does not create an abc element whose type annotation is xs:integer just because its content is of type xs:integer. In fact, element constructors that have simple content, as in this example, are always annotated with xs:untyped unless they are enclosed in a validate expression.

The type of a newly constructed element with complex content is also generic, but any children it copies from an input document may or may not retain their original types from the input document. This is determined by construction mode, which can have one of two values: strip or preserve. If construction mode is strip, the type of the newly constructed element, and all of its descendants, is xs:untyped. If the element is contained in a validate expression, it may then be annotated with a new schema type.

If construction mode is preserve, the type of the newly constructed element is xs:anyType, and all of its copied children retain their original types from the input document.

For example, suppose you construct a productList element with the following expression:

<productList>{doc("catalog.xml")//product}</productList>

Suppose also that the catalog.xml document has been validated with a schema, and the product elements from this document are annotated with the type ProductType. This query will result in a productList element that contains four product elements.

If construction mode is strip, both productList and all the product elements in the results will be annotated with xs:untyped. If construction mode is preserve, productList will be annotated with xs:anyType, and the product elements will be annotated with ProductType.

Construction mode is set using a construction declaration, which may appear in the query prolog. Its syntax is shown in Figure 14-3.

Figure 14-3. Syntax of a construction declaration