Architecture

How the pieces fit, why the schema subsystem is shaped the way it is, and where the design tensions live.

The layers

The macro-structure is a clean, idiomatic LSP stack. Each layer only talks to the one beneath it, with two exceptions noted later (diagnostics and the WASM module).

The schema subsystem

This is where the interesting design decisions live. Three collaborators:

SchemaAssociator — "which XSD?"

Maps a document to an XSD by two rules, in strict priority:

1. User associations (from settings / init options) matched by glob pattern on the file path. Init options use bundled 430/440 schemas but are still registered as user associations.
2. Built-in associations matched by XML namespace (the Synapse namespace → bundled synapse_config.xsd) only when no user pattern matched.

In the usual MI setup, path patterns choose the schema version. Namespace matching is a fallback/default route, not the primary 430/440 selection mechanism.

SchemaProvider — the registry

Holds three maps (see Caches & keys). It keeps one XsdValidatorService wrapper per unique XSD key and reuses it across every document that resolves to the same schema, and it builds the completion model from the fully-inlined XSD (via inlineIncludes()) so xs:included types are available. (The heavy grammar compilation actually happens later, inside the WASM ProjectValidator that DiagnosticsHandler owns — the wrapper itself just stores the XSD text.)

XsdCompletionProvider — the completion brain

A hand-written XSD reader (496 lines) that parses element/attribute declarations out of the XSD text and answers "what can go here?" for completion and hover. It compiles XSD rules into a flat lookup registry (Map<string, ElementInfo>) using a three-phase pipeline inside XsdCstParser:

1. Pre-Pass (prePass): Scans the top-level XSD nodes to extract and cache reusable groups (xs:attributeGroup and xs:group) in temporary maps. This allows the parser to instantly expand group contents when referenced later via ref="...".
2. Main Walk (mainWalk): Recursively walks the XSD CST. For each xs:element, it registers an ElementInfo entry, parses its xs:documentation annotations, and recursively maps inline attributes. If the element specifies a type (e.g., type="LogMediator"), it records the reference for post-walk resolution. Named xs:complexType definitions are also parsed and cached during this walk.
3. Reference Resolution (resolveReferences): Resolves type pointers by looking up the cached properties of the referenced xs:complexType definitions and merging them directly into the target elements.

<!-- Reusable attribute group -->
<xs:attributeGroup name="commonAttrs">
  <xs:attribute name="description" type="xs:string" />
</xs:attributeGroup>

<!-- Target element definition -->
<xs:element name="log" type="LogMediator" />

<!-- Type declaration -->
<xs:complexType name="LogMediator">
  <xs:sequence>
    <xs:element ref="property" />
  </xs:sequence>
  <xs:attribute name="level" type="xs:string" />
  <xs:attributeGroup ref="commonAttrs" />
</xs:complexType>

rawGroups.set("commonAttrs", {
  attrs: [{ name: "description", type: "xs:string", required: false }],
  refs: []
});

// Final compiled state in data.elements:
data.elements.get("log") == {
  name: "log",
  children: ["property"],
  attributes: [
    { name: "level", type: "xs:string", required: false },
    { name: "description", type: "xs:string", required: false }
  ]
};

The two-engine model important

This is the single most important thing to internalise. XSD semantics are interpreted twice, by two unrelated implementations, on two different paths:

Caches & keys

Four caches exist, keyed differently. Knowing the keys explains most of the behaviour.

Concretely, for a single open document those caches hold:

documentToSchema — "which schema does this document use?" (per-document)

"auto://…/test.xml" → "/resources/schemas/440/synapse_config.xsd"

validators — "the compiled XsdValidatorService for this schema" (per-schema, fallback diagnostics path)

"/…/440/synapse_config.xsd" → <compiled validator>

completionProviders — "autocomplete / hover engine for this schema" (per-schema)

"/…/440/synapse_config.xsd" → <completion provider>

projectValidators (in DiagnosticsHandler) — "the Xerces-WASM validator for this schema; primary diagnostics path" (per-schema)

"/…/440/synapse_config.xsd" → <project validator>

Note: keyed by the XSD file path (xsdPath), not the schema folder. The folder ("/…/440") is only used to gather the files map for WASM, not as the cache key — so validators and projectValidators share the same per-schema granularity.

Trade-offs & known smells

The architecture ships and all tests pass. These are the spots to watch, in rough priority:

1. Dual engine & dual schema-loading (above) — one SchemaResolver feeding both paths would collapse this.
2. DiagnosticsHandler does too much — ~half of its 453 lines (loadReferencedXsds, buildFilesMap, findSchemaLocations, resolveLocalReference) is schema-graph crawling that belongs in schema/.
3. Dead-weight validator — an XsdValidatorService is instantiated for every registered schema in registerSchema, but its validate() is only reached on a fallback path that almost never fires (built-ins/user schemas always carry an xsdPath, so diagnostics go through the WASM ProjectValidator instead). Cheap to create, but it's an unused branch carrying its own re-parsing cost if ever hit.
4. No-fallback resolution — if a user association matches but its XSD can't be read, findSchema returns null instead of falling through to the built-in schema, killing all validation for that file.
5. Namespace fallback depends on parser support — diagnostics asks for getNamespace?.(), but the current XMLDocumentImpl does not expose that method. Pattern-based associations still work.
6. Two config shapes — {pattern, schema:"430"} (init options) and {pattern, xsdPath} (settings) take two code paths to the same destination.