0.7.1 Is out: A Step to Making SOAP less painful ;)

[sergeliatko]

Pipeline vision:
Old WSDL → Typed TypeScript Client → Deterministic OpenAPI → (Next) Generated REST Wrapper → Automate & Repeat

Many teams (like ours) still sit on contract-heavy SOAP endpoints that aren’t going away overnight. What we do need:

• Type safety to reduce integration mistakes
• A stable REST-friendly surface for consumers who don’t want to touch SOAP
• Predictable artifacts that can flow into CI/CD, gateways, policy layers, and eventually automation

---

What’s new in 0.7.1

1. Always‑on Standard Response Envelope

Every operation response now lives inside a consistent envelope: status, message, data, error.

Why? REST wrapper generation and gateway policies (logging, error mapping, correlation IDs) are easier when shapes converge early.

2. Deterministic OpenAPI output

Alphabetical ordering of:

• paths
• methods
• schemas (including added envelope + extensions)
• securitySchemes
• parameters
• operation tag arrays

Cleaner diffs; safer automation (e.g., detecting meaningful schema shifts).

3. Stability & polish

• Default server / when none provided
• Omit unnecessary jsonSchemaDialect to reduce IDE noise
• Collision‑aware namespace concatenation (adds underscore when needed)

---

Why the envelope matters for modernization

If you’re planning to stand up a REST façade (or serverless proxy) over a SOAP backend, you eventually need:

• A uniform HTTP response contract
• A hook for correlation IDs, timing, pagination, policy outcomes
• A single place to map SOAP faults → consistent error object

Adding the envelope now avoids a future breaking change once wrapper generation lands.

---

Example

Success

{
  "status": "SUCCESS",
  "message": null,
  "data": { "...": "Payload fields" },
  "error": null
}

Error

{
  "status": "FAILURE",
  "message": "Upstream timeout",
  "data": null,
  "error": {
    "code": "TIMEOUT",
    "message": "Upstream service did not respond",
    "details": { "elapsedMs": 5021 }
  }
}

---

Upgrade impact

• Always on; no flag needed
• If you parsed raw payloads directly, now read data
• Customize naming with:
  • --envelope-namespace CustomEnvelope
  • --error-namespace Problem
• Underscore injection prevents accidental suffix collisions

---

Current pipeline (today)

1. Compile WSDL → internal catalog
2. Emit TypeScript client + types
3. Generate OpenAPI 3.1 (stable ordering)
4. (You are here) Envelope + diff‑friendly output
5. (Upcoming) REST wrapper scaffolding (Express / Fastify / H3 / Lambda?)
6. (Later) Policy + fault mapping helpers
7. (Later) Multi‑WSDL batch automation

---

Roadmap slice (0.7.x → 0.8.x)

Track	Goal
0.7.x	Harden OpenAPI fidelity, refine envelope shaping, gather edge cases
0.8.x	Prototype REST wrapper generation
0.9.x	Gateway profile emission (auth, correlation, logging)
1.0	Repeatable modernization pipeline

---

Feedback wanted

• Need an opt‑out for the envelope? (Default stance: keep always‑on unless strong friction emerges.)
• Preferred framework for first wrapper: Express, Fastify, H3, Lambda flavor?
• SOAP fault extension patterns you rely on?
• Any naming collisions despite underscore guard?

---

Quick generate reminder

wsdl-tsc openapi --wsdl ./examples/minimal/weather.wsdl --out ./tmp/openapi --format both

---

Changelog reference

See [0.7.1] – 2025-09-23 in CHANGELOG.md.

---

Short variant (for social / brief Discussion)

0.7.1 shipped: always‑on response envelope + deterministic OpenAPI. Stabilizes modernization loop: WSDL → TS client → OpenAPI → (next) REST wrapper. Envelope = consistent status/data/error for future gateway & fault mapping. Feedback: preferred wrapper framework? need envelope opt‑out? fault mapping needs?

— TechSpokes

[sergeliatko]

@GerryWilko any feedback is welcome
Thanks