# SOAP Contracts API

> Compare caller-supplied WSDL 1.1 and XSD documents for broken references and syntactic contract changes. No documents are downloaded.

Each POST has a fixed USDC price on Base, paid with the x402 exact scheme. The request is validated first, and payment settles only after a successful (2xx) result. Failed calls are not charged.

1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.
2. A valid unpaid call returns 402 with the exact amount and payTo.
3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.

- Product: https://www.brainiac.software/api/soap-contracts
- Docs: https://www.brainiac.software/api/soap-contracts/docs
- OpenAPI: https://www.brainiac.software/api/soap-contracts/openapi.json
- Contact: support@brainiac.software (https://www.brainiac.software/contact)

## Operations

### POST /api/v1/soap-contracts/wsdl-xsd-dependency-audit

$0.05 USDC. Compare a caller-supplied WSDL 1.1 document and its XSD documents, including an optional previous set. audit_status is valid, warnings, breaking_changes, invalid, or incomplete. Imports are not downloaded. A schema difference is syntactic and is not proof that a SOAP client fails at runtime.

Inputs: wsdl, schemas, previous?, clients?

Docs: https://www.brainiac.software/api/soap-contracts/docs#soap-contracts-wsdl-xsd-dependency-audit

Example request:

```json
{
  "wsdl": {
    "name": "account.wsdl",
    "content": "<?xml version=\"1.0\"?>\n<definitions xmlns=\"http://schemas.xmlsoap.org/wsdl/\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:tns=\"urn:account\" targetNamespace=\"urn:account\">\n  <types>\n    <xsd:schema targetNamespace=\"urn:account\">\n      <xsd:include schemaLocation=\"types.xsd\"/>\n      <xsd:import namespace=\"urn:missing\" schemaLocation=\"https://example.com/missing.xsd\"/>\n    </xsd:schema>\n  </types>\n  <message name=\"GetAccountRequest\"><part name=\"body\" element=\"tns:GetAccountRequest\"/></message>\n  <message name=\"GetAccountResponse\"><part name=\"body\" element=\"tns:GetAccountResponse\"/></message>\n  <portType name=\"AccountPortType\">\n    <operation name=\"GetAccount\"><input message=\"tns:GetAccountRequest\"/><output message=\"tns:GetAccountResponse\"/></operation>\n  </portType>\n  <binding name=\"AccountBinding\" type=\"tns:AccountPortType\"><operation name=\"GetAccount\"/></binding>\n  <service name=\"AccountService\"><port name=\"AccountPort\" binding=\"tns:AccountBinding\"/></service>\n</definitions>"
  },
  "schemas": [
    {
      "name": "types.xsd",
      "content": "<?xml version=\"1.0\"?>\n<xsd:schema xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:tns=\"urn:account\" targetNamespace=\"urn:account\">\n  <xsd:element name=\"GetAccountRequest\"><xsd:complexType><xsd:sequence>\n    <xsd:element name=\"id\" type=\"xsd:string\" minOccurs=\"1\"/>\n    <xsd:element name=\"note\" type=\"xsd:string\" minOccurs=\"0\"/>\n  </xsd:sequence></xsd:complexType></xsd:element>\n  <xsd:element name=\"GetAccountResponse\" type=\"tns:Account\"/>\n  <xsd:complexType name=\"Account\"><xsd:sequence>\n    <xsd:element name=\"id\" type=\"xsd:string\"/>\n    <xsd:element name=\"owner\" type=\"tns:Account\"/>\n  </xsd:sequence></xsd:complexType>\n</xsd:schema>"
    },
    {
      "name": "extra.xsd",
      "content": "<?xml version=\"1.0\"?><xsd:schema xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" targetNamespace=\"urn:account\"><xsd:complexType name=\"Account\"><xsd:sequence><xsd:element name=\"id\" type=\"xsd:string\"/></xsd:sequence></xsd:complexType></xsd:schema>"
    }
  ],
  "previous": {
    "wsdl": {
      "name": "account.wsdl",
      "content": "<?xml version=\"1.0\"?>\n<definitions xmlns=\"http://schemas.xmlsoap.org/wsdl/\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:tns=\"urn:account\" targetNamespace=\"urn:account\">\n  <types><xsd:schema targetNamespace=\"urn:account\"><xsd:include schemaLocation=\"types.xsd\"/></xsd:schema></types>\n  <message name=\"GetAccountRequest\"><part name=\"body\" element=\"tns:GetAccountRequest\"/></message>\n  <message name=\"GetAccountResponse\"><part name=\"body\" element=\"tns:GetAccountResponse\"/></message>\n  <message name=\"ResetPasswordRequest\"><part name=\"body\" element=\"tns:ResetPasswordRequest\"/></message>\n  <portType name=\"AccountPortType\">\n    <operation name=\"GetAccount\"><input message=\"tns:GetAccountRequest\"/><output message=\"tns:GetAccountResponse\"/></operation>\n    <operation name=\"ResetPassword\"><input message=\"tns:ResetPasswordRequest\"/></operation>\n  </portType>\n  <binding name=\"AccountBinding\" type=\"tns:AccountPortType\"><operation name=\"GetAccount\"/><operation name=\"ResetPassword\"/></binding>\n  <service name=\"AccountService\"><port name=\"AccountPort\" binding=\"tns:AccountBinding\"/></service>\n</definitions>"
    },
    "schemas": [
      {
        "name": "types.xsd",
        "content": "<?xml version=\"1.0\"?>\n<xsd:schema xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:tns=\"urn:account\" targetNamespace=\"urn:account\">\n  <xsd:element name=\"GetAccountRequest\"><xsd:complexType><xsd:sequence>\n    <xsd:element name=\"id\" type=\"xsd:string\" minOccurs=\"0\"/>\n  </xsd:sequence></xsd:complexType></xsd:element>\n  <xsd:element name=\"GetAccountResponse\" type=\"tns:Account\"/>\n  <xsd:element name=\"ResetPasswordRequest\"><xsd:complexType><xsd:sequence><xsd:element name=\"id\" type=\"xsd:string\"/></xsd:sequence></xsd:complexType></xsd:element>\n  <xsd:complexType name=\"Account\"><xsd:sequence><xsd:element name=\"id\" type=\"xsd:int\"/></xsd:sequence></xsd:complexType>\n</xsd:schema>"
      }
    ]
  },
  "clients": [
    {
      "name": "legacy-client",
      "operations": [
        "ResetPassword"
      ],
      "elements": [
        {
          "namespace": "urn:account",
          "name": "ResetPasswordRequest"
        }
      ]
    }
  ]
}
```

Example response:

```json
{
  "audit_status": "breaking_changes",
  "dependency_graph": {
    "nodes": [
      {
        "document": "account.wsdl",
        "role": "wsdl",
        "namespace": "urn:account"
      },
      {
        "document": "types.xsd",
        "role": "xsd",
        "namespace": "urn:account"
      },
      {
        "document": "extra.xsd",
        "role": "xsd",
        "namespace": "urn:account"
      }
    ],
    "edges": [
      {
        "from": "account.wsdl",
        "to": "types.xsd",
        "kind": "include",
        "reference": "types.xsd"
      }
    ]
  },
  "unresolved_references": [
    {
      "document": "account.wsdl",
      "reference": "https://example.com/missing.xsd",
      "kind": "import",
      "namespace": "urn:missing",
      "detail": "https://example.com/missing.xsd is not in the supplied documents. It was not downloaded."
    }
  ],
  "namespace_conflicts": [
    {
      "namespace": "urn:account",
      "name": "Account",
      "kind": "complexType",
      "documents": [
        "types.xsd",
        "extra.xsd"
      ],
      "detail": "complexType Account in namespace urn:account is defined in types.xsd and extra.xsd with different content. The first definition is used for comparison."
    }
  ],
  "contract_changes": [
    {
      "change": "removed",
      "impact": "breaking",
      "kind": "operation",
      "namespace": "urn:account",
      "name": "ResetPassword",
      "document": "account.wsdl",
      "ownerKind": "operation",
      "ownerNamespace": "urn:account",
      "ownerName": "ResetPassword",
      "detail": "AccountPortType.ResetPassword is in the previous contract and is not in the proposed contract. This is a syntactic removal, not proof a client fails at runtime."
    },
    {
      "change": "removed",
      "impact": "breaking",
      "kind": "message",
      "namespace": "urn:account",
      "name": "ResetPasswordRequest",
      "document": "account.wsdl",
      "ownerKind": "message",
      "ownerNamespace": "urn:account",
      "ownerName": "ResetPasswordRequest",
      "detail": "message ResetPasswordRequest in namespace urn:account was removed. This is a syntactic removal, not proof a client fails at runtime."
    },
    {
      "change": "removed",
      "impact": "breaking",
      "kind": "element",
      "namespace": "urn:account",
      "name": "ResetPasswordRequest",
      "document": "types.xsd",
      "ownerKind": "element",
      "ownerNamespace": "urn:account",
      "ownerName": "ResetPasswordRequest",
      "detail": "element ResetPasswordRequest in namespace urn:account was removed. This is a syntactic removal, not proof a client fails at runtime."
    },
    {
      "change": "cardinality",
      "impact": "breaking",
      "kind": "element",
      "namespace": "",
      "name": "GetAccountRequest.id",
      "document": "types.xsd",
      "ownerKind": "element",
      "ownerNamespace": "urn:account",
      "ownerName": "GetAccountRequest",
      "detail": "GetAccountRequest.id changed from 0..1 to 1..1. This is a syntactic cardinality change, not proof a client fails at runtime."
    },
    {
      "change": "added",
      "impact": "additive",
      "kind": "element",
      "namespace": "",
      "name": "GetAccountRequest.note",
      "document": "types.xsd",
      "ownerKind": "element",
      "ownerNamespace": "urn:account",
      "ownerName": "GetAccountRequest",
      "detail": "GetAccountRequest.note was added as an optional item. This is a syntactic change, not proof a client fails at runtime."
    },
    {
      "change": "type",
      "impact": "breaking",
      "kind": "element",
      "namespace": "",
      "name": "Account.id",
      "document": "types.xsd",
      "ownerKind": "complexType",
      "ownerNamespace": "urn:account",
      "ownerName": "Account",
      "detail": "Account.id changed from {http://www.w3.org/2001/XMLSchema}int to {http://www.w3.org/2001/XMLSchema}string. This is a syntactic type change, not proof a client fails at runtime."
    },
    {
      "change": "added",
      "impact": "breaking",
      "kind": "element",
      "namespace": "",
      "name": "Account.owner",
      "document": "types.xsd",
      "ownerKind": "complexType",
      "ownerNamespace": "urn:account",
      "ownerName": "Account",
      "detail": "Account.owner was added as a required item. This is a syntactic change, not proof a client fails at runtime."
    }
  ],
  "breaking_change_candidates": [
    {
      "change": "removed",
      "impact": "breaking",
      "kind": "operation",
      "namespace": "urn:account",
      "name": "ResetPassword",
      "document": "account.wsdl",
      "ownerKind": "operation",
      "ownerNamespace": "urn:account",
      "ownerName": "ResetPassword",
      "detail": "AccountPortType.ResetPassword is in the previous contract and is not in the proposed contract. This is a syntactic removal, not proof a client fails at runtime."
    },
    {
      "change": "removed",
      "impact": "breaking",
      "kind": "message",
      "namespace": "urn:account",
      "name": "ResetPasswordRequest",
      "document": "account.wsdl",
      "ownerKind": "message",
      "ownerNamespace": "urn:account",
      "ownerName": "ResetPasswordRequest",
      "detail": "message ResetPasswordRequest in namespace urn:account was removed. This is a syntactic removal, not proof a client fails at runtime."
    },
    {
      "change": "removed",
      "impact": "breaking",
      "kind": "element",
      "namespace": "urn:account",
      "name": "ResetPasswordRequest",
      "document": "types.xsd",
      "ownerKind": "element",
      "ownerNamespace": "urn:account",
      "ownerName": "ResetPasswordRequest",
      "detail": "element ResetPasswordRequest in namespace urn:account was removed. This is a syntactic removal, not proof a client fails at runtime."
    },
    {
      "change": "cardinality",
      "impact": "breaking",
      "kind": "element",
      "namespace": "",
      "name": "GetAccountRequest.id",
      "document": "types.xsd",
      "ownerKind": "element",
      "ownerNamespace": "urn:account",
      "ownerName": "GetAccountRequest",
      "detail": "GetAccountRequest.id changed from 0..1 to 1..1. This is a syntactic cardinality change, not proof a client fails at runtime."
    },
    {
      "change": "type",
      "impact": "breaking",
      "kind": "element",
      "namespace": "",
      "name": "Account.id",
      "document": "types.xsd",
      "ownerKind": "complexType",
      "ownerNamespace": "urn:account",
      "ownerName": "Account",
      "detail": "Account.id changed from {http://www.w3.org/2001/XMLSchema}int to {http://www.w3.org/2001/XMLSchema}string. This is a syntactic type change, not proof a client fails at runtime."
    },
    {
      "change": "added",
      "impact": "breaking",
      "kind": "element",
      "namespace": "",
      "name": "Account.owner",
      "document": "types.xsd",
      "ownerKind": "complexType",
      "ownerNamespace": "urn:account",
      "ownerName": "Account",
      "detail": "Account.owner was added as a required item. This is a syntactic change, not proof a client fails at runtime."
    }
  ],
  "affected_operations": [
    {
      "client": "legacy-client",
      "service": "AccountService",
      "binding": "AccountBinding",
      "operation": "ResetPassword",
      "reason": "operation_removed",
      "detail": "ResetPassword was removed from the proposed contract. A schema difference does not prove the client fails at runtime."
    },
    {
      "service": "AccountService",
      "binding": "AccountBinding",
      "operation": "GetAccount",
      "reason": "operation_changed",
      "detail": "GetAccount reaches element GetAccountRequest. The change is syntactic and is not proof the client fails at runtime."
    }
  ],
  "findings": [
    {
      "code": "operation_removed",
      "severity": "high",
      "document": "account.wsdl",
      "namespace": "urn:account",
      "name": "ResetPassword",
      "operation": "ResetPassword",
      "detail": "AccountPortType.ResetPassword is in the previous contract and is not in the proposed contract. This is a syntactic removal, not proof a client fails at runtime."
    },
    {
      "code": "message_removed",
      "severity": "high",
      "document": "account.wsdl",
      "namespace": "urn:account",
      "name": "ResetPasswordRequest",
      "detail": "message ResetPasswordRequest in namespace urn:account was removed. This is a syntactic removal, not proof a client fails at runtime."
    },
    {
      "code": "element_removed",
      "severity": "high",
      "document": "types.xsd",
      "namespace": "urn:account",
      "name": "ResetPasswordRequest",
      "detail": "element ResetPasswordRequest in namespace urn:account was removed. This is a syntactic removal, not proof a client fails at runtime."
    },
    {
      "code": "element_cardinality",
      "severity": "high",
      "document": "types.xsd",
      "namespace": "",
      "name": "GetAccountRequest.id",
      "detail": "GetAccountRequest.id changed from 0..1 to 1..1. This is a syntactic cardinality change, not proof a client fails at runtime."
    },
    {
      "code": "element_added",
      "severity": "low",
      "document": "types.xsd",
      "namespace": "",
      "name": "GetAccountRequest.note",
      "detail": "GetAccountRequest.note was added as an optional item. This is a syntactic change, not proof a client fails at runtime."
    },
    {
      "code": "element_type",
      "severity": "high",
      "document": "types.xsd",
      "namespace": "",
      "name": "Account.id",
      "detail": "Account.id changed from {http://www.w3.org/2001/XMLSchema}int to {http://www.w3.org/2001/XMLSchema}string. This is a syntactic type change, not proof a client fails at runtime."
    },
    {
      "code": "element_added",
      "severity": "high",
      "document": "types.xsd",
      "namespace": "",
      "name": "Account.owner",
      "detail": "Account.owner was added as a required item. This is a syntactic change, not proof a client fails at runtime."
    },
    {
      "code": "client_component_removed",
      "severity": "high",
      "namespace": "urn:account",
      "name": "ResetPasswordRequest",
      "detail": "legacy-client depends on element ResetPasswordRequest in namespace urn:account, and the proposed contract does not declare it. This is a syntactic removal, not proof the client fails at runtime."
    },
    {
      "code": "recursive_type",
      "severity": "medium",
      "namespace": "urn:account",
      "name": "Account",
      "detail": "Account in namespace urn:account participates in a recursive type reference. The cycle is reported from the supplied documents only."
    },
    {
      "code": "schema_unreferenced",
      "severity": "medium",
      "document": "extra.xsd",
      "detail": "extra.xsd is supplied, and no supplied document imports, includes, or redefines it."
    },
    {
      "code": "definition_conflict",
      "severity": "high",
      "document": "extra.xsd",
      "namespace": "urn:account",
      "name": "Account",
      "detail": "complexType Account in namespace urn:account is defined in types.xsd and extra.xsd with different content. The first definition is used for comparison."
    },
    {
      "code": "reference_unresolved",
      "severity": "medium",
      "document": "account.wsdl",
      "namespace": "urn:missing",
      "name": "https://example.com/missing.xsd",
      "detail": "https://example.com/missing.xsd is not in the supplied documents. It was not downloaded."
    },
    {
      "code": "syntactic_only",
      "severity": "low",
      "detail": "This comparison is syntactic. It does not prove that an existing SOAP client would fail at runtime, and it does not establish full client compatibility."
    }
  ],
  "limitations": [
    "Documents are the XML strings in the request. Imports, includes, and redefines were not downloaded.",
    "A difference between contracts is syntactic. It is not proof that a SOAP client fails at runtime.",
    "Names are compared as a namespace plus a local name.",
    "Only WSDL 1.1 and XML Schema are read. The root WSDL is the only WSDL document in a set.",
    "When one name is defined more than once, the first definition is used for comparison.",
    "This audit does not establish full client compatibility."
  ]
}
```

### POST /api/v1/soap-contracts/schema-dependency-tree

$0.04 USDC. Read import, include, and complexType names from the supplied XML. A document cycle, or a complex type that references itself, sets the circular flag. The score counts types, imports, and non-builtin references. schemaLocation values are not downloaded.

Inputs: documents

Docs: https://www.brainiac.software/api/soap-contracts/docs#soap-contracts-schema-dependency-tree

Example request:

```json
{
  "documents": [
    {
      "name": "types.xsd",
      "content": "<?xml version=\"1.0\"?>\n<xsd:schema xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">\n  <xsd:import schemaLocation=\"other.xsd\"/>\n  <xsd:complexType name=\"Account\"><xsd:sequence><xsd:element name=\"owner\" type=\"tns:Account\"/></xsd:sequence></xsd:complexType>\n</xsd:schema>"
    },
    {
      "name": "other.xsd",
      "content": "<?xml version=\"1.0\"?>\n<xsd:schema xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">\n  <xsd:import schemaLocation=\"types.xsd\"/>\n  <xsd:complexType name=\"Note\"><xsd:sequence><xsd:element name=\"text\" type=\"xsd:string\"/></xsd:sequence></xsd:complexType>\n</xsd:schema>"
    }
  ]
}
```

Example response:

```json
{
  "schema_complexity_score": 55,
  "circular_dependency_detected": true,
  "dependency_tree_json": [
    {
      "document": "types.xsd",
      "imports": [
        "other.xsd"
      ],
      "types": [
        "Account"
      ],
      "references": [
        "Account"
      ]
    },
    {
      "document": "other.xsd",
      "imports": [
        "types.xsd"
      ],
      "types": [
        "Note"
      ],
      "references": []
    }
  ]
}
```