S9API interface

Schema API

Some changes have been made to the schema processing API. These arise from the fact that a Processor (and its underlying Configuration) can now hold multiple independent schemas. A schema (meaning a compiled and consistent collection of schema components) is now represented by an net.sf.saxon.s9api.XsdSchema object. This is created using a net.sf.saxon.s9api.XsdCompiler, which in turn is created using the factory method Processor.newXsdCompiler().

It is possible to continue using the old SchemaManager class rather than switching to the new XsdCompiler, but there are a few changes in behavior that may cause incompatibilities:

• The schema must be loaded in a single call of the load() method, rather than in a sequence of calls.

• The schema must be loaded before creating any SchemaValidator.

• The schema is only made available to a XsltCompiler, XQueryCompiler, or XPathCompiler that is instantiated from the Processor after the schema has been loaded.

• The schema, once loaded, is immutable. Two schemas can be combined into one (using the method XsdSchema.combine()), but the original schemas are not affected. In particular, loading additional schema components using xsi:schemaLocation attributes in an instance document will no longer affect the baseline schema used for validation.

Although Saxon now allows multiple schemas to be held in a Processor (and indeed, XSLT 4.0 allows multiple schemas to be used within a single transformation – for example one schema for the source document and another for the result document), the schemas must be consistent with each other. This primarily means that two schemas within a Processor must not hold conflicting definitions of the same component (for example, different definitions of the same complex type).

If a schema-aware stylesheet is exported to a SEF file, the SCM representation of any schema imported by the stylesheet is included in the SEF file and is automatically incorporated in any compiled stylesheet reconstituted from the SEF file.

The schemaDocument and schemaComponentModel elements in a configuration file are now deprecated and have no effect.

The handling of a schema referenced from a source document using xsi:schemaLocation or xsi:noNamespaceSchemaLocation has changed. Generally, such a schema is read only if the use of such schemas is explicitly enabled. Earlier Saxon releases read the schema at the specified location and added the relevant schema components to the schema held globally by the Configuration, changing the results of subsequent validation episodes under that Configuration. In Saxon 13, the schema constructed by reading these components is transient, and does not affect the result of any subsequent validation task.

Constructing a schema-aware type such as element(N, T) using the ItemTypeFactory now requires the ItemTypeFactory to be associated with a specific schema (which can be supplied when the factory is created).

Building a validated document tree using a DocumentBuilder now requires a SchemaValidator associated with a specific schema to be supplied.

Saxon has built-in ("born binary") schemas for the XML, XSI, and FN namespaces; when these schemas are referenced (for example in an xs:import declaration), Saxon will use its built-in copies and will ignore any schema location hint. This means it is not possible to load custom variants of these schemas. Other W3C-defined schemas, notably the XLink namespace, do allow such variation, although Saxon will load its own copy of the schema by default.

Once created, an XsdSchema object is immutable. This affects the interpretation of xs:override and xs:redefines declarations: these are now scoped to the XsdSchema in which they appear. It also affects the interpretation of other XSD features that were previously global, for example a strict wildcard (<xs:any processContents="strict"/>) will only match an element whose declaration appears in the containing XsdSchema.

Other s9api changes

Some new convenience methods have been introduced for the XdmValue and XdmStream classes. In both cases, you can now write select("name") or select("uri", "local") as a shorthand for select(Steps.child("name")) or select(Steps.child("uri", "local") respectively. For example, the expression doc.select(Steps.child("test-set").then(Steps.child("dependencies"))).first() reduces to doc.select("test-set").select("dependencies").first().

A couple of methods have been added to net.sf.saxon.s9api.ItemType. The static method ItemType.builtInAtomicType(localName) provides a quick way of getting an ItemType such as ItemType.DATE_TIME if the local name is not known statically. The method ItemType.validateAtomic(String) tests whether a given string is in the lexical space of an atomic type, and returns the corresponding atomic item if it is.

You can now set an ErrorReporter on the DocumentBuilder object.

The interface net.sf.saxon.s9api.StaticError, which was no longer used, has now been dropped from the product.

New methods checkpoint() and recover() have been added to the TraceListener interface. The default implementations do nothing. These methods are called when dynamic errors are caught using try/catch; in the case of the standard -T output, they are used to ensure that the trace output remains well-formed when errors are caught and recovered.

The callback for xsl:message processing can now request (by calling a method on the supplied Message object) that the message is to be treated as a dynamic error.