If XJC cannot resolve an imported schema, an XML catalog can redirect the schema reference to a local or otherwise accessible copy without changing the upstream XSD. The catalog controls where XJC retrieves a dependency; a JAXB external binding file controls how schema components map to Java.
How XJC resolves imported schemas
XJC is the schema-to-Java compiler in the Jakarta XML Binding toolchain: it generates Java source from XML Schema definitions. JAXB also includes APIs for marshalling, unmarshalling, and validation, but those runtime functions are separate from XJC’s source-generation step. The Jakarta XML Binding API description summarizes the broader binding role at Jakarta XML Binding 4.0.
An xs:import or other schema reference creates a dependency XJC must locate while compiling. By default, a schema may point to a remote URL or to a relative location that no longer works in a developer or CI environment. The JAXB RI’s catalog resolver checks for an alternate location before XJC fetches a resource, allowing you to redirect lookup without editing the imported schema. See the JAXB RI 4.0.5 catalog resolver documentation.
Choose the right catalog match key
The two common line-based catalog declarations are SYSTEM and PUBLIC. Use the one that corresponds to the identifier XJC can match, rather than assuming the text written in schemaLocation is itself the lookup key.
| Entry | What it matches | Useful when |
|---|---|---|
SYSTEM |
An absolute resource reference derived by XJC. | The schema reference resolves to a known system location, such as a URL or absolute file path. |
PUBLIC |
A public identifier, or an xs:import namespace URI. |
The dependency is identified by its namespace, including an import without a schemaLocation. |
For example, the RI guide shows these declaration forms:
SYSTEM "http://www.w3.org/2001/xml.xsd" "xml.xsd"
PUBLIC "http://www.w3.org/1999/xlink" "http://www.w3.org/2001/xlink.xsd"If an XSD contains schemaLocation="xlink.xsd", XJC first resolves that relative reference against the importing schema and matches using the resulting absolute reference. A SYSTEM key containing only xlink.xsd may therefore fail to match. Catalog targets, by contrast, can be relative to the catalog file, which helps keep a project’s catalog portable when its schema files move together.
Rank #2
Create a catalog for a failing import
- Identify the failing dependency. Find the importing schema and its
xs:import,xs:include, or other external reference. Note both the namespace and theschemaLocation, if present. - Determine the resolved identifier. For a relative location, establish the absolute system reference XJC derives from the importing schema. For namespace-based matching, check whether a
PUBLICentry for the namespace is more appropriate, especially if noschemaLocationis given. - Add a catalog mapping. Point the matching identifier to the local schema copy. If the target is relative, calculate it from the catalog file’s directory—not from the working directory where XJC happens to run.
- Pass the catalog to the same compiler invocation that processes the schemas. The catalog has no effect if it exists in the repository but is not configured in the build.
- Run generation again and inspect resolver diagnostics if it still fails. Confirm that the match key and target are the ones XJC is actually using.
Pass the catalog to XJC or your build
Direct XJC command line
For direct compiler use, pass the catalog with -catalog:
xjc -catalog path/to/catalog.cat path/to/schema.xsdThe JAXB RI 4.0.5 guide documents this option and catalog formats. Use command syntax appropriate to the XJC distribution installed in the project; compiler packaging and invocation can vary across toolchains.
Ant
The RI’s Ant task accepts a catalog attribute. Configure it on the XJC task so the catalog is available during generation, and check the task documentation corresponding to the RI version used by the build.
Maven
The RI guide includes a Maven example with a <catalog> setting for org.jvnet.jaxb2.maven2:maven-jaxb2-plugin. Treat that as an example for that plugin, not a universal Maven setting: verify the plugin coordinates, configuration element, and version actually used by your project. A different plugin may expose a different configuration or invoke XJC differently.
Rank #4
Debug “XJC cannot resolve imported schema” errors
Check these points in order so you can distinguish a missing match from a bad target or an omitted build setting:
- Reference: identify which import or include XJC attempts to resolve; the file mentioned in the error may be a transitive dependency rather than the schema you started with.
- System ID: for a relative
schemaLocation, determine the absolute reference after resolution. Compare that value—not just the relative spelling—to the catalog’sSYSTEMkey. - Namespace match: if the import has a namespace but no
schemaLocation, check for a matchingPUBLICentry. - Catalog target: verify that the target file exists and that any relative target is correct from the catalog file’s location.
- Build wiring: confirm the actual command, Ant task, or Maven plugin invocation passes the catalog used by the generation step.
- Resolver logging: the RI documents
-Dxml.catalog.verbosity=999for verbose catalog diagnostics. How to provide that property depends on the interface launching XJC; set it on the relevant Java process or task, not as an XJC schema argument.
Keep XML catalogs separate from JAXB bindings
A catalog redirects resource retrieval. It does not rename generated classes, change property mappings, or otherwise customize the Java model. Those are jobs for JAXB binding customizations.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →An external binding file identifies a schema with schemaLocation, selects schema components using an XPath 1.0 node expression, and is supplied to XJC with -b. The Oracle tutorial explains the general structure in Customizing JAXB Bindings. Its examples use a legacy JAXB namespace; for a Jakarta-era project, use the Jakarta binding namespace and version form documented in the JAXB RI 4.0.5 documentation, rather than copying an old descriptor header unchanged.
Check compiler and generated-code compatibility
Match documentation and binding syntax to the XJC compiler you actually run. The Eclipse Implementation of JAXB 4.0.5 requires Java SE 11 or higher and identifies org.glassfish.jaxb:jaxb-xjc as the source-generation tool. The RI 4.0.5 release documentation also describes migration from JAXB 1.x/2.x to Jakarta: update javax.xml.bind references to jakarta.xml.bind, regenerate sources with a newer XJC, and adapt application code to the new bindings.
The Jakarta XML Binding 4.0 release page likewise lists Java SE 11 or higher and says compatibility with JAXB 1.0 was dropped. Do not confuse the API artifact with the compiler: the API provides binding interfaces, while XJC is supplied by a compiler/tool artifact such as org.glassfish.jaxb:jaxb-xjc.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches
