Salesforce Metadata Model: What It Is and Why It Shapes Everything

What Metadata Actually Means in Salesforce

In most software systems, "metadata" means supplementary data that describes other data — file creation dates, database column types, API response schemas. In Salesforce, the term is far more encompassing. Metadata is the entire configuration layer of the platform: custom objects, fields, validation rules, page layouts, permission sets, Apex classes, flows, reports, dashboards, and hundreds of other types.

This distinction matters because it means that in Salesforce, the boundary between "code" and "configuration" is not where you expect it to be. A custom object definition is metadata. The Apex class that runs against that object is also metadata. The permission set that grants access to both is metadata. The page layout that displays the object's fields is metadata. They are all managed through the same Metadata API and can all be version-controlled, deployed, and tracked as a unified set of org configuration.

This is what makes Salesforce different from most enterprise software platforms. The application tier is not a running process that reads configuration from a database — it is a generic execution engine that is entirely shaped by the metadata loaded for each tenant. Change the metadata, and you change what the platform does.

The Three Tiers of Metadata

Salesforce metadata exists across three conceptual tiers, each with different governance rules and upgrade behaviours.

Tier 1 — System Metadata: This is the core platform metadata managed exclusively by Salesforce. It defines the execution engine, the standard APIs, the underlying object framework, and the platform's own infrastructure. You cannot read or modify system metadata directly — it is what gets upgraded when Salesforce releases a new version.

Tier 2 — Standard Metadata: Standard objects (Account, Contact, Opportunity), standard fields, standard process configurations, and standard user interface components fall into this tier. Salesforce creates and owns the base definitions, but orgs can extend them — adding custom fields to Account, adding page layout variations, adding validation rules on top of standard objects. Standard metadata evolves with each Salesforce release, and Salesforce carefully manages backward compatibility so that release upgrades do not break org configurations.

Tier 3 — Custom Metadata: Everything created in your org — custom objects, custom fields, Apex classes, flows, permission sets, reports, custom labels, and hundreds of other types — is custom metadata. This is what your development and admin teams create, and it is what your org's identity is built from.

How Metadata Enables Multi-Tenancy

The metadata model is the mechanism that makes Salesforce's multi-tenant architecture work. Understanding this connection explains many otherwise puzzling platform behaviours.

Every Salesforce org runs on shared infrastructure — the same application servers, the same database clusters, the same code. What differentiates your org from every other org is the metadata. At runtime, when a user performs an action, the platform reads the relevant metadata for that org and executes accordingly: which fields exist, which validations apply, which Apex runs, which permissions are checked.

This architecture is why Salesforce can push a single upgrade to all ~150,000 orgs simultaneously. Because the application logic is in the platform layer (Tier 1), not in the tenant's data layer, upgrading the platform upgrades every tenant at once. There is no per-tenant deployment, no per-tenant upgrade testing by Salesforce. The guarantee is that the upgrade will not break standard org configurations — which is why the standard metadata contracts are so carefully maintained.

The same architecture creates the governor limits. Because all tenants share resources, the platform must prevent any single tenant's metadata-driven logic (Apex, SOQL, triggers) from monopolising shared resources. Governor limits are the enforcement mechanism for the shared-resource bargain.

// Metadata API retrieve example (using SFDX CLI)
sf project retrieve start \
  --metadata "CustomObject:Account" \
  --metadata "ApexClass:OrderService" \
  --metadata "Flow:Order_Approval_Flow" \
  --target-org mydevorg

// The retrieved metadata is a set of XML files
// that represent the current state of those components
// Account.object-meta.xml
// OrderService.cls + OrderService.cls-meta.xml
// Order_Approval_Flow.flow-meta.xml

Metadata API vs Tooling API

Salesforce exposes two APIs for metadata interaction. Understanding which to use — and when each is appropriate — is a practical architectural skill.

Metadata API: The primary API for deploying and retrieving metadata at scale. It is designed for bulk operations — deploying a full package, retrieving all metadata of a type, migrating org configuration between environments. Metadata API operations are asynchronous (you submit a job and poll for results) and work with file-based representations (XML files matching the metadata source format). This is what Salesforce CLI, all CI/CD pipelines, and tools like Gearset and Copado use under the hood.

Tooling API: Designed for developer tooling — IDE integrations, programmatic inspection, and fine-grained metadata queries. Tooling API is synchronous for small operations and exposes object-level access to metadata types as if they were query-able records (you can SOQL against ApexClass, ApexTrigger, Flow, and other types). It is faster for single-record operations than Metadata API but not designed for bulk deployment.

// Tooling API query example — check Apex code coverage
GET /services/data/v60.0/tooling/query?q=
  SELECT+Id,ApexClassOrTrigger.Name,NumLinesCovered,
         NumLinesUncovered,Coverage
  FROM+ApexCodeCoverageAggregate
  WHERE+ApexClassOrTrigger.Name='OrderService'

// Returns coverage data without triggering a deploy
// Useful in CI pipelines that need to assess test coverage
// without running a full Metadata API operation

Metadata Drift and Technical Debt

In orgs without disciplined metadata governance, a phenomenon called metadata drift emerges: the state of the org diverges from what is tracked in source control. This is one of the most common sources of Salesforce technical debt and one of the hardest to recover from.

Drift happens when admins make changes directly in production (field additions, layout changes, permission adjustments) without the corresponding source control update. Over time, the org accumulates metadata that exists "only in production" — not captured in any deployment artifact, not reproducible if the org were recreated, and invisible to the version control history.

The consequences are significant: deployments break because sandbox and production are out of sync; regression testing is unreliable because the test environment doesn't match production; and audits become impossible because there is no authoritative record of what exists in the org and when it was added.

The governance model to prevent drift is the source-of-truth principle: source control is the canonical state of the org, and production is a deployed instance of that canonical state. Any change that bypasses source control is a governance violation, not just a process issue.

Metadata Architecture in DevOps and Org Strategy

The metadata model has direct architectural implications for how orgs are structured, how DevOps is implemented, and how changes are managed across environments.

Environment strategy: Each Salesforce sandbox is an independent metadata container. When you create a sandbox from production, you get a copy of production's metadata — but from that point on, the two metadata sets diverge independently. Keeping sandbox and production metadata aligned requires deliberate deployment practices. The more sandboxes in use, the more complex the metadata synchronisation challenge.

Package-based development: The Salesforce DX (Salesforce CLI / Second-Generation Packaging) model defines explicit package boundaries — a package contains a declared subset of org metadata. This is the architectural recommendation for complex orgs because it creates modularity: different teams own different packages, dependencies between packages are explicit, and package versions provide reproducibility. Contrast this with org-based development where all metadata is in one undifferentiated bucket.

Metadata completeness: Not all metadata types are retrievable via the Metadata API. Some standard platform configuration (certain setup UI configurations, some permission system features) cannot be exported and redeployed. This is a known platform limitation — when designing deployment pipelines, validate that all relevant metadata types are API-retrievable before committing to an automated deployment strategy.

# sfdx-project.json — defining package structure
{
  "packageDirectories": [
    {
      "path": "core",
      "package": "SFVedas-Core",
      "versionName": "Version 1.0",
      "default": true
    },
    {
      "path": "commerce",
      "package": "SFVedas-Commerce",
      "dependencies": [
        { "package": "SFVedas-Core", "versionNumber": "1.0.0.LATEST" }
      ]
    }
  ],
  "sourceApiVersion": "60.0"
}