Catalogs in Strict Mode

TL;DR Always use non-strict mode (<strict>false</strict>) with catalogs.

XJC has a so-called strict mode which is enabled by default (but can be disabled by the -nv command-line option).

It is not exactly documented, what the strict does. The best description can be found in the XJC documentation:

By default, xjc performs strict validation of the source schema before processing. Note that this does not mean the binding compiler will not perform any validation; it simply means that it will perform less-strict validation.

In a series of tests we have found out that in strict and non-strict modes schema documents are parsed differently. Strict mode uses the javax.xml.validation.SchemaFactory and non-strict mode the javax.xml.parsers.SAXParserFactory. Unfortunately these two methods have some fine differences in the usage of the entity resolvers. For instance, there's an issue that in non-strict mode the namespace of the imported schema is not used as publicId.

From the other side, it seems like in the strict mode some URIs are passed to the resolver as relative URIs and in the non-strict mode as absolute URLs. Consider the following resolution in the strict mode:

[DEBUG] Resolving publicId [http://www.opengis.net/gml/3.2], systemId [dynamicFeature.xsd].
resolveSystem(dynamicFeature.xsd)
resolvePublic(http://www.opengis.net/gml/3.2,dynamicFeature.xsd)
[DEBUG] Parent resolver has resolved publicId [http://www.opengis.net/gml/3.2], systemId [dynamicFeature.xsd] to [null].
[DEBUG] SystemId [dynamicFeature.xsd] is not a Maven dependency resource URI. Returning parent resolver result [null].

And the same resolution in the non-strict mode:

[DEBUG] Resolving publicId [null], systemId [http://schemas.opengis.net/gml/3.2.1/dynamicFeature.xsd].
resolveSystem(http://schemas.opengis.net/gml/3.2.1/dynamicFeature.xsd)
Resolved system: http://schemas.opengis.net/gml/3.2.1/dynamicFeature.xsd
	file:/.../src/main/resources/schema/gml/3.2.1/dynamicFeature.xsd
[DEBUG] Parent resolver has resolved publicId [null], systemId [http://schemas.opengis.net/gml/3.2.1/dynamicFeature.xsd] to [file:/.../src/main/resources/schema/gml/3.2.1/dynamicFeature.xsd].
[DEBUG] SystemId [file:/.../src/main/resources/schema/gml/3.2.1/dynamicFeature.xsd] is not a Maven dependency resource URI. Returning parent resolver result [file:/.../src/main/resources/schema/gml/3.2.1/dynamicFeature.xsd].

You may note that strict mode has a relative URI dynamicFeature.xsd whereas non-strict mode an absolute URI http://schemas.opengis.net/gml/3.2.1/dynamicFeature.xsd as systemId.

Since the base URI for the resolution is not provided, it is critical that entity resolver gets the absolute URI. In the first case above the URI dynamicFeature.xsd was not resolved by the catalog and in the second case the URI http://schemas.opengis.net/gml/3.2.1/dynamicFeature.xsd was correctly resolved by the following catalog rule:

<rewriteSystem systemIdStartString="http://schemas.opengis.net/gml/3.2.1" rewritePrefix="../schema/gml/3.2.1"/>	

So if you use catalogs to resolve schema URIs, using the strict mode at the same time may lead to resolution errors which in some cases won't even be noticed (schema document will be retrieved via unresolved URI from the web). These errors are not quite predictable and may even break builds randomly - depending on whether the target resource is available, if you're online or offline and so on.

To avoid such situations, disable strict mode when you use catalogs. Add the following configuration element to your build:

<strict>false</strict>

Starting from the version 0.12.0 the plugin will display a warning message if catalogs and strict mode are used at the same time.