WSDL Parser and Analyzer

Overview

The WSDL Parser is a component responsible for parsing and analyzing Web Services Definition Language (WSDL) 1.1 documents. It is a foundational part of the API onboarding process for SOAP-based services.

The parser's primary function is to ingest a WSDL file, either as a single XML document or as a set of interconnected documents via wsdl:import and xsd:import/include, and extract a structured representation of the SOAP service. This includes:

• API Operations: The available functions in the service, derived from wsdl:portType/wsdl:operation elements.
• Data Contracts: The request and response message schemas for each operation.
• Backend Configuration: Suggested backend endpoint URLs, SOAP version, and transport protocols found in wsdl:service and wsdl:binding definitions.
• Security Policy Hints: Inferred authentication requirements (e.g., WS-Security, HTTP Basic) based on WS-Policy assertions within the WSDL.

The parser is designed to be robust, with built-in support for repairing common WSDL syntax issues, securely fetching external dependencies, and providing detailed diagnostics to the API publisher. It produces a WsdlParsedDocument object that serves as the input for configuring a SOAP-to-REST API.

How it Works

The parsing process involves several stages, from initial XML processing to the final extraction of service metadata. The parser can be invoked to perform a full parse or to preview specific aspects like namespace repairs or external references.

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

    subgraph WSDL Parser
        B --> C{Analyze & Repair XML};
        C --> D{Discover External Files?};
        D -- Yes --> E[Fetch External WSDL/XSD];
        D -- No --> F;
        E --> F[Merge All Documents];
        F --> G[Extract Operations & Schemas];
        F --> H[Extract Backend Configuration];
    end

    subgraph Secure Fetch
        style E fill:#f9f,stroke:#333,stroke-width:2px
        E -- "HTTP/HTTPS GET" --> I(SSRF Egress Guard);
        I -- "Validate URL" --> J(Backend SOAP Service);
    end

    G --> K(Operation & Schema Definitions);
    H --> L(Backend Endpoint & Auth Suggestions);

    subgraph "Parser Output"
        K
        L
    end

1. XML Pre-processing and Security

Before parsing, the WSDL input undergoes several normalization steps:

1. Character Encoding Repair: The parser corrects "mojibake" (e.g., UTF-8 content misinterpreted as Latin-1) to ensure correct handling of non-ASCII characters.
2. BOM Stripping: A leading Byte Order Mark (BOM, U+FEFF), often present in files from Windows-based systems, is removed to prevent XML parsing errors.
3. Namespace Repair: The parser attempts to automatically add missing namespace declarations for common WSDL, SOAP, and XSD schemas using WsdlNamespaceRepairSupport. This fixes many validation errors in non-compliant WSDLs.
4. Secure Parsing: The XML is parsed using a security-hardened DocumentBuilderFactory that disables DTDs and external entity resolution to prevent XXE (XML External Entity) attacks.

2. External Reference Resolution

WSDLs often split definitions across multiple files using wsdl:import, xsd:import, xsd:include, and xsd:redefine. The parser recursively discovers and fetches these external documents.

• Discovery: It scans the main WSDL for location attributes on import/include elements.
• Fetching: For each http or https URL, a secure fetch is initiated.
  • SSRF Protection: All outbound requests are routed through an OperatorUrlGuard, which enforces egress policies to prevent Server-Side Request Forgery (SSRF) attacks.
  • Redirects: HTTP redirects are not followed automatically. The guard validates each hop in a redirect chain to prevent redirection to blocked internal addresses.
  • Timeouts: Requests have a 5-second connection timeout and a 20-second read timeout.
• Merging: The content of successfully fetched external WSDLs and XSDs is merged into the main document's DOM under the <wsdl:types> element, creating a single, complete definition for subsequent processing.

3. Metadata Extraction

With a complete WSDL DOM, the parser uses XPath and direct DOM traversal to extract service details.

• Backend Suggestions (readBackendSuggestion):

  • It scans wsdl:service/wsdl:port/soap:address to find candidate endpoint URLs.
  • It analyzes wsdl:binding elements to determine the SOAP version (1.1 or 1.2), transport protocol (e.g., http://schemas.xmlsoap.org/soap/http), and binding style (document or rpc).
  • It infers authentication hints (inferBackendAuthHint) by scanning for WS-Policy keywords like UsernameToken, PasswordDigest, and X509Token.
  • It generates diagnostic notes about capabilities (e.g., MTOM, WS-Addressing) and structural issues (e.g., non-SOAP bindings, use of RPC/encoded style).

• Operations (parse):

  • The parser iterates through each <wsdl:portType>/<wsdl:operation>.
  • For each operation, it resolves the soapAction, binding style, headers, and faults. This resolution is keyed by (portTypeName, operationName) to correctly handle WSDLs with multiple port types that share operation names.
  • The bindingStyle (document vs. rpc) is determined before schema generation, as it affects how the request and response payloads are structured.
  • The WsdlContractBuilder is used to generate JSON Schema representations for the operation's request and response messages.

The final result is a WsdlParsedDocument containing a list of WsdlOperationRecord objects and a WsdlBackendSuggestionRecord.

Public API

The WsdlParser exposes several public methods for parsing and analyzing WSDL documents.

Methods

Return Types

The parser methods return structured records that encapsulate the analysis results.

WsdlParsedDocument

The primary output of the parse method.

WsdlOperationRecord

Represents a single SOAP operation.

NamespaceRepairPreview

Returned by previewNamespaceRepair to show the results of automatic namespace correction.

ExternalReferencePreview

Returned by previewExternalReferences to provide a detailed report on external WSDL/XSD dependencies.

| Field | Type | Description

All SOAP-to-REST docs