XML Schema and DTD

## The symptom Split a chimney-sweep schedule schema across three files — `sweep-schedule.xsd` importing `flue-types.xsd` and `common-types.xsd` — and an assertion that worked against a single-file schema stops working: ```java get("/sweep-schedule").then().body(matchesXsd(schemaAsString)); ``` What you get is not a body-mismatch report. It is a schema **compilation** failure, raised before the response body is examined at all, complaining that the schema document at `flue-types.xsd` could not be read or that a type in the `flues` namespace cannot be resolved. ## Why the import cannot resolve `XmlXsdMatcher.matches` does four things: 1. `SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI)` 2. `factory.setResourceResolver(resolver)` — only if one was supplied 3. `factory.newSchema(source)` — compile the schema 4. `schema.newValidator().validate(...)` — run it over the response body Step 3 is where a multi-file schema dies. The `String`, `Reader` and `InputStream` overloads wrap what you passed in a `StreamSource` with **no system id**. `xsd:import schemaLocation="flue-types.xsd"` is a *relative* reference, and a relative reference needs a base URI to be relative *to*. Without a system id there is no base URI, so the compiler has nowhere to look. A few things that feel like they should help, and do not: - `matchesXsdInClasspath(...)` is no safer — it opens a bare classpath `InputStream` and calls the `InputStream` overload, so it has exactly the same missing base URI. - Putting the imported files next to the main one on the classpath changes nothing, because nothing tells the compiler that the classpath is the place to look. - `XmlConfig` settings are irrelevant here; the matcher builds its own factory and never reads them. ## The hook that fixes it `XmlXsdMatcher` — and only `XmlXsdMatcher` — carries the escape hatch: - `using(LSResourceResolver resourceResolver)` - `with(LSResourceResolver resourceResolver)`, an alias that delegates straight to `using` Both return a **new** `XmlXsdMatcher` over the same schema source with the resolver attached; neither mutates the matcher you called it on. Two practical consequences follow. First, chain the call directly on the factory method — `matchesXsd(source).using(resolver)` — rather than calling `using` on a variable and throwing the result away. Second, if you do split it across statements, declare the variable as `XmlXsdMatcher`, not `Matcher<String>`, or the `using` call will not compile. ## Writing the resolver `org.w3c.dom.ls.LSResourceResolver` has one method: ```java LSInput resolveResource(String type, String namespaceURI, String publicId, String systemId, String baseURI); ``` The pieces you actually use: - `systemId` is the raw `schemaLocation` text — `flue-types.xsd` — which is normally the key you look the file up by. - `namespaceURI` is the imported schema's target namespace, a more robust key when file names are not stable. - The return value is an `LSInput`; supply the bytes through `setByteStream(...)` or the characters through `setCharacterStream(...)`, and set the system id so nested references have somewhere to hang off. - Returning `null` means "fall back to default resolution", which is the behaviour that already failed, so a resolver that returns `null` for the file you need fixes nothing. The library's own integration test builds exactly this: a resolver whose `LSInput.getByteStream()` loads `systemId` through the thread context classloader, attached with `.with(...)`. ## What has no hook at all | Matcher | Declared return type | Resolver hook | |---|---|---| | `matchesXsd(...)` | `XmlXsdMatcher` | `using(...)` / `with(...)` | | `matchesXsdInClasspath(...)` | `XmlXsdMatcher` | same | | `matchesDtd(...)` | `Matcher<String>` | none | | `matchesDtdInClasspath(...)` | `Matcher<String>` | none | That asymmetry is deliberate in effect if not in intent: the DTD matcher hands its work to a validating `DocumentBuilderFactory` with no resolver plumbed through, so a DTD that pulls in another file by a relative system id has nothing to resolve it with. If your document contract is genuinely multi-file, XSD is the side of this leaf that can be made to work. ## Keeping it boring If you never want to write an `LSResourceResolver` at all, the alternatives are structural: - Keep the imported schemas in one classpath folder and key the resolver on the file name once, in a shared helper, rather than per test. - Hand `matchesXsd` a `File` whose parent directory holds the imports, so the source carries a real system id and relative locations resolve on their own. - Or flatten the schema for test purposes, accepting that the flattened copy can drift from the one the service publishes — which is usually the reason teams write the resolver instead.