XSLT 3.0 conformance

F.1 Application Programming Interfaces

This category covers interfaces for initiating a transformation, setting its parameters, initializing the static and dynamic context, and collecting the results. In general terms, it is implementation defined how input is passed to the processor and how it returns its output. This includes the interpretation of URIs used to refer to stylesheet packages and modules, source documents and collections, collations, and result documents.

► For information on Saxon's APIs for XSLT transformation, see Invoking XSLT from an application.

More specifically:

1. A processor MAY also provide a mode of operation in which static errors in parts of the stylesheet that are not evaluated can go unreported. (See 2.14 Error Handling)

   ► By default, in Saxon-EE, the body of a template rule is compiled only the first time that the template rule is evaluated; static errors in unused template rules are therefore not detected. This setting can be changed for example by using -opt:-j on the command line.

2. If the initialization of any global variables or parameter depends on the context item, a dynamic error can occur if the context item is absent. It is implementation-defined whether this error occurs during priming of the stylesheet or subsequently when the variable is referenced; and it is implementation-defined whether the error occurs at all if the variable or parameter is never referenced. (See 2.3.2 Priming a Stylesheet)

   ► The error typically only occurs when the variable is actually referenced.

3. The way in which an XSLT processor is invoked, and the way in which values are supplied for the source document, starting node, stylesheet parameters, and base output URI, are implementation-defined. (See 2.3.2 Priming a Stylesheet)

   ► For information on Saxon's APIs for XSLT transformation, see Invoking XSLT from an application. Transformations can also be invoked from the command line (see Running XSLT from the command line).

4. The way in which a base output URI is established is implementation-defined. (See 2.3.6 Post-processing the Raw Result)

   ► For the s9api interface: XsltTransformer30.setBaseOutputURI(). For the command line: the -o option.

5. It is implementation-defined how a package is located given its name and version, and which version of a package is chosen if several are available. (See 3.5.2 Dependencies between Packages)

   ► Packages must be explicitly loaded into a configuration, for example by use of the -pack option on the command line or by the method XsltCompiler.importPackage(). There is no machinery for selecting a preferred version of a package if several are available.

6. In the absence of an [xsl:]default-collation attribute, the default collation may be set by the calling application in an implementation-defined way. (See 3.7.1 The default-collation Attribute)

   ► The name of the default collation may be specified as a configuration option on the XSLT compiler: XsltCompiler.declareDefaultCollation().

7. It is implementation-defined what forms of URI reference are acceptable in the href attribute of the xsl:include and xsl:import elements, for example, the URI schemes that may be used, the forms of fragment identifier that may be used, and the media types that are supported. The way in which the URI reference is used to locate a representation of a stylesheet module, and the way in which the stylesheet module is constructed from that representation, are also implementation-defined. (See 3.11.1 Locating Stylesheet Modules)

   ► A user-written URIResolver may be supplied to handle any kind of URI that the application wishes to handle.

8. The statically known documents, statically known collections, and the statically known default collection type are implementation-defined. (See 5.3.1 Initializing the Static Context)

   ► These values are all empty; no documents, collections, or collection types are known statically.

9. Implementations may provide user options that relax the requirement for the doc and collection functions (and therefore, by implication, the document function) to return stable results. The manner in which such user options are provided, if at all, is implementation-defined. (See 5.3.3 Initializing the Dynamic Context)

   ► Document stability may be relaxed by calling the extension function saxon:discard-document(). Collection stability can be controlled at the configuration level, or at the level of an individual collection by means of a query parameter in the collection URI.

10. The implicit timezone for a transformation is implementation-defined. (See 5.3.3.2 Other Components of the XPath Dynamic Context)

    ► The value is taken from the system clock, as exposed by the Java platform. Alternatively, the current date and time may be set programmatically, and the implicit timezone is taken from this value.

11. The default collection is implementation-defined. (See 5.3.3.2 Other Components of the XPath Dynamic Context)

    ► A default collection name may be defined at Configuration level; this is then resolved in the same way as any other collection URI.

12. Streamed processing may be initiated by invoking the transformation with an initial mode declared as streamable, while supplying the initial match selection (in an implementation-defined way) as a streamed document. (See 6.6.4 Streamable Templates)

    ► If the initial mode is streamable, then for streaming to take place, the source document must be supplied as a StreamSource or SAXSource.

13. The mechanism by which the caller supplies a value for a stylesheet parameter is implementation-defined. (See 9.5 Global Variables and Parameters)

    ► In s9api, use Xslt30Transformer.setStylesheetParameters(). In JAXP, use Transformer.setParameter(). On the command line, use a name=value pair as a command line option.

14. The detail of any external mechanism allowing a processor to enable or disable checking of assertions is implementation-defined. (See 23.2 Assertions)

    ► On the command line, use the -ea option to enable assertion checking. In s9api, assertions must be enabled at compile time using XsltCompiler.setAssertionsEnabled(true); if required they can then be disabled at evaluation time using Xslt30Transformer.setAssertionsEnabled(false).

15. The way in which the results of the transformation are delivered to an application is implementation-defined. (See 25 Transformation Results)

    ► Results are delivered to a user-supplied OutputURIResolver. The default OutputURIResolver serializes result trees to files in filestore.

16. It is implementation-defined how the URI appearing in the href attribute of xsl:result-document affects the way in which the result tree is delivered to the application. There may be restrictions on the form of this URI. (See 25.1 Creating Secondary Results)

    ► This can be customized by use of a user-supplied OutputURIResolver. By default, result documents are serialized to files in filestore, which implies that the URIs must use the file URI scheme.

17. If serialization is supported, then the location to which a final result tree is serialized is implementation-defined, subject to the constraint that relative URI references used to reference one tree from another remain valid. (See 26 Serialization)

    ► This can be customized by use of a user-supplied OutputURIResolver. By default, result documents are serialized to files in filestore, which implies that the URIs must use the file URI scheme.

F.2 Vendor and User Extensions

This category covers extensions and extensibility: mechanisms for providing vendor or user extensions to the language without sacrificing interoperability.

In general terms, it is implementation-defined:

• whether and under what circumstances the implementation recognizes any extension functions, extension instructions, extension attributes, user-defined data elements, additional types, additional serialization methods or serialization parameters, or additional collations, and if so, what effect they have.

  ► Extensions implemented by the Saxon processor are documented at Extensions.

• whether, how, and under what circumstances the implementation allows users to define extension functions, extension instructions, extension attributes, user-defined data elements, additional types, additional serialization methods or serialization parameters, or additional collations. If it does allow users to do so, it must follow the rules given elsewhere in this specification.

  ► Mechanisms provided by the Saxon processor for implementing extension functions and extension instructions are documented at Extensibility. Mechanisms for extending the serialization capability are available via the method Configuration.setSerializerFactory(). Collations can be defined at configuration level either by registering individual collations using Configuration.registerCollation(), or by supplying a user-written CollationURIResolver.

• what information is available to such extensions (for example, whether they have access to the static and dynamic context.)

  ► Some of the mechanisms for implementing extension instructions and extension functions provide the implementation of the instruction or function with information about the static and dynamic context.

• where such extensions are allowed, the extent to which the processor enforces their correct behaviour (for example, checking that strings returned by extension functions contain only valid XML characters)

  ► By default the results of extensions are checked, but the implementation of an extension can assert that the result is to be trusted.

More specifically:

1. The mechanisms for creating new extension instructions and extension functions are implementation-defined. It is not required that implementations provide any such mechanism. (See 2.8 Extensibility)

   ► Mechanisms provided by the Saxon processor for implementing extension functions and extension instructions are documented at Extensibility.

2. The set of namespaces that are specially recognized by the implementation (for example, for user-defined data elements, and extension attributes) is implementation-defined. (See 3.7.3 User-defined Data Elements)

   ► Saxon recognizes the namespace http://saxon.sf.net/ for its own extensions; it also recognizes extensions in various namespaces defined by the EXSLT and EXPath communities.

3. The effect of user-defined data elements whose name is in a namespace recognized by the implementation is implementation-defined. (See 3.7.3 User-defined Data Elements)

   ► Saxon only recognizes user-defined data elements in the namespace http://saxon.sf.net/. Any other user-defined data elements are ignored.

