Metadata Standards¶

A practical set of standards for Salesforce metadata: naming, structure, and governance, with the checks that keep orgs consistent and reviewable. Automation comes first because its framework governs how everything else changes, and Observability follows because every automation layer logs through it; the remaining pages group metadata types by domain. The Principles behind these standards include that code and metadata are governed alike.

• Automation: the Automation Framework that governs all automation in the org, then Flows, approval processes, and the retirement of legacy automation
• Observability: logging, platform monitoring with Salesforce Shield, and the observability platform every company must run
• Permissions and Security: profiles, permission sets and groups, sharing, and high-risk permission elements
• Objects and Fields: the data model, validation rules, record types, and picklists
• Integration: the choice of API, External Client Apps, credentials, external services, and access settings
• Settings: org settings metadata and what belongs in version control
• User Interface: Lightning apps and pages, layouts, and actions
• Data Management: custom metadata types, duplicate and matching rules, and data classification
• Analytics: reports, dashboards, and report types
• Agentforce: agents, topics, actions, and prompt templates

Naming¶

The metadata of an org follows one naming convention for each kind of metadata, and the organisation posts those conventions in an easily accessible place for all involved in org maintenance. A name is read far more often than it is written (Naming), and a reader who knows the convention knows what a component is before opening it. The convention is the organisation's own: these standards state the ones that hold everywhere, such as the case of an Apex class name, and leave the rest to the organisation (Names and Descriptions). The specifics of naming conventions are less important than the need to have one consistent convention.

• Each part of a convention is enforced where it can be read. The Centre of Excellence (CoE) checks items that are decided at design time, such as the name of a new object, Flow, or Named Credential, when it approves the design document, so a design document must name every component it introduces. Static analysis checks the parts of a name that a rule can read, such as case, prefix, suffix, and first letter, on every pull request. Reviewers check the rest: that the name says what the component is, and that it is written the same way as the names of the components beside it.
• Some rules below take a convention through their properties: the stock PMD naming rules take a regular expression for each kind of Apex name, the trigger rule takes the suffixes a trigger name may end with, the {N} capital-letter rules take the metadata types they read from a property, the checkbox field rule takes its two prefixes, and the Flow naming rules take the project, application, or business unit codes, kind codes, verbs, and prefixes from properties, so an organisation that has a related convention enforces the parts a rule can read without writing a new rule.

The conventions these standards state, and the rules that check them:

API Version¶

Every metadata file that states an API version states a recent one. A component keeps the platform behaviour of the version it is saved at, so a fix, a new feature, or a safer default reaches it only when its version is raised (Apex Versioned Behavior Changes; Component Versioning for Lightning Web Components). An older version blocks the pull request (severity 2). Enforced by BumpApiVersion and AvoidOldSalesforceApiVersions.

Components left at old versions also drift apart. One org then runs the same kind of component under several sets of platform behaviour, which makes it harder to predict and to test, and the step to a current version grows with every release that passes. What a version changes for code is shown by example on the Apex and JavaScript pages.

Each organisation chooses its own floor, and moves it when it chooses. {N} rules can enforce the standard, and replacing AvoidOldSalesforceApiVersions with BumpApiVersion is recommended, because the first sets its floor by itself and the second takes the floor that the organisation gives it.

The standard is checked in the apiVersion element of each metadata file. No rule reads sourceApiVersion in sfdx-project.json, or the version in a package.xml manifest.

Duplicated Metadata¶

• No block of metadata XML is copied by hand from one file to another. Much metadata repeats by nature, because the platform writes the same elements into every file of a kind, so the rule is set to report a long run of identical XML, and a report is read as a question: is this a component that should exist once? A block of XML that appears more than once across the repository is reported at severity 5, for the developer's information (Refactoring Duplicates). Enforced by DetectCopyPasteForXml.

Rules¶

The rules that this page mentions. The Standard column gives each rule's standard in one line, and the Section column links to the section that mentions the rule; "Not yet written" marks a rule of this page that no section mentions yet. Appendix F.6 holds the full cross-reference.