💃 Stop Discovering API Changes in Production 🕺

Good morning, Salesforce Nerds! We’ve all lived it …

Friday, 4:47 p.m. Product ships a new subscription tier. Engineering adds an enum value. Everyone goes home. 🍻

Monday, 6:12 a.m. Quote-to-cash is down. The picklist rejected the new value, the integration user hit a validation rule, and 900 orders are sitting in a dead-letter queue nobody monitors.

The postmortem will say "communication gap." It will not say "we never wrote down what we promised each other."

Same thing, less flattering. 🔍

A data contract is that promise, written down and enforced. Product owns the meaning, Engineering owns the shape, Salesforce owns the landing zone.

If you've ever heard "but the API didn't change, we just added a field," this one's for you. 👇️

TABLE OF CONTENTS

💃 Stop Discovering API Changes in Production 🕺

• Who Owns The Promise

• Schema As Contract

• Closed Means What Exactly

• Breaking Changes Break Things

• Enforce It Or Forget It

A PROMISE IS NOT A CONTRACT

WHO OWNS THE PROMISE

Every data flow has a producer and a consumer. The producer owns the promise. The consumer owns the dependency. 🤝

Here's the part that trips teams up: "the integration guy" owns neither.

The moment you make the MuleSoft developer the arbiter of what Status = Closed means, you've built an org chart with a single point of failure.

Chad Sanderson's framing is the useful one. Consumers define what they need. Producers own the contract once the cost of breaking downstream dependencies becomes real. 🎯

Salesforce sits in an awkward spot. It's a consumer of product events and a producer of CDC events.

That means the Salesforce team signs contracts in both directions, and most orgs have signed exactly zero.

The tell? Ask who owns Account_Tier__c. If three people answer "well, sort of," nobody does. 🤷

CONFLUENCE IS NOT SOURCE CONTROL

SCHEMA AS CONTRACT

 A contract you can't diff is a rumor. 💯 

The schema lives in source control: JSON Schema or OpenAPI for the REST edges, Avro for the event edges.

The Open Data Contract Standard from the Bitol project gives you a YAML format that covers schema, quality rules, SLAs, and ownership in one file, if you'd rather not invent your own.

The good news? Salesforce already speaks this language.

Every Platform Event and CDC event carries an Avro schema with a versioned schema ID. When the object changes, the ID changes. Pub/Sub API hands it to you via GetSchema. 🔑

The platform is publishing a contract on every message. Most subscribers just never read it.

Compare that to the Confluence page describing the Salesforce-to-billing payload, last edited in 2023, by someone who now works at a bank.

That page is documentation. It is not a contract. 🪦

Store it in the repo. Version it. Review it in the PR. Treat it like code, because downstream it behaves like code.

TYPE IS NOT MEANING

CLOSED MEANS WHAT EXACTLY

Schema tells you Status is a string.

It does not tell you that Closed is a win in Sales Cloud, a loss in the billing system, and a shrug in the data warehouse. 🎭

Semantic guarantees cover everything the type system can't: allowed values, cardinality, nullability rules with business meaning, and what happens when two systems disagree.

Salesforce makes this worse in a specific way.

The schema is flexible by design. Any admin with a Setup menu can add a picklist value, deactivate one, or change a field's data type at 3 p.m. on a Tuesday. 🧨

That's not a bug. That's the value proposition.

But it means the semantic layer is the only thing standing between "flexible platform" and "surprise breaking change."

A good contract states the guarantee in plain English right next to the field.

Stage__c: exactly one of these seven values, never null after creation, and Closed Won requires CloseDate in the past. 📌

If Product wants an eighth value, they open a PR against the contract. Not a Jira ticket assigned to whoever's on call.

RENAMING A FIELD IS A FELONY

BREAKING CHANGES BREAK THINGS

Additive changes are cheap. Destructive changes are expensive.

Every team knows this. Every team ships destructive changes anyway. 🔨

✅ Non-breaking: adding an optional field, adding a picklist value the consumer treats as passthrough, widening a length.
❌ Breaking: removing a field, renaming one, tightening a type, changing meaning while keeping the name.

That last one is the silent killer. Same API name, same type, different business definition.

No schema validator on earth catches it. Only the contract's semantic section does. 🕵️

Versioning policy belongs in the contract: how long a deprecated field stays live, how consumers are notified, and who signs off.

A 90-day deprecation window with a dashboard of remaining consumers beats a Slack announcement every time.

For Platform Events, that means publishing a new event definition rather than mutating the old one.

OrderPlaced__e becomes OrderPlacedV2__e, both live until the last subscriber migrates. 📅

Salesforce even hands you the tool: field-level deprecation via Deprecated metadata on managed packages.

Use the same discipline on unmanaged ones.

TRUST BUT VALIDATE

ENFORCE IT OR FORGET IT

An unenforced contract is a wish. 🧞

Enforce at three points. First, CI/CD: a contract test that fails the build when the producer's schema diverges from the committed one. It runs before deploy, not after the outage.

Second, the boundary: MuleSoft DataWeave validates inbound payloads against the spec; Apex validates event payloads before they touch a record. 🛡️

public inherited sharing class OrderEventContract {
  private static final Set<String> VALID_TIERS =
      new Set<String>{ 'Starter', 'Growth', 'Enterprise' };

  public static void validate(OrderPlaced__e evt) {
    if (evt.Tier__c == null || !VALID_TIERS.contains(evt.Tier__c)) {
      throw new ContractViolationException(
          'OrderPlaced__e v1: Tier__c "' + evt.Tier__c + '" is not in contract');
    }
  }
}

That class is boring on purpose. Boring is the point. It fails loudly, names the contract, and routes the violation somewhere a human will see it. 📣

Third, monitoring: drift detection on CDC schema IDs. When AccountChangeEvent starts arriving with a new schema ID, someone should know before the warehouse load fails.

Data contracts won't make Product stop shipping on Fridays. They will make the Friday change fail in CI instead of in your quote-to-cash pipeline. 🏁

That's the whole pitch. Write the promise down. Enforce it at the door. Sleep through the weekend. 🤙 

SOUL FOOD

Today’s Principle

and now....Salesforce Memes