4. An implementation may define mechanisms, above and beyond xsl:import-schema, that allow schema components such as type definitions to be made available within a stylesheet. (See 3.14 Built-in Types)

   ► Saxon allows schemas to be loaded into the configuration in a number of ways, but type definitions can generally be used in a stylesheet only if the namespace is explicitly imported using xsl:import-schema. The exception is types corresponding to external Java objects: every Java class on the classpath has a corresponding named external type definition which is implicitly imported.

   ► If syntax extensions are enabled, Saxon allows union types to be defined inline using syntax such as union(xs:date, xs:dateTime) anywhere that an ItemType is expected.

5. The set of extension functions available in the static context for the target expression of xsl:evaluate is implementation-defined. (See 10.4.1 Static context for the target expression)

   ► All extension functions available within a stylesheet are also available in XPath expressions dynamically evaluated using xsl:evaluate.

6. If the data-type attribute of the xsl:sort element has a value other than text or number, the effect is implementation-defined. (See 13.1.2 Comparing Sort Key Values)

   ► No additional values are recognised.

7. The posture and sweep of extension functions (and references to extension functions) and extension instructions are implementation-defined. (See 19.8.4.2 Streamability of extension instructions)

   ► Extension functions and instructions are not streamable, with the exception of the saxon:stream() extension function.

8. Additional streamability categories for stylesheet functions may be defined by an implementation. (See 19.8.5 Classifying Stylesheet Functions)

   ► No additional categories are recognized for streamable stylesheet functions.

9. The effect of an extension function returning a string containing characters that are not permitted in XML is implementation-defined. (See 24.1.2 Calling Extension Functions)

   ► The results are not checked.

10. The way in which external objects are represented in the type system is implementation-defined. (See 24.1.3 External Objects)

    ► In addition to nodes, atomic values, and functions, Saxon supports a fourth kind of item: the external Java (or .NET) object. The value of such an item is simply a wrapper for the external object. These have types which correspond to the Java or .NET class hierarchy.

F.3 Localization

This specification, and the specifications that it refers to, include facilities for adapting the output of a transformation to meet local expectations: examples include the formatting of numbers and dates, and the choice of collations for sorted output. The general principles are:

• The specification does not mandate any particular localizations that processors must offer: for example, a conformant processor might choose to provide output in Japanese only.

• The specification provides fallback mechanisms so that if a particular localization is requested and is not available, processing does not fail.

More specifically:

1. The combinations of languages and numbering sequences recognized by the xsl:number instruction, beyond those defined as mandatory in this specification, are implementation-defined. There may be implementation-defined upper bounds on the numbers that can be formatted using any particular numbering sequence. There may be constraints on the values of the ordinal attribute recognized for any given language. (See 12.4 Number to String Conversion Attributes)

   ► Saxon uses the ICU-J library for localization. This offers a large and extensible set of languages. The numbering sequences recognized are listed at xsl:number.

2. The facilities for defining collations and allocating URIs to identify them are largely implementation-defined. (See 13.1.3 Sorting Using Collations)

   ► Mechanisms provided by the Saxon processor for implementing extension functions and extension instructions are documented at Extensibility. Mechanisms for extending the serialization capability are available via the method Configuration.setSerializerFactory(). Collations can be defined at configuration level either by registering individual collations using Configuration.registerCollation(), or by supplying a user-written CollationURIResolver.

3. The algorithm used by xsl:sort to locate a collation, given the values of the lang and case-order attributes, is implementation-defined. (See 13.1.3 Sorting Using Collations)

   ► If these attributes are present then the Unicode Collation Algorithm is used, selected by a collation URI that incorporates these two parameters.

4. If none of the collation, lang, or case-order attributes is present (on xsl:sort), the collation is chosen in an implementation-defined way. (See 13.1.3 Sorting Using Collations)

   ► By default, Unicode codepoint collation is used.

5. When using the family of URIs that invoke the Unicode Collation Algorithm, the effect of supplying a query keyword or value not defined in this specification is implementation-defined. The defaults for query keywords are also implementation-defined unless otherwise stated. (See 13.4 The Unicode Collation Algorithm)

   ► By default, unrecognized parameters are ignored.

F.4 Optional Features

As well as the optional conformance features identified in 27 Conformance, some specific features of the specification are defined to be optional.

1. It is implementation-defined whether an XSLT 3.0 processor supports backwards compatible behaviour for any XSLT version earlier than XSLT 3.0. (See 3.9 Backwards Compatible Processing)

   ► XSLT 1.0 and XSLT 2.0 backwards compatibility are supported as defined in the W3C specification, in Saxon-HE from 9.8.0.7, or for earlier versions of 9.8 in Saxon-PE and Saxon-EE only.

2. If an xml:id attribute that has not been subjected to attribute value normalization is copied from a source tree to a result tree, it is implementation-defined whether attribute value normalization will be applied during the copy process. (See 11.9.1 Shallow Copy)

   ► Attribute value normalization is applied.

3. It is implementation-defined whether, and under what circumstances, disabling output escaping is supported. (See 26.2 Disabling Output Escaping)

   ► Disable-output-escaping is supported provided that the result tree is being serialized, and that no xsl:try or xsl:fork instruction is in effect.

F.5 Dependencies

When this specification refers normatively to other specifications, it generally gives implementations freedom to decide (within constraints) which version of the referenced specification should be used. Specifically:

1. It is implementation-defined which versions and editions of XML and XML Namespaces (1.0 and/or 1.1) are supported. (See 4.1 XML Versions)

   ► Both 1.0 and 1.1 are supported provided support is available from the chosen XML parser. XML 1.1 is available only if explicitly requested.

2. It is implementation-defined which versions of XML, HTML, and XHTML are supported in the version attribute of the xsl:output declaration. (See 26 Serialization)

   ► XML 1.0 and 1.1 are supported; HTML 4 and 5 are supported; XHTML 1 and 5 are supported.

3. It is implementation-defined whether (and if so how) an XSLT 3.0 processor is able to work with versions of XPath later than XPath 3.1. (See 27 Conformance)

   ► The question does not yet arise.

4. It is implementation-defined whether (and if so how) an XSLT 3.0 processor is able to work with versions of [XSLT and XQuery Serialization] later than 3.1. (See 27.3 Serialization Feature)

   ► The question does not yet arise.

F.6 Defaults and Limits

To accommodate variations in the way that the XSLT language is deployed, and the constraints of different processing environments, defaults for some options are implementation-defined. In addition, limits on the sizes of ranges of values permitted are in general implementation-defined:

1. Limits on the value space of primitive datatypes, where not fixed by [XML Schema Part 2], are implementation-defined. (See 4.8 Limits)

   ► For integers, decimals, and strings, the only limits imposed by Saxon are those inherent in the underlying Java types BigInteger, BigDecimal, and String.

   For calendar data types, the year must be in the range of a signed 32-bit integer; seconds are supported to a fractional precision of six digits (that is, microsecond precision).

   For durations, the number of months must fit in a signed 32-bit integer; the integer number of seconds must fit in a signed 64-bit integer, and the precision is to microseconds.

   The maximum length of a sequence (or array) is limited to 2³¹-1 items.

2. The default value of the encoding attribute of the xsl:output element is implementation-defined. Where the encoding is UTF-8, the default for the byte-order-mark attribute is implementation-defined. (See 26 Serialization)

   ► The default encoding is UTF-8; by default, no byte order mark is written.

F.7 Detection and Reporting of Errors

Some aspects of error handling are implementation-defined:

1. It is implementation-defined whether type errors are signaled statically. (See 2.12 Error Handling)

   ► Type errors are signaled statically where the intersection of the required type and the (statically-inferred) supplied type is empty.

2. If the effective version of any element in the stylesheet is not 1.0 or 2.0 but is less than 3.0, the recommended action is to report a static error; however, processors may recognize such values and process the element in an implementation-defined way. (See 3.9 Backwards Compatible Processing)

   ► Saxon reports a warning and treats the value as 2.0.

3. The default values for the warning-on-no-match and warning-on-multiple-match attributes of xsl:mode are implementation-defined. (See 6.6.1 Declaring Modes)

   ► The default values are no and yes respectively.

4. The form of any warnings output when there is no matching template rule, or when there are multiple matching template rules, is implementation-defined. (See 6.6.1 Declaring Modes)

   ► The warning, by default, consists of an explanatory English-language message sent to the system error output; both the form of the message and its destination may be customized.

5. The destination and formatting of messages written using the xsl:message instruction are implementation-defined. (See 23.1 Messages)

   ► By default messages are serialized as XML and sent to the system error output; both the form of the message and its destination may be customized.