Metadata WSDL
The Metadata WSDL is the SOAP interface definition for the Salesforce Metadata API.
Definition
The Metadata WSDL is the SOAP interface definition for the Salesforce Metadata API. WSDL stands for Web Service Description Language, and the file describes every operation, request shape, and response shape the SOAP-based Metadata API exposes. You download it from Salesforce Setup and import it into a development platform like Java or .NET, which reads the file and generates strongly typed stub classes. Your code then calls Metadata API operations through those stubs instead of hand-building raw SOAP envelopes.
The Metadata API lets you read and change the configuration of an org as XML, rather than the records that live inside it. Through the Metadata WSDL you can retrieve and deploy components such as custom objects, page layouts, Apex classes, and permission sets. The SOAP-based interface was the original way to reach the Metadata API, and it still works today. Many continuous integration tools use it under the covers, though most everyday teams now reach the same API through the Salesforce CLI.
How the Metadata WSDL fits into deployment work
Two WSDLs you usually need together
The Metadata WSDL rarely travels alone. It describes the Metadata API operations, but it does not handle login. To authenticate, you pair it with an Enterprise WSDL or a Partner WSDL, both of which expose a login call that returns a session ID. Your client logs in once through that companion WSDL, captures the session ID, then passes it in the SOAP header of every Metadata API request. Salesforce generates all three WSDLs from Setup. The Enterprise WSDL is strongly typed to one specific org and its custom fields. The Partner WSDL is loosely typed and works across many orgs, which makes it the common choice for tools that connect to lots of different Salesforce instances. The Metadata WSDL itself is the same document for any org on a given API version, because it describes metadata operations rather than a particular org's data schema. Knowing which file does what saves real confusion when a build fails. A login error usually points at the companion WSDL or the session, while a missing metadata type points at the Metadata WSDL version you imported.
File-based calls: retrieve, deploy, list, describe
The Metadata API offers two development models, and the WSDL declares both. The file-based model is the one most teams picture when they think about deployments. It centers on four asynchronous operations. The deploy call takes a zip of metadata files plus a manifest and creates, updates, or deletes those components in the target org. The retrieve call pulls a chosen set of components out of an org as XML. Because both run asynchronously, you submit the request, get back an ID, then poll deployStatus or checkRetrieveStatus until the job finishes. Two helper operations round out the set. The listMetadata call returns the components that exist for a given type, which is how a tool discovers, say, every custom object in an org. The describeMetadata call returns the catalog of metadata types the org supports at that API version. Tools build their whole sync workflow on these four operations. You pick the components, you package them, you deploy or retrieve, and you watch the status until it reports success or a list of component failures.
CRUD-based calls for one component at a time
The second model is CRUD-based metadata development, and the same WSDL declares it. Instead of zipping files and polling an async job, you send a single synchronous call that acts on a small set of components in memory. The operations read like database verbs. createMetadata adds new components, updateMetadata changes existing ones, and deleteMetadata removes them. There is also upsertMetadata, which creates a component if it is missing or updates it if it already exists, and renameMetadata for changing a component's developer name. readMetadata returns the full definition of named components so you can inspect or modify them in code. These calls are synchronous and return right away, which makes them handy for scripts and for Apex that needs to make a quick configuration change. The trade-off is scope. CRUD-based calls work on a limited set of metadata types and a capped number of components per call, so they suit targeted edits rather than a full org migration. For moving large bundles between orgs, the file-based deploy and retrieve operations remain the right tool.
Generating client stubs from the file
A WSDL is only useful once a tool turns it into code. After you download the Metadata WSDL, you feed it to a code generator that produces stub or proxy classes in your language. Java developers commonly run wsimport or the Force.com WSC toolkit, while .NET developers add it as a service reference or run the SOAP proxy generator. The generator reads every operation and type the WSDL describes and emits matching classes and methods. From then on, calling deploy or listMetadata looks like calling a normal local method. The stubs serialize your arguments into a SOAP envelope, send the HTTP request, and parse the XML response back into objects. This is why teams import the WSDL once and rarely look at it again. The generated code hides the SOAP plumbing. The cost is that the stubs are tied to the API version of the WSDL you imported. When Salesforce adds new metadata types in a later release, you regenerate the stubs from a fresh WSDL to pick them up, otherwise your client simply cannot see the new types.
Calling the Metadata API from Apex
You do not always need an external client to reach metadata. Apex can do it in two ways. The first is to import the Metadata WSDL directly through Setup, Apex Classes, Generate from WSDL. That tool runs WSDL2Apex, which converts the SOAP definition into Apex classes you can call from server-side code. The second and now more common path is the built-in Metadata namespace, which Salesforce added so you do not have to generate anything. The Metadata.Operations class exposes enqueueDeployment and retrieve methods, and you build a Metadata.DeployContainer to hold the components you want to push. A Metadata.DeployCallback handles the asynchronous result. This native approach is cleaner than the generated WSDL2Apex classes, which tend to be large and awkward to maintain. A practical use is a self-service admin screen. A Lightning page collects input, then Apex deploys a small configuration change such as a new picklist value or a custom metadata record, all without leaving the org. Keep in mind that metadata calls from Apex still run against governor limits and callout rules.
SOAP, REST, and the CLI today
Salesforce ships the Metadata API in two flavors that expose the same operations. The SOAP flavor is the one the Metadata WSDL describes. The REST flavor came later and is handy for lightweight clients and for the deploy and retrieve resources used by modern tooling. Neither flavor is more capable than the other for the core deploy and retrieve work, so the choice usually comes down to the libraries your stack already speaks. On top of both sits the Salesforce CLI. It wraps the Metadata API and the newer source-tracking workflow, handling login, packaging, async polling, and error reporting for you. Most teams now deploy through the CLI or through a CI tool that calls these APIs for them, which is why a developer can work for years without opening a WSDL file. The Metadata WSDL has not gone away though. It remains supported, it underpins many Java-based integration tools, and it is still the right entry point when you are building a custom SOAP client or generating Apex stubs for in-org metadata work.
Versioning and common pitfalls
The Metadata WSDL carries an API version, and that version shapes what your client can do. A WSDL downloaded at an older version describes only the metadata types and fields that existed then. If you try to deploy a component type that arrived in a newer release, a client built from the old WSDL will not recognize it, and the call fails. This is the most frequent surprise for teams that bundle a WSDL with their tool and forget to refresh it. The fix is simple. Periodically download a current WSDL and regenerate your stubs so the client tracks the latest types. A second pitfall is permissions. Generating the WSDL and running deployments both require strong access, typically a user with Modify All Data or Modify Metadata, so a least-privilege integration user may hit errors. A third is mixing versions across files. Your Metadata WSDL, your companion login WSDL, and the package manifest version should line up. When they drift apart you can see odd failures that are hard to trace, so treating the API version as a single setting across the integration keeps things predictable.
How to generate and import the Metadata WSDL
Generating the Metadata WSDL and importing it into a development platform is a one-time setup you do before building a SOAP client. You download the file from Setup, generate stub code from it, and pair it with a login WSDL for authentication.
- Open the API page in Setup
From Setup, enter API in the Quick Find box, then select API. This page lists every WSDL and client certificate Salesforce can generate for your org.
- Generate the Metadata WSDL
Click Generate Metadata WSDL and save the XML file to your file system. The file is tied to the org's current API version, so note that version for later.
- Generate a login WSDL
Back on the API page, also generate the Enterprise WSDL or Partner WSDL. You need its login operation to obtain the session ID that the Metadata API requires.
- Import and generate stubs
Feed the Metadata WSDL to your code generator, such as wsimport for Java or a service reference in .NET, to produce typed stub classes for the deploy, retrieve, list, and describe operations.
- Authenticate, then call
Call login through the companion WSDL, capture the returned session ID, and pass it in the SOAP header of each Metadata API request your stubs send.
Describes the Metadata API operations. Required to generate the stub code that performs deploy and retrieve.
Provides the login operation and session ID. Enterprise is typed to one org; Partner is generic and works across orgs.
Set by the WSDL you download. Keep it aligned with your manifest and login WSDL so newer metadata types resolve.
The tool that turns the WSDL into stubs, for example Force.com WSC or wsimport for Java, or a service reference for .NET.
- Generating the WSDL and running deployments require strong access, usually Modify All Data or Modify Metadata; a minimal integration user can hit permission errors.
- Stubs are locked to the WSDL's API version. New metadata types from later releases stay invisible until you download a fresh WSDL and regenerate.
- The Metadata WSDL does not handle login. Skipping the companion Enterprise or Partner WSDL leaves you with no session ID and every call fails.
- For most routine deployments the Salesforce CLI is faster and safer than a hand-built SOAP client, so reach for the WSDL only when you truly need a custom integration.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Metadata WSDL.
Hands-on resources to go deeper on Metadata WSDL.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the Metadata WSDL?
Q2. Where do you download the Metadata WSDL?
Q3. What's the modern alternative?
Discussion
Loading discussion…