Skip to content

Transformers

Responsibility

Transformation capability provider for XSLT, XML↔JSON, CSV, JSON Schema, XSD, and Liquid. Workflows call it via service_call — there are no first-class xslt / xml2json / json2xml / liquid / csv step types.

Capabilities:

Capability Path
transformers.apply_xslt /applyXSLT
transformers.xml2json /xml2json
transformers.json2xml /json2xml
transformers.apply_liquid /applyLiquid
transformers.csv_to_json /csv2json
transformers.json_to_csv /json2csv
transformers.xml_to_csv /xml2csv
transformers.csv_to_xml /csv2xml
transformers.flatfile_to_xml /flatfile2xml
transformers.xml_to_flatfile /xml2flatfile
transformers.validate_json_schema /validateJsonSchema
transformers.validate_xsd /validateXsd

Architecture

Capability provider (see Deploy integration contract):

  • Registers with capability-registry at startup
  • Orchestrator discovers endpoints via the registry
  • Demo workflows: flows/workflows/transform_testing_demo.yaml, flows/workflows/csv_transform_demo.yaml, flows/workflows/xml_csv_demo.yaml, flows/workflows/flatfile_demo.yaml, flows/workflows/json_schema_validate_demo.yaml, flows/workflows/xsd_validate_demo.yaml

CSV quoting and headers

transformers.csv_to_json / json_to_csv use RFC 4180 (Python csv module), not split(delimiter).

  • Quoted delimiter in a value: id:"meshflows:runs" with delimiter: ":" is one field (path=meshflows:runs).
  • Unquoted delimiter in a value: 1:meshflows:runs is three columns. If that exceeds the header width, the call returns 400 — quote the field instead of silently dropping runs.
  • Headers: has_header (alias header) defaults to true. First row → object keys. Empty names become column_N; duplicates get a suffix (sku then sku_1). With has_header: false every row is data and keys are column_1, column_2, …

transformers.xml_to_csv (POST /xml2csv) and transformers.csv_to_xml (POST /csv2xml) are first-class capabilities. Designer: Add step → transformers → XML → CSV / CSV → XML (same list as XML → JSON). Repeating child elements become CSV rows; CSV round-trips to <rows><row>…</row></rows>. Demo: xml_csv_demo.

Flatfile (BizTalk wizard XSD, POC)

transformers.flatfile_to_xml (POST /flatfile2xml) and transformers.xml_to_flatfile (POST /xml2flatfile) convert positional or delimited lines. schema_file is either:

  • a BizTalk Flat File Schema Wizard XSD (xmlns:b, b:recordInfo / b:fieldInfo, tag identifiers, delimiters, pos_length) — compiled with the same lxml stack as validate_xsd; or
  • a compact MeshFlows JSON layout (equivalent of those annotations).

This lives on the transformers provider (same family as xml2json / csv_to_xml / validate_xsd), not a gateway policy. It is a POC, not a full FFDASM (no nested repeating groups or wrap characters).

  • Prefer including the field delimiter in the tag (HDR; not HDR), matching BizTalk guidance.
  • Demo: flatfile_demo with flows/artifacts/transforms/examples/order-flatfile.xsd (HDR/DTL/FTR order file).
  • Quoted CSV stays on csv_to_xml / xml_to_csv.

JSON Schema validation

transformers.validate_json_schema (POST /validateJsonSchema) checks a JSON instance against a schema artifact (schema_file).

  • Valid → {"valid": true} (HTTP 200).
  • Invalid → HTTP 400 with {valid: false, errors: [{path, message, validator}, ...]} (JSON Pointer path, not a generic 500).
  • Schema lives with the workflow artifacts; this is not an Integration Account catalog.

XSD validation

transformers.validate_xsd (POST /validateXsd) checks an XML instance against an XSD artifact (schema_file).

  • Valid → {"valid": true} (HTTP 200).
  • Invalid → HTTP 400 with {valid: false, errors: [{path, message, line?}, ...]} (element/XPath, not a generic 500).
  • XSD lives with the workflow artifacts; this is not an Integration Account catalog.

Inbound Authentication

  • internal-only service (cluster network)

Outbound Authentication

  • none

Example workflow step

- id: to_json
  type: service_call
  capability_name: transformers.xml2json
  capability_version: "^1.0"
  path: /xml2json
  payload_from: initial
  timeout_seconds: 30

Key Config

  • transform limits and timeouts

Health

  • GET /healthz
  • GET /readyz
  • GET /internal/capabilities