This appendix describes all the types that are built into XQuery via the XML Schema specification. For each type, it describes the set of valid values, as well as notes on comparing and casting values of these types.
xs:anyAtomicType
The type xs:anyAtomicType
is a generic type that encompasses all atomic types, both primitive and derived, including xs:untypedAtomic
. No values ever actually have the type xs:anyAtomicType
; they always have a more specific type. As such, it does not have a corresponding constructor.
However, this type name can be used as a placeholder for all other atomic types in function signatures and sequence types. For example, the distinct-values
function signature specifies that its argument is xs:anyAtomicType
. This means that atomic values of any type can be passed to this function.
xs:anySimpleType
The type xs:anySimpleType
represents the base type of all simple types (atomic, list, and union types) in the type hierarchy. In the context of XQuery, xs:anySimpleType
is abstract and is never used directly. For example, it is not possible to cast values to or from this type, or use this type name in a user-defined function signature.
xs:anyType
The type xs:anyType
is given to some element nodes without a more specific type. 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 also untyped. An element has the type xs:anyType
if:
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.
The element is the result of an element constructor, and construction mode is set to preserve
.
xs:anyURI
The primitive type xs:anyURI
represents a Uniform Resource Identifier (URI) reference. The value has to be a lexically valid URI reference. Because the bare minimum rules for valid URI references are fairly generic, most implementations accept most character strings, including a zero-length string. The only values that are not accepted are those that make inappropriate use of reserved characters, such as those that contain multiple #
characters or have %
characters that are not followed by two hexadecimal digits.
Some URI processors require that certain non-ASCII characters be escaped using a percent sign (%) followed by a two-digit Unicode codepoint. However, the xs:anyURI
type does accept these characters escaped or unescaped. Table B-1 shows some examples of valid and invalid URI references.
Values | Explanation |
---|---|
Valid | |
http://datypic.com | Absolute URI (in this case, an HTTP URL) |
http://datypic.com/prod.html#shirt | Absolute URI with fragment identifier |
mailto:[email protected] | Absolute URI using mailto scheme |
../%C3%A9dition.html | Relative URI with escaped non-ASCII character |
../édition.html | Relative URI with unescaped non-ASCII character |
../prod.html#A557 | Relative URI with fragment identifier |
urn:datypic:com | Absolute URI (in this case, a URN) |
Empty values are allowed | |
Invalid | |
http://datypic.com#frag1#frag2 | Too many fragment identifiers (# characters) |
http://datypic.com#f%rag | % character followed by something other than two hexadecimal digits |
For more information on URIs, see “Working with URIs”.
xs:anyURI
ValuesValues of type xs:anyURI
can be cast to and from xs:string
or xs:untypedAtomic
. No escaping or unescaping occurs when values are cast among these types. To escape reserved characters in URIs, use one of the functions iri-to-uri
, escape-html-uri
, or encode-for-uri
.
In addition, xs:anyURI
values are automatically promoted to xs:string
whenever a string is expected by a function or operator. For example, you could pass an xs:anyURI
value to the substring
function, which expects an xs:string
value as its first argument. This also means that xs:anyURI
values can be compared to strings and sorted with them.
Two xs:anyURI
values are considered equal if they have identical characters (based on Unicode codepoints). This means that if they are capitalized differently, they are considered different values, even if they may be seemingly equivalent URLs. For example, http://datypic.com/prod
is not equal to http://datypic.com/proD
, because the last letter is capitalized differently.
Values of type xs:anyURI
that are relative URIs are also compared based on codepoints, and no attempt is made to determine or compare their base URI. For example, ../prod
is always equal to ../prod
, even if the two xs:anyURI
values may have come from different XHTML documents with different base URIs.
xs:base64Binary
The primitive type xs:base64Binary
represents binary data in base-64 encoding. The following rules apply to xs:base64Binary
values:
The following characters are allowed: the letters A through Z (uppercase and lowercase), digits 0 through 9, the plus sign (+), the slash (/), the equals sign (=), and XML whitespace characters.
XML whitespace characters can appear anywhere in the value.
The number of non-whitespace characters must be divisible by four.
Equals signs, which are used as padding, can only appear at the end of the value, and there can be zero, one, or two of them. If there are two equals signs, they must be preceded by one of the following characters: A
, Q
, g
, w
. If there is only one equals sign, it must be preceded by one of the following characters: A
, E
, I
, M
, Q
, U
, Y
, c
, g
, k
, o
, s
, w
, 0
, 4
, 8
.
Note that these rules for acceptable base-64 values are rather strict, and processors are expected to enforce the rules strictly. This differs from practice elsewhere, and some software may generate “base 64” that doesn’t meet these rules.
Table B-2 lists some values of the xs:base64Binary
type. For more information on base-64 encoding, see RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies.
Values | Explanation |
---|---|
Valid | |
0DC7 | |
0 DC7 0F+9 | Whitespace is allowed anywhere in the value. |
0F+40A== | Equals signs are used for padding. |
An empty value is valid. | |
Invalid | |
DC7 | Odd number of characters not valid; characters appear in groups of four. |
==0F | Equals signs can only appear at the end. |
Values of type xs:base64Binary
can be cast to and from xs:hexBinary
, xs:string
, and xs:untypedAtomic
. When cast to xs:string
, an xs:base64Binary
value is converted to its canonical representation, which contains no whitespace characters except for a line-feed (#xA
) character inserted after every 76 characters and at the end.
Two xs:base64Binary
values can be compared using the comparison operators =
and !=
. Two xs:base64Binary
values are considered equal if their canonical representations are equal. This means that the whitespace is not taken into account in the comparison. An xs:base64Binary
value is never equal to an xs:hexBinary
value, nor is it equal to an xs:string
containing the same characters. Starting in XQuery 3.1, two xs:base64Binary
values can also be compared using the <
, <=
, >
, or >=
operators.
xs:boolean
The primitive type xs:boolean
represents a logical true
or false
value. The valid lexical representations for xs:boolean
are false
, true
, 0
(which is equal to false
), and 1
(which is equal to true
). The values are case-sensitive, so TRUE
and FALSE
are not valid lexical representations.
xs:boolean
ValuesIn addition to the standard xs:boolean
constructor, xs:boolean
values can be constructed using the true
and false
functions, which take no arguments and return the appropriate value. For example, true()
returns the value true
.
Boolean values are more often constructed indirectly, as:
The result of a function that returns a Boolean value, such as exists($seq1)
The value of a comparison expression, such as $price > 20
The result of a path expression that is evaluated using its effective boolean value, such as if (doc("catalog.xml")//product) ...
In addition, a function named boolean
can be used to explicitly convert a sequence to its effective boolean value. A sequence that is an xs:boolean
value false
, a single number 0
or NaN
, a single zero-length string, or the empty sequence, evaluates to false
. Otherwise, it evaluates to true
. Note that it doesn’t give the same result as the xs:boolean
constructor—for example, xs:boolean("false")
returns false
, but boolean("false")
returns true
. More information can be found in Appendix A, in the “boolean” section.
xs:boolean
ValuesValues of type xs:string
or xs:untypedAtomic
can be cast to xs:boolean
. The string false
(all lowercase), or the string 0
is converted to the value false
. The string true
(all lowercase) or 1
is converted to true
. Any other string value raises type error XPTY0004
; other strings that may appear to be equal to 0 or 1, such as 0.0
or 01
, are not accepted.
Values of any of the numeric types can also be cast to and from xs:boolean
. A numeric value that is equal to 0 or NaN
is converted to false
; any other numeric value is converted to true
.
Likewise, values of type xs:boolean
can be cast to xs:string
, xs:untypedAtomic
, and any of the numeric types. When they are cast to xs:string
or xs:untypedAtomic
, they are represented as true
and false
, not their numeric equivalents.
xs:date
The primitive type xs:date
represents a date of the Gregorian calendar. The lexical representation of xs:date
is YYYY-MM-DD
where YYYY
represents the year, MM
the month, and DD
the day. The year value has to be at least four digits, but it can be more than four digits to represent years later than 9999. However, XQuery implementations are not required to support more than four digits. A preceding minus sign (-) can be used to represent years before 0001. A time zone can be added to the end, as described in “Time Zones”.
Values of type xs:date
can be cast to and from xs:dateTime
, as described in the section on xs:dateTime
. You can obtain the current date by using the current-date
function, which returns a value of type xs:date
.
Table B-3 lists some values of the xs:date
type. For more information on working with dates, see Chapter 20.
Values | Explanation |
---|---|
Valid | |
2015-05-03 | May 3, 2015 |
2015-05-03-05:00 | May 3, 2015, US Eastern Standard Time, which is five hours behind Coordinated Universal Time (UTC) |
2015-05-03Z | May 3, 2015, Coordinated Universal Time (UTC) |
Invalid | |
2015/05/03 | Slashes are not allowed as separators. |
05-03-2015 | The value must be in YYYY-MM-DD order. |
2015-09-31 | The date must be valid (September has 30 days). |
An empty value or zero-length string is not permitted. |
xs:dateTime
The primitive type xs:dateTime
represents a combined date and time. The lexical representation of xs:dateTime
is YYYY-MM-DDThh:mm:ss.sss
, which is a concatenation of the xs:date
and xs:time
representation, with an uppercase letter T
between them. The constraints described for the xs:date
and xs:time
types are also true for xs:dateTime
. A time zone can be added to the end, as described in “Time Zones”.
Table B-4 lists some values of the xs:dateTime
type. For more information on working with dates and times, see Chapter 20.
Values | Explanation |
---|---|
Valid | |
2015-05-03T13:20:00 | 1:20 P.M. on May 3, 2015 |
2015-05-03T13:20:15.5 | 1:20 P.M. and 15.5 seconds on May 3, 2015 |
2015-05-03T13:20:00-05:00 | 1:20 P.M. on May 3, 2015, US Eastern Standard Time |
2015-05-03T13:20:00Z | 1:20 P.M. on May 3, 2015, Coordinated Universal Time (UTC) |
2015-05-03T24:00:00 | Midnight the evening of May 3/morning of May 4 |
2015-05-04T00:00:00 | Midnight the evening of May 3/morning of May 4 (equal to the previous example) |
Invalid | |
2015-05-03T13:00 | Seconds must be specified. |
2015-05-03 | The time is required. |
2015-05-0313:20:00 | The letter T is required. |
An empty value or zero-length string is not permitted. |
Values of type xs:dateTime
can be constructed using the standard xs:dateTime
constructor. In addition, a function named dateTime
can be used to construct an xs:dateTime
value from an xs:date
and an xs:time
. You can obtain the current date/time by using the current-dateTime
function, which returns a value of type xs:dateTime
.
It is possible to cast some values to and from xs:dateTime
, as shown in the examples in Table B-5. You can split an xs:dateTime
value into its date and time components by casting it to xs:date
or xs:time
. Additionally, xs:date
values can be cast to xs:dateTime
, in which case the time components are filled in with zeros. Time zones are unchanged by the cast.
Expression | Result |
---|---|
xs:dateTime("2015-05-03T10:32:15") cast as xs:date | 2015-05-03 |
xs:dateTime("2015-05-03T10:32:15") cast as xs:time | 10:32:15 |
xs:date("2015-05-03") cast as xs:dateTime | 2015-05-03T00:00:00 |
xs:dateTimeStamp
The type xs:dateTimeStamp
represents a combined date and time, but with a time zone required. It is derived from xs:dateTime
and has the same lexical representation and rules. The only difference is that a value is required to end in a time zone, as described in “Time Zones”. This type is only supported by processors that support XSD version 1.1 data types.
Because xs:dateTimeStamp
is derived from xs:dateTime
, values of this type follow the same rules for comparing and casting values.
Table B-6 lists some values of the xs:dateTimeStamp
type. For more information on working with dates and times, see Chapter 20.
Values | Explanation |
---|---|
Valid | |
2015-05-03T13:20:00-05:00 | 1:20 P.M. on May 3, 2015, US Eastern Standard Time |
2015-05-03T13:20:00Z | 1:20 P.M. on May 3, 2015, Coordinated Universal Time (UTC) |
Invalid | |
2015-05-03T13:20:00 | Time zone is required. |
An empty value or zero-length string is not permitted. |
xs:dayTimeDuration
The xs:dayTimeDuration
type is a restriction of the xs:duration
type, with only day (D
), hour (H
), minute (M
), and second (S
) components allowed. Its lexical representation is PnDTnHnMnS
, where an uppercase P
starts the expression, n
indicates the quantity of each component, and an uppercase letter T
separates the day and time components. For example, the value P3DT5H
represents a period of three days and five hours. You can omit components whose quantity is zero, but at least one component is required.
All the lexical rules for xs:duration
also apply to the xs:dayTimeDuration
type. This includes allowing a negative sign at the beginning of the value. Table B-7 lists some values of the xs:dayTimeDuration
type.
Unlike the xs:duration
type, the xs:dayTimeDuration
type is totally ordered, meaning that its values can be compared using the operators <
, >
, <=
, and >=
. For more on working with durations, see Chapter 20.
Values | Explanation |
---|---|
Valid | |
P6DT11H32M20S | 6 days, 11 hours, 32 minutes, 20 seconds |
P2DT3H | 2 days, 3 hours |
PT40H | 40 hours (the number of hours can be more than 24) |
PT0S | 0 seconds |
-P60D | Minus 60 days |
Invalid | |
P2Y | Years and months cannot be specified. |
P15.5D | Only the seconds number can contain a decimal point. |
P1D2H | The letter T must be used to separate day and time components. |
PT30S35M | Minutes must appear before seconds. |
An empty value or zero-length string is not permitted. |
xs:decimal
The primitive type xs:decimal
represents a decimal number. The lexical representation of xs:decimal
is a sequence of digits that can be preceded by a sign (+ or -) and may contain a decimal point (.). Trailing zeros after the decimal point are not considered significant. That is, the decimal values 5.1
and 5.1000
are considered equal.
Table B-8 lists some values of the xs:decimal
type.
Values | Explanation |
---|---|
Valid | |
5.0 | |
-5.2 | A sign is permitted. |
6 | A decimal point is not required. |
0 | |
0006.000 | Leading and trailing zeros are valid. |
Invalid | |
5,6 | The decimal separator must be a period, not a comma. |
1e6 | Exponential notation is not allowed; use xs:float or xs:double instead. |
An empty value or zero-length string is not permitted. |
Implementations vary in the number of significant digits they allow. They are free to round or truncate values to the number of digits they support. If overflow occurs during arithmetic operations on xs:decimal
values, error FOAR0002
is raised. When underflow occurs, the value 0.0
is returned.
xs:decimal
ValuesValues of type xs:decimal
can be cast to and from any of the other numeric types. Casting among numeric types is straightforward if the value is in the value space of both types. For example, casting an xs:decimal
value 12.5
to xs:float
results in a value 12.5E0
whose type is xs:float
.
However, some xs:float
or xs:double
values cannot be cast to xs:decimal
. Error FOCA0002
is raised if you attempt to cast to xs:decimal
one of the special values NaN
, INF
, or -INF
. Error FOCA0001
is raised if a value is too large to be supported by the implementation. Error FOCA0006
is raised if a value has greater precision than the implementation can support.
You can cast xs:decimal
values to xs:integer
, in which case the value is truncated.
Values of type xs:decimal
can also be cast to and from xs:string
, xs:untypedAtomic
, and xs:boolean
. When cast to xs:string
, the value will have no positive sign, no leading zeros, and no trailing zeros after the decimal point, except that there will always be at least one digit before the decimal point. If there is no fractional part, the decimal point is omitted. When cast to xs:boolean
, the value 0
becomes false
, and all other values become true
.
xs:double
The primitive type xs:double
is patterned after an IEEE double-precision 64-bit floating-point number. The lexical representation is a mantissa (a decimal number) followed, optionally, by the letter E (in upper- or lowercase), followed by an integer exponent. For example, 3E2
represents 3 × 102, or 300. In addition, there are three special values: INF
, (infinity), -INF
(negative infinity), and NaN
(not a number).
Table B-9 lists some values of the xs:double
type.
Values | Explanation |
---|---|
Valid | |
-5E12 | |
44.56E5 | |
+23.2e-2 | |
12 | |
+3.5 | Any value valid for xs:decimal is also valid for xs:float and xs:double |
-0 | Negative zero |
INF | Positive infinity |
NaN | Not a number |
Invalid | |
-5E3.5 | The exponent must be an integer. |
37E | An exponent must be specified if E is present. |
An empty value or zero-length string is not permitted. |
XQuery makes a distinction between positive and negative zero values for the xs:double
type. 0
and -0
are considered to be equal but separate values.
The implementation has some flexibility regarding how to handle overflow or underflow during arithmetic operations on xs:double
values. The processor may raise error FOAR0002
. Alternatively, in an overflow situation, it may return INF
, -INF
, or the largest or smallest possible value. For underflow, it may return the closest possible value to zero.
xs:double
ValuesValues of type xs:double
can be cast to and from any of the other numeric types. Casting among numeric types is straightforward if the value is in the value space of both types. For example, casting an xs:double
value 12.5E0
to xs:float
results in a value 12.5E0
whose type is xs:float
.
However, some xs:double
values are either too large or are otherwise not represented in the value spaces of xs:float
, xs:decimal
, or xs:integer
. See the descriptions of these types for more information.
Values of type xs:double
can also be cast to and from xs:string
, xs:untypedAtomic
, and xs:boolean
. When cast to xs:string
, if the absolute value is between 0.000001 (inclusive) and 1,000,000 (exclusive), the value is represented as a decimal. It will have no exponent, no positive sign, and no leading or trailing zeros, except that there will always be at least one digit before the decimal point. If there is no fractional part, the decimal point is omitted. If the value is outside that range, it is represented using an exponent, as shown in the first three examples in Table B-9.
xs:duration
The primitive type xs:duration
represents a duration of time. It allows you to specify a number of years (Y
), months (M
), days (D
), hours (H
), minutes (M
), and seconds (S
). The lexical representation of xs:duration
is PnYnMnDTnHnMnS
, where an uppercase P
starts the expression, n
indicates the quantity of each component, and an uppercase letter T
separates the day and time components. For example, the value P3YT5H
represents a period of three years and five hours.
The following rules apply to xs:duration
values:
A minus sign may appear at the beginning of the value (before the P
) to indicate a negative duration.
You can omit components whose quantity is zero, but at least one component is required.
If no time components (hours, minutes, or seconds) are specified, the T
cannot appear.
The numbers must be integers, except for the number of seconds, which can include a decimal point. XQuery implementations are required to support at least three fractional digits in the number of seconds, but may support more.
If a decimal point appears in the number of seconds, there must be at least one digit after the decimal point.
Table B-10 lists some values of the xs:duration
type. For more information on working with durations, see Chapter 20.
Values | Explanation |
---|---|
Valid | |
P3Y5M8DT9H25M20S | 3 years, 5 months, 8 days, 9 hours, 25 minutes, 20 seconds |
P2DT3H | 2 days, 3 hours |
P25M | 25 months (the number of months may be more than 12) |
PT25M | 25 minutes |
P0Y | 0 years |
-P60Y | Minus 60 years |
PT1M30.5S | 1 minute, 30.5 seconds |
Invalid | |
P16.3D | All numbers except the seconds must be integers. |
P3D5H | The T must be used to separate days and time components. |
P-40M | The minus sign must appear first. |
P1YM5D | The number of months is missing. |
An empty value or zero-length string is not permitted. |
The xs:duration
type is not totally ordered, meaning that values of this type cannot be compared because it is sometimes ambiguous. For example, if you try to determine whether the xs:duration
value P1M
is greater than or less than the xs:duration
value P30D
, it is ambiguous. Months may have 28, 29, 30, or 31 days, so is 30 days less than a month or not?
For this reason, there are two types derived from duration: xs:yearMonthDuration
and xs:dayTimeDuration
. By ensuring that month and day components never appear in the same duration, the ambiguity is eliminated.
Values of xs:duration
can be tested for equality (or inequality) with other values of the same type. Two xs:duration
values will be considered equal if they have the same number of months and seconds, regardless of their lexical representation. For example, P1YT60S
is equal to P12MT1M
because they represent the same duration of time (12 months and 60 seconds). However, you cannot compare them by using the operators <
, <=
, >
, or >=
. These operators can be used on the two ordered subtypes.
xs:ENTITY
The type xs:ENTITY
represents a value that refers to an unparsed entity, which must be declared in the document’s DTD. The xs:ENTITY
type might be used to include information from another file that is not in XML syntax, such as images. XQuery does not provide any special functions for this type. However, since xs:ENTITY
is ultimately derived from xs:string
, xs:ENTITY
values can be compared and used like strings.
xs:error
The type xs:error
is a union type that has no member types and therefore no possible valid values. It is used in XML Schema 1.1 to force an error during conditional type assignment. In XQuery, if your processor supports XSD 1.1, it is possible to use the type xs:error
as a type constructor or in a cast expression. However, this will always result in a dynamic query error since there are no possible valid values. A better approach to forcing an error is to call the error
function, which allows the specification of an error message.
xs:float
The primitive type xs:float
is patterned after an IEEE single-precision 32-bit floating-point number. The lexical representation is a mantissa (a decimal number) followed, optionally, by the letter E (in upper- or lowercase), followed by an integer exponent. For example, 3E2
represents 3 × 102, or 300. In addition, there are three special values: INF
, (infinity), -INF
(negative infinity), and NaN
(not a number).
Table B-11 lists some values of the xs:float
type.
Values | Explanation |
---|---|
Valid | |
-5E12 | |
44.56E5 | |
+23.2e-2 | |
12 | |
+3.5 | Any value valid for xs:decimal is also valid for xs:float and xs:double |
-0 | Negative zero |
INF | Positive infinity |
NaN | Not a number |
Invalid | |
-5E3.5 | The exponent must be an integer. |
37E | An exponent must be specified if E is present. |
An empty value or zero-length string is not permitted. |
XQuery makes a distinction between positive and negative zero values for the xs:float
type. 0
and -0
are considered to be equal but separate values.
The implementation has some flexibility regarding how to handle overflow or underflow during arithmetic operations on xs:float
values. The processor may raise error FOAR0002
. Alternatively, in an overflow situation, it may return INF
, -INF
, or the largest or smallest possible value. For underflow, it may return the closest possible value to zero.
xs:float
ValuesValues of type xs:float
can be cast to and from any of the other numeric types. Casting among numeric types is straightforward if the value is in the value space of both types. For example, casting an xs:float
value 12.5E0
to xs:decimal
results in a value 12.5
whose type is xs:decimal
.
However, some xs:float
values are either too large or are otherwise not represented in the value spaces of xs:decimal
or xs:integer
. See the descriptions of these types for more information.
Additionally, some special cases apply when casting xs:double
values to xs:float
. Values that are too large to be represented by xs:float
are cast to INF
, values that are too small are cast to -INF
, and values that would cause underflow are cast to 0
.
Values of type xs:float
can also be cast to and from xs:string
, xs:untypedAtomic
, and xs:boolean
. When cast to xs:string
, if the absolute value is between 0.000001 (inclusive) and 1000000 (exclusive), the value is represented as a decimal. It will have no exponent, no positive sign, and no leading or trailing zeros, except that there will always be at least one digit before the decimal point. If there is no fractional part, the decimal point is omitted. If the value is outside that range, it is represented using an exponent, as shown in the first three examples in Table B-11.
xs:gDay
The primitive type xs:gDay
represents a recurring day of the month. It can be used to specify, for example, that bills are sent out on the 15th of each month. It does not represent a number of days; to represent that, use the xs:dayTimeDuration
type instead.
The lexical representation of xs:gDay
is ---DD
, where DD
is a two-digit day number. An optional time zone may be used, as described in “Time Zones”. Table B-12 lists some values of xs:gDay
.
Values | Explanation |
---|---|
Valid | |
---04 | The fourth of the month |
Invalid | |
---41 | It must be a valid day of the month. |
04 | The three leading hyphens are required. |
---4 | It must have two digits. |
An empty value or zero-length string is not permitted. |
Values of xs:gDay
can be tested for equality (or inequality) with other values of the same type, but they cannot be compared using the operators <
, <=
, >
, or >=
.
Values of this type can be cast from the xs:date
and xs:dateTime
types. For example, the expression xs:date("2015-05-30") cast as xs:gDay
returns an xs:gDay
value of ---30
. They can also be cast to and from xs:string
and xs:untypedAtomic
.
xs:gMonth
The primitive type xs:gMonth
represents a recurring month. It can be used to specify, for example, that year-end auditing occurs in October of every year. It does not represent a number of months; to represent that, use the xs:yearMonthDuration
type instead.
The lexical representation of xs:gMonth
is --MM
. An optional time zone may be used, as described in “Time Zones”. Table B-13 lists some values of this type.
Values | Explanation |
---|---|
Valid | |
--06 | June |
Invalid | |
--06-- | Because of an error in the first version of XML Schema, you may see examples that use this format, but it is technically invalid. |
--15 | The month must be a valid month. |
2015-06 | The year cannot be specified. |
06 | The two leading hyphens are required. |
--6 | It must have two digits. |
An empty value or zero-length string is not permitted. |
Values of xs:gMonth
can be tested for equality (or inequality) with other values of the same type, but you cannot compare them using the operators <
, <=
, >
, or >=
.
Values of this type can be cast from the xs:date
and xs:dateTime
types. For example, the expression xs:date("2015-05-30") cast as xs:gMonth
returns an xs:gMonth
value of --05
. They can also be cast to and from xs:string
and xs:untypedAtomic
.
xs:gMonthDay
The primitive type xs:gMonthDay
represents a recurring day of the year. It can be used to specify, for example, that your anniversary is on the 30th of July every year.
The lexical representation of xs:gMonthDay
is --MM-DD
. An optional time zone can be used, as described in “Time Zones”. Table B-14 lists some values of this type.
Values | Explanation |
---|---|
Valid | |
--05-03 | May 3 |
--05-03Z | May 3, Coordinated Universal Time (UTC) |
Invalid | |
--05-32 | It must be a valid day of the year. |
05-03 | The two leading hyphens are required. |
--5-3 | The month and day must have two digits each. |
An empty value or zero-length string is not permitted. |
Values of xs:gMonthDay
can be tested for equality (or inequality) with other values of the same type, but they cannot be compared using the operators <
, <=
, >
, or >=
.
Values of this type can be cast from the xs:date
and xs:dateTime
types. For example, the expression xs:date("2015-05-30") cast as xs:gMonthDay
returns an xs:gMonthDay
value of --05-30
. They can also be cast to and from xs:string
and xs:untypedAtomic
.
xs:gYear
The primitive type xs:gYear
represents a specific year. The lexical representation of xs:gYear
is YYYY
. A preceding minus sign (-) can be used to represent years before 0001. An optional time zone may be used, as described in “Time Zones”. Table B-15 lists some values of the xs:gYear
type.
Values | Explanation |
---|---|
Valid | |
2015 | 2015 |
2015-08:00 | 2015, US Pacific Time |
12015 | The year 12015 |
0922 | The year 922 |
-0073 | 73 B.C. |
Invalid | |
99 | It must have at least four digits. |
922 | It must have at least four digits; leading zeros can be added. |
An empty value or zero-length string is not permitted. |
Values of xs:gYear
can be tested for equality (or inequality) with other values of the same type, but they cannot be compared using the operators <
, <=
, >
, or >=
.
Values of this type can be cast from the xs:date
and xs:dateTime
types. For example, the expression xs:date("2015-05-30") cast as xs:gYear
returns an xs:gYear
value of 2015
. They can also be cast to and from xs:string
and xs:untypedAtomic
.
xs:gYearMonth
The primitive type xs:gYearMonth
represents a specific month. The lexical representation of xs:gYearMonth
is YYYY-MM
. A preceding minus sign (-) can be used to represent years before 0001. An optional time zone may be used, as described in “Time Zones”. Table B-16 lists some values of the xs:gYearMonth
type.
Values | Explanation |
---|---|
Valid | |
2015-05 | May 2015 |
2015-05-08:00 | May 2015, US Pacific Time |
Invalid | |
2015-5 | The month must have two digits. |
2015-13 | The month must be a valid month. |
An empty value or zero-length string is not permitted. |
Values of xs:gYearMonth
can be tested for equality (or inequality) with other values of the same type, but they cannot be compared using the operators <
, <=
, >
, or >=
.
Values of this type can be cast from the xs:date
and xs:dateTime
types. For example, the expression xs:date("2015-05-30") cast as xs:gYearMonth
returns an xs:gYearMonth
value of 2015-05
. They can also be cast to and from xs:string
and xs:untypedAtomic
.
xs:hexBinary
The primitive type xs:hexBinary
represents binary data as a sequence of binary octets. The type xs:hexBinary
uses hexadecimal encoding, where each binary octet is a two-character hexadecimal number. Digits 0 through 9 and lowercase and uppercase letters A through F are permitted. For example, 0CD7
and 0cd7
are two equal xs:hexBinary
representations consisting of two octets.
Table B-17 lists some values of the xs:hexBinary
type.
Values | Explanation |
---|---|
Valid | |
0CD7 | |
0cd7 | The equivalent of 0CD7 |
An empty value is allowed. | |
Invalid | |
CD7 | An odd number of characters is not allowed; characters appear in pairs. |
Values of type xs:hexBinary
can be cast to and from xs:base64Binary
, xs:string
, and xs:untypedAtomic
. When cast to xs:string
, xs:hexBinary
values are converted to their canonical representation, which uses only uppercase letters.
Two xs:hexBinary
values can be compared using the comparison operators =
and !=
. Two xs:hexBinary
values are considered equal if their canonical representations are equal. This means that the case of the letters is not taken into account in the comparison. An xs:hexBinary
value is never equal to an xs:base64Binary
value, nor is it equal to an xs:string
containing the same characters. Starting in XQuery 3.1, two xs:hexBinary
values can also be compared using the <
, <=
, >
, or >=
operators.
xs:ID
The type xs:ID
represents a unique identifier in an XML document. It is most commonly used as the type of an attribute that serves as an identifier for the element that carries it. Example B-1 shows an XML document that contains some ID attributes, namely the id
attribute of the section
element, and the fnid
attribute of the fn
element. Each section
and fn
element is uniquely identified by an ID value, such as fn1
, preface
, or context
.
The example assumes that this document was validated with a schema that declares these attributes to be of type xs:ID
. Having the local name id
is not enough to make an attribute an xs:ID
; the attribute must be declared in a schema to have the type ID. In fact, the name is irrelevant; an attribute named foo
can have the type xs:ID
, and an attribute named id
can be of type xs:integer
.
<book>
<section
id=
"preface"
>
This book introduces XQuery... The examples are downloadable<fnref
ref=
"fn1"
/>
...</section>
<section
id=
"context"
>
...</section>
<section
id=
"language"
>
...Expressions, introduced in<secRef
refs=
"context"
/>
, are...</section>
<section
id=
"types"
>
...As described in<secRef
refs=
"context language"
/>
, you can...</section>
<fn
fnid=
"fn1"
>
See http://datypic.com.</fn>
</book>
The values of attributes of type xs:ID
must be unique within the entire XML document. This is true even if two xs:ID
values appear in attributes with different names, or on elements with different names. For example, it would be invalid for an fn
element’s fnid
attribute to have the same value as a section
element’s id
attribute. Values of type xs:ID
follow the same rules as the xs:NCName
type; they must start with a letter or underscore, and can only contain letters, digits, underscores, hyphens, and periods.
Because xs:ID
is ultimately derived from xs:string
, xs:ID
values can be compared and used like strings. For more information on working with IDs, see “Working with IDs”.
xs:IDREF
The type xs:IDREF
represents a cross-reference to an xs:ID
value. Like xs:ID
, it is most commonly used to describe attribute values. Each attribute of type xs:IDREF
must reference an ID in the same XML document. For example, the ref
attribute of the fnref
element in Example B-1 contains an xs:IDREF
value (again, assuming it is validated with a schema). Its value, fn1
, matches the value of the fnid
attribute of the fn
element. You can find all the xs:IDREF
values that refer to a specific ID by using the idref
function.
Because xs:IDREF
is ultimately derived from xs:string
, xs:IDREF
values can be compared and used like strings. For more information on working with IDREFs, see “Working with IDs”.
xs:IDREFS
The type xs:IDREFS
represents a whitespace-separated list of one or more xs:IDREF
values. In Example B-1, the refs
attribute of secRef
is assumed to be of type xs:IDREFS
. The first refs
attribute contains only one xs:IDREF
(context
), while the second contains two xs:IDREF
values (context
and language
).
Because xs:IDREF
is derived by restriction from xs:string
, a value of type xs:IDREFS
can be treated like a sequence of xs:string
values.
xs:integer
The type xs:integer
represents an arbitrarily large integer. It is derived from xs:decimal
, and it is the base type for many other integer types.
The lexical representation of the xs:integer
type is a sequence of digits. A sign (+ or -) may precede the numbers. Decimal points are not permitted in xs:integer
values, even if there are no significant digits after the decimal point. Table B-18 lists some values of the xs:integer
type.
Values | Explanation |
---|---|
Valid | |
231 | |
00231 | Leading zeros are permitted. |
0 | |
+4 | A sign is permitted. |
-4 | |
Invalid | |
4.0 | A decimal point is not permitted. |
An empty value or zero-length string is not permitted. |
Implementations vary in the number of significant digits they support. If overflow or underflow occurs during arithmetic operations on xs:integer
values, the implementation may either raise error FOAR0002
or return a result that is the remainder after dividing by the largest possible integer value.
xs:integer
ValuesValues of type xs:integer
can be cast to and from any of the other numeric types. Casting among numeric types is straightforward if the value is in the value space of both types. For example, casting an xs:float
value 12
to xs:integer
results in a value 12
whose type is xs:integer
. When casting a number with a fractional part to xs:integer
, the fractional part is truncated (not rounded).
However, some xs:float
or xs:double
values cannot be cast to xs:integer
. Error FOCA0002
is raised if you attempt to cast to xs:integer
one of the special values NaN
, INF
, or -INF
. Error FOCA0003
is raised if a value is greater than those supported by the implementation.
Values of type xs:integer
can also be cast to and from xs:string
, xs:untypedAtomic
, and xs:boolean
. When cast to xs:string
, the value will have no positive sign and no leading zeros. When cast to xs:boolean
, the value 0
becomes false
, and all other values become true
.
xs:language
The type xs:language
represents a natural language. It is often used for attributes that specify the language of the element. Its values conform to RFC 3066, Tags for the Identification of Languages. The most common format is a two- or three-character (usually lowercase) language code that follows ISO 639, such as en
or fr
. It can optionally be followed by a hyphen and a two-character (usually uppercase) country code that follows ISO 3166, such as en-US
. Additional dialects or country codes may be specified at the end of the value, each preceded by a hyphen.
Processors do not verify that values of the language type conform to the above rules. They simply validate based on the pattern specified for this type, which says that the value must consist of parts containing one to eight characters, separated by hyphens.
The xs:language
type is most commonly associated with the xml:lang
attribute defined in the XML specification; the value of this attribute may be tested using the lang
function. Table B-19 lists some values of the xs:language
type.
Values | Explanation |
---|---|
Valid | |
en | English |
en-US | US English |
en-GB | UK English |
de | German |
es | Spanish |
fr | French |
it | Italian |
ja | Japanese |
nl | Dutch |
zh | Chinese |
any-value-with-short-parts | Although this value is valid, it does not follow RFC 3066 guidelines. |
Invalid | |
longerThan8 | Parts cannot exceed eight characters in length. |
An empty value or zero-length string is not permitted. |
The xs:language
type is derived by restriction from xs:string
, so any functions and operations that can be performed on strings, such as substring
and comparing using the <
operator, can also be performed on xs:language
values.
xs:long
The type xs:long
represents an integer between -9223372036854775808 and 9223372036854775807, inclusive. It is ultimately derived from xs:decimal
, via xs:integer
. Its value can be a sequence of digits, optionally preceded by a sign (+ or -). For example, -9223372036854775808
, 0
, 1
, and +214
are valid values. Because implementations are only required to support integers up to 18 digits, some may not accept the full value range of xs:long
.
xs:Name
The xs:Name
type is used to represent a lexically valid name in XML. However, this type is almost never used in XQuery or XML Schema. The xs:QName
type is much more appropriate to fully represent names, whether they are in a namespace or not. For unqualified names or local parts of names, xs:NCName
or even xs:string
are also appropriate types.
xs:NCName
The letters NC
in NCName
stand for non-colonized. The type xs:NCName
can be used to represent the local part of names, or even prefixes. An xs:NCName
value must start with a letter and underscore (_), and may contain only letters, digits, underscores, hyphens, and periods.
Because xs:NCName
is ultimately derived from xs:string
, xs:NCName
values can be compared and used like strings.
xs:NMTOKEN
The type xs:NMTOKEN
represents a string that contains no whitespace. xs:NMTOKEN
values may consist only of characters allowed in XML names, namely letters, digits, periods, hyphens, underscores, and colons. For example, navy
, 123
, and SENDER_OR_RECEIVER
are all valid values. Leading and trailing whitespace is allowed but is considered insignificant.
Because xs:NMTOKEN
is ultimately derived from xs:string
, xs:NMTOKEN
values can be compared and used like strings.
xs:NMTOKENS
The type xs:NMTOKENS
represents a whitespace-separated list of one or more xs:NMTOKEN
values. For example, navy black
is a valid value that represents two different xs:NMTOKEN
values. Because xs:NMTOKEN
is derived by restriction from xs:string
, a value of type xs:NMTOKENS
can be treated like a sequence of xs:string
values.
xs:nonNegativeInteger
The type xs:nonNegativeInteger
represents an arbitrarily large integer greater than or equal to 0. It is ultimately derived from xs:decimal
via xs:integer
. Its value can be a sequence of digits, optionally preceded by a sign (+). For example, 0
, 1
, and +1234123412341234
are valid values.
xs:nonPositiveInteger
The type xs:nonPositiveInteger
represents an arbitrarily large integer less than or equal to 0. It is ultimately derived from xs:decimal
, via xs:integer
. Its value can be a sequence of digits, optionally preceded by a sign (- or + if the value is 0
). For example, 0
, -1
, and -1234123412341234
are valid values.
xs:normalizedString
The xs:normalizedString
type is identical to xs:string
, except in the way that whitespace is normalized in its values. This whitespace normalization takes place during validation, and also when values are constructed or cast to xs:normalizedString
. For values of type xs:normalizedString
, the processor replaces each carriage return, line feed, and tab by a single space. This is different from xs:string
values, where whitespace is preserved. There is no collapsing of multiple consecutive spaces into a single space; this is done with values of type xs:token
.
The whitespace handling of the xs:normalizedString
type is different from that of the normalize-space
function, which does collapse multiple adjacent spaces to a single space.
The xs:normalizedString
type is derived by restriction from xs:string
, so any functions and operations that can be performed on strings, such as substring
and comparing using the <
operator, can also be performed on xs:normalizedString
values.
xs:NOTATION
The primitive type xs:NOTATION
represents a reference to an XML notation. Notations are a way to indicate how to interpret non-XML content that is rarely used in the domain of XQuery and XML Schema. xs:NOTATION
is an abstract type, and as such, you cannot construct values that have the type xs:NOTATION
. It is possible to create user-defined types that are restrictions of xs:NOTATION
, which do have type constructors associated with them. These type constructors have the constraint that they will only accept a literal string as an argument, not an evaluated expression.
xs:numeric
The type xs:numeric
is a union type that includes xs:double
, xs:float
, and xs:decimal
. It is most commonly used in the signatures of functions that accept any numeric type. For example, the abs
function accepts an argument of type xs:numeric
, which means that an xs:double
, xs:float
, or xs:decimal
value can be passed to it. Because of the function conversion rules, xs:integer
values are also allowed, since xs:integer
is derived from xs:decimal
.
Despite its xs
prefix, this type is not defined by XML Schema. However, it is implicitly supported by XQuery 3.1 processors. In previous versions of XQuery, a special keyword numeric
(no prefix) was used in built-in function signatures instead.
xs:QName
The primitive type xs:QName
represents an XML namespace-qualified name. xs:QName
values have three parts: the full namespace URI, the local part of the name, and the prefix. The namespace and the prefix are optional. If a QName does not have a namespace associated with it, it is considered to be in “no namespace.”
When used in a query or schema, the lexical representation of an xs:QName
has just two parts: an optional prefix and the local part of the name. Based on the prefix, the context is used to determine the namespace URI. If the prefix is not present, either the name is in the default namespace or it is in no namespace at all.
Table B-20 lists some values of the xs:QName
type.
Values | Explanation |
---|---|
Valid | |
prod:number | Valid assuming the prefix prod is bound to a namespace in scope. |
number | Prefix and colon are optional. |
Invalid | |
:number | An xs:QName must not start with a colon. |
prod:3rdnumber | The local part must not start with a number; it must be a valid NCName . |
An empty value or zero-length string is not permitted. |
The prefix itself has no meaning; it is just a placeholder. However, the XQuery processor does keep track of a QName’s prefix. This simplifies certain processes such as serializing QNames and casting them to strings.
One of the most common ways of getting an xs:QName
is to use the node-name
function, which returns the name of an element or attribute as an xs:QName
value.
The xs:QName
type has a standard constructor that allows a value to be cast from xs:untypedAtomic
or from xs:string
. The value may be prefixed, e.g., prod:number
, or unprefixed, e.g., number
. If a prefix is used, it must be declared.
Two additional functions can be used to construct xs:QName
values: QName
and resolve-QName
.
Two xs:QName
values can be compared using the =
and !=
operators. They are considered equal if they have the exact same namespace URI (based on Unicode codepoints) and the exact same local name (also based on Unicode codepoints); the prefixes are ignored. Because the xs:QName
type is not ordered, two xs:QName
values cannot be compared using the <
, <=
, >
, or >=
operators. The xs:QName
type is not derived from xs:string
, so you cannot compare them to strings directly.
More information on working with qualified names can be found in “Working with Qualified Names”.
xs:string
An xs:string
value is a character string that may contain any character allowed by XML. The xs:string
type is a primitive type from which a large number of other types are derived. It is intended to represent generic character data, and whitespace in elements of type xs:string
is always preserved.
It should be noted that xs:string
is not the default type for untyped values. If a value is selected from an input document with no schema, the value is given the type xs:untypedAtomic
, not xs:string
. But it is easy enough to cast an xs:untypedAtomic
value to xs:string
. In fact, you can cast a value of any type to xs:string
, and you can cast an xs:string
value to any type (with restrictions for xs:QName
and xs:NOTATION
), assuming it is a valid value for that type.
Chapter 18 provides an overview of all the functions and operations on strings. All the operations and functions that can be performed on xs:string
values can also be performed on values whose types are restrictions of xs:string
. This includes user-defined types that appear in a schema, as well as the built-in derived types such as xs:normalizedString
, xs:language
, and xs:ID
.
xs:time
The primitive type xs:time
represents a specific time of day. The lexical representation of xs:time
is hh:mm:ss.sss
where hh
is the hour, mm
is the minutes, and ss.sss
is the seconds. XQuery implementations are required to support at least three fractional digits for the number of seconds, but may support more. To represent P.M. values, the hours 13 through 24 should be used. Either of the values 00:00:00
or 24:00:00
can be used to represent midnight. These values are considered identical, which means that 24:00:00
is considered less than 23:59:59
. A time zone can be added to the end, as described in “Time Zones”.
Values of type xs:dateTime
can be cast to xs:time
, but the reverse is not true. This is described further in the section on xs:dateTime
. You can obtain the current time by using the current-time
function, which returns a value of type xs:time
.
Table B-21 lists some values of the xs:time
type. For more information on working with times, see Chapter 20.
Values | Explanation |
---|---|
Valid | |
15:30:00 | 3:30 P.M. |
15:30:34.67 | 3:30 P.M. and 34.67 seconds |
15:30:00-08:00 | 3:30 P.M., US Pacific Time |
15:30:00Z | 3:30 P.M., Coordinated Universal Time (UTC) |
00:00:00 | Midnight |
24:00:00 | Midnight (equal to the previous example) |
Invalid | |
3:40:00 | All numbers must be two digits each. |
15:30 | Seconds must be specified. |
15:70:00 | It must be a valid time of day. |
An empty value or zero-length string is not permitted. |
xs:token
The xs:token
type is identical to xs:string
, except in the way that whitespace is normalized in its values. This whitespace normalization takes place during validation, and also when values are constructed or cast to xs:token
. In values of type xs:token
, the processor replaces each carriage return, line feed, and tab by a single space. Subsequently, all consecutive whitespace characters are replaced by a single space, and leading and trailing spaces are removed. This is different from xs:string
values, where whitespace is preserved. It is also different from xs:normalizedString
, which replaces whitespace characters but does not collapse them.
A value of type xs:token
can contain whitespace, despite the fact that “token” implies a single token. The xs:token
type is derived by restriction from xs:string
, so any functions and operations that can be performed on strings, such as substring
and comparisons using the <
operator, can also be performed on xs:token
values.
xs:unsignedLong
The type xs:unsignedLong
represents an unsigned integer between 0 and 18446744073709551615, inclusive. It is ultimately derived from xs:decimal
via xs:integer
. Its value can be a sequence of digits. For example, 0
, 1
, and 18446744073709551615
are valid values. A leading plus sign (+) is not allowed.
xs:untyped
The generic xs:untyped
type applies to all element nodes that are “untyped,” i.e., have no specific type annotation. This includes element nodes that were not validated against a schema declaration. “Types, Nodes, and Atomic Values” describes how element nodes might come to be untyped.
xs:untypedAtomic
The generic xs:untypedAtomic
type applies to all attribute nodes and atomic values that are “untyped”, i.e., have no specific type. An attribute node is untyped if it was not validated against a schema declaration. “Types, Nodes, and Atomic Values” describes how attribute nodes might come to be untyped.
An atomic value might have the type xs:untypedAtomic
if it was extracted from an untyped element or attribute. Untyped atomic values can often be used wherever a typed value would. This is because every function and expression has rules for casting untyped values to an appropriate type.
xs:yearMonthDuration
The xs:yearMonthDuration
type represents a restriction of the xs:duration
type, with only year (Y
) and month (M
) components allowed. Its lexical representation is PnYnM
, where an uppercase P
starts the expression, and n
indicates the quantity of each component. For example, the value P3Y5M
represents a period of three years and five months. You can omit components whose quantity is zero, but at least one component is required.
All of the lexical rules for xs:duration
also apply to the xs:yearMonthDuration
type. This includes allowing a negative sign at the beginning of the value. Table B-22 lists some values of the xs:yearMonthDuration
type.
Unlike the xs:duration
type, the xs:yearMonthDuration
type is totally ordered, meaning that its values can be compared. For more information on working with durations, see Chapter 20.
Values | Explanation |
---|---|
Valid | |
P3Y5M | 3 years, 5 months |
P3Y | 3 years |
P30M | 30 months (the number of months can be more than 12) |
P0M | 0 months |
Invalid | |
P2Y6M3D | Days cannot be specified. |
P16.6Y | The number of years cannot be expressed as a decimal. |
P2M1Y | The years must appear before the months. |
An empty value or zero-length string is not permitted. |