WSDL Parsing and Analysis

Overview

The WSDL Parser is a component responsible for parsing, analyzing, and interpreting Web Services Definition Language (WSDL) 1.1 documents. It serves as the primary mechanism for onboarding SOAP-based services by extracting the necessary metadata to configure the API platform.

The parser's main function is to take a raw WSDL XML document, either as a string or from a URL, and produce a structured representation of the service contract. This includes:

• Operations: A list of all available SOAP operations.
• Data Contracts: JSON Schema representations of the request and response message structures for each operation.
• Backend Configuration: Suggestions for the backend endpoint URL, SOAP version, and authentication type.
• External References: Resolution and merging of external WSDL and XML Schema Definition (XSD) files referenced via wsdl:import or xsd:import/include.

The parser is called during the API creation process when an API publisher imports a WSDL file. It is designed to be robust, secure, and provide detailed diagnostics to help publishers understand and troubleshoot their WSDL definitions.

How it Works

The WSDL parsing process involves several distinct stages, from initial XML processing to the final extraction of service metadata. The parser is designed to handle complex WSDLs that are split across multiple files.

flowchart TD
    A[API Publisher provides WSDL XML] --> B(WsdlParser);

    subgraph "Parser Processing Stages"
        direction TD
        B --> C[1. Pre-process & Repair];
        C --> D[2. Parse to XML Document];
        D --> E{Has External Refs?};
        E -- Yes --> F[3. Fetch & Merge Refs];
        E -- No --> G[4. Analyze & Extract];
        F --> G;
        G --> H[5. Generate Parsed Document];
    end

    subgraph "Secure Fetch Mechanism"
        F -- "HTTP/HTTPS only" --> I[SSRF Guard];
        I --> J[HTTP Client];
        J --> K[Backend SOAP Service];
    end

    H --> L[Output: WsdlParsedDocument];

    style F fill:#f9f,stroke:#333,stroke-width:2px

1. Pre-processing and Namespace Repair

Before parsing, the WSDL XML undergoes two cleanup steps:

1. Character Encoding Repair: The parser corrects common "mojibake" encoding errors (e.g., UTF-8 content misinterpreted as Latin-1) and strips any leading Byte Order Mark (BOM U+FEFF) characters, which can cause parsing failures.
2. Namespace Repair: It automatically adds missing namespace declarations for common WSDL, SOAP, and XSD prefixes using the WsdlNamespaceRepairSupport component. This fixes many validation errors found in hand-edited or legacy WSDL files.

2. Secure XML Parsing

The cleaned XML string is parsed into a standard DOM Document object. The parser uses a security-hardened DocumentBuilderFactory with the following features to prevent common XML-based attacks:

• FEATURE_SECURE_PROCESSING is enabled.
• disallow-doctype-decl is enabled to prevent XML External Entity (XXE) attacks via <!DOCTYPE>.
• ACCESS_EXTERNAL_DTD and ACCESS_EXTERNAL_SCHEMA are disabled.

3. External Reference Resolution

WSDLs often import other WSDLs or external XML Schemas (XSDs). The parser recursively resolves and merges these external documents.

1. Discovery: It scans the main document for wsdl:import elements and all <xsd:schema> blocks for xsd:import, xsd:include, and xsd:redefine elements.
2. Resolution: For each reference, it resolves the location or schemaLocation attribute into an absolute URI. Relative paths are resolved against the base URI of the document containing the reference.
3. Secure Fetching: External documents are fetched using a dedicated, security-focused HTTP client.
   • SSRF Protection: All outbound requests are validated by an OperatorUrlGuard, which enforces egress policies to prevent Server-Side Request Forgery (SSRF) attacks. References to blocked or non-HTTP/HTTPS URLs will fail.
   • Timeout: The HTTP client has a 5-second connection timeout, and individual requests have a 20-second timeout.
   • Redirects: Automatic redirects are disabled. The OperatorUrlGuard follows each redirect hop manually and re-validates the destination URL to prevent redirect-based SSRF attacks.
4. Merging: The content of successfully fetched documents is parsed. If the document is a WSDL, its <types> are processed. If it's an XSD, the <schema> element is imported directly into the main WSDL document's <types> section. This creates a single, unified DOM for analysis.

4. WSDL Structure Analysis

With a complete and merged DOM, the parser extracts structural metadata using XPath and direct DOM traversal.

• Bindings: It identifies all wsdl:binding elements, determining their SOAP version (1.1 or 1.2), transport protocol (e.g., http://schemas.xmlsoap.org/soap/http), and binding style (document or rpc).
• Services and Ports: It finds all wsdl:service and wsdl:port elements to discover backend endpoint addresses from soap:address declarations.
• Operations: It iterates through each wsdl:portType/wsdl:operation to serve as the primary unit of extraction.
• Headers and Faults: It reads per-operation soap:header, soap:headerfault, and wsdl:fault definitions from both the wsdl:binding and wsdl:portType.

5. Contract and Suggestion Generation

For each operation, the parser assembles a complete record.

• Data Contracts: The WsdlContractBuilder is used to generate JSON Schemas for the operation's input and output messages. The binding style (rpc vs. document) is a key input to this process, as it determines whether to unwrap the top-level operation element in the SOAP Body.
• Backend Suggestions: The parser analyzes all discovered ports, bindings, and policy assertions to generate a WsdlBackendSuggestionRecord. This record recommends a preferred endpoint URL, SOAP version, and authentication type. It also includes diagnostic notes about the WSDL's structure and capabilities.
• Final Assembly: The results are compiled into a WsdlParsedDocument object, which contains the list of WsdlOperationRecords and the WsdlBackendSuggestionRecord.

API Reference

The WsdlParser component exposes several public methods for parsing and diagnostics.

Core Parsing Methods

Example Usage

// Conceptual example of invoking the parser
WsdlParser parser = new WsdlParser(/*...dependencies...*/);
String wsdlContent = "... WSDL XML content ...";
String wsdlUrl = "https://api.example.com/service?wsdl";

try {
    // Parse the WSDL, fetching external references relative to wsdlUrl
    WsdlParsedDocument parsedDoc = parser.parse(wsdlContent, wsdlUrl);
    
    // Access the extracted operations and backend suggestions
    System.out.println("Target Namespace: " + parsedDoc.getTargetNamespace());
    System.out.println("Suggested Endpoint: " + parsedDoc.getBackendSuggestion().preferredEndpointUrl());
    
    for (WsdlOperationRecord op : parsedDoc.getOperations()) {
        System.out.println("Found operation: " + op.getOperationName());
    }
} catch (WsdlParseException e) {
    System.err.println("Failed to parse WSDL: " + e.getMessage());
    // The root cause is often included for diagnosis
    if (e.getCause() != null) {
        System.err.println("Cause: " + e.getCause().getMessage());
    }
}

Diagnostic Methods

These methods help diagnose issues with a WSDL before performing a full import.

External Reference Preview

The previewExternalReferences method returns a detailed report on every external document linked from the WSDL. The report contains a list of ExternalReferenceRecord objects, each with the following fields:

• detail | String | For failed references, a message explaining the reason for failure (e.g., HTTP 404, connection timed out, blocked by SSRF egress guard). For resolved references, this is "Loaded successfully." |
• rootElement | String | The tag name of the root element of the fetched document (e.g., wsdl:definitions or xsd:schema). - | | depth | int | The recursion depth of the reference (0 for top-level, 1 for a reference within a top-level import, etc.). | | --- | --- | --- | | fileNameHint | String | A suggested filename for the referenced document, derived from its location URL. | | suggestedFix | String | An actionable suggestion for how to resolve a failed or unresolved reference, such as downloading the file manually or correcting a URL. |

Troubleshooting

When a WSDL fails to parse, the parser provides detailed error messages and diagnostics to help identify the root cause.

Exceptions

• WsdlParseException: This is the primary exception thrown for most parsing failures. The message includes a high-level summary and, crucially, a cause field containing the underlying exception. Always check the cause for specific details, such as HTTP 404 for a missing import or an XML parsing error for malformed content.
• IllegalArgumentException: Thrown for invalid inputs or conditions detected during parsing. Common causes include:
  • Root element must be wsdl:definitions: The provided XML is not a valid WSDL document.
  • No wsdl:operation elements found under wsdl:portType: The WSDL is missing the core operation definitions.
  • external reference blocked by SSRF egress guard: An import URL was blocked for security reasons.
  • unsupported schema reference scheme: An import uses a protocol other than http or https.
  • HTTP 401, HTTP 403, HTTP 404: The parser failed to fetch an external reference due to authentication, authorization, or a broken link.
• IllegalStateException: Thrown by parseWithResolvedDocuments if a required external document is not found in the provided map.

Diagnostic Notes and Warnings

The parser embeds diagnostic notes in the WsdlBackendSuggestionRecord to flag potential issues or important characteristics of the WSDL.

Other common notes include:

• Non-SOAP HTTP Bindings: A warning that ports using plain HTTP bindings (not SOAP-over-HTTP) were found and excluded from endpoint candidates.
• Namespace-only Imports: A note indicating that a wsdl:import was found with a namespace but no location. These cannot be fetched automatically and may lead to unresolved types.
• Multiple wsdl:service Elements: A note to alert the API publisher that the WSDL defines multiple services, and they should confirm which one to use.
• Capability Hints: Informational notes indicating the presence of features like WS-Addressing, MTOM/XOP attachments, or WS-Security policies. These often require careful verification during testing.

Inferred Authentication

The parser inspects the WSDL for common WS-Security Policy assertions and other markers to suggest a backend authentication type. It looks for keywords inside element names, attributes, and namespaces.

| Suggested Auth Type | Inferred From Markers Like...

All SOAP-to-REST docs