DataSourceObject Metadata Type in SFDX

Architectural Overview#

In Salesforce Data Cloud, DataSourceObject represents the structural schema definition of an external table, object, or file feed originating from a DataSource (such as Amazon S3, Snowflake, Google BigQuery, or a Salesforce CRM org). While CustomObject with an __dlm or __dll suffix represents the materialized Data Model Object (DMO) or Data Lake Object (DLO), DataSourceObject captures the raw upstream schema contract before transformation.

Architecturally, separating DataSourceObject from target DMOs decouples ingestion connectors from canonical enterprise data models. When packaging Data Cloud integrations into a Data Kit, DataSourceObject ensures that downstream field mappings (DataSrcDataModelFieldMap) and stream templates (DataStreamTemplate) have a deterministic source schema to bind against.

SFDX Directory and File Suffix#

Key Metadata Fields#

Declarative XML and Package.xml Examples#

DataSourceObject Metadata File#

<?xml version="1.0" encoding="UTF-8"?>
<DataSourceObject xmlns="http://soap.sforce.com/2006/04/metadata">
    <dataSource>Snowflake_Enterprise_ERP</dataSource>
    <externalRecordIdentifier>PUBLIC.ERP_ORDER_HEADERS</externalRecordIdentifier>
    <masterLabel>ERP Order Header Source Object</masterLabel>
    <objectType>Engagement</objectType>
    <storageType>LOCAL</storageType>
    <templateVersion>1</templateVersion>
</DataSourceObject>

package.xml Manifest#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>ERP_Order_Header_DSO</members>
        <name>DataSourceObject</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval and Deployment Commands#

Because DataSourceObject is a declarative Data Cloud metadata component, use the Salesforce CLI (sf) to retrieve and deploy definitions between sandboxes and production orgs:

# Retrieve a specific DataSourceObject from your Data Cloud org
sf project retrieve start --metadata "DataSourceObject:ERP_Order_Header_DSO" --target-org data-cloud-prod

# Retrieve all DataSourceObject definitions alongside their parent DataSource
sf project retrieve start --metadata "DataSource,DataSourceObject" --target-org data-cloud-prod

# Validate deployment in a target environment
sf project deploy start --metadata "DataSourceObject:ERP_Order_Header_DSO" --dry-run --target-org data-cloud-uat

Senior Architect Best Practices and Gotchas#

• Naming Conventions: Prefix DataSourceObject developer names with the source system identifier (for example, SAP_, SFMC_, or Snowflake_) to prevent namespace collisions when multiple connectors expose identically named tables like Orders or Customers.
• Zero-Copy vs. Local Storage: Verify that storageType aligns with your connector capability—switching an existing DataSourceObject from LOCAL ingestion to federated zero-copy requires recreating the downstream Data Lake Object.

Frequently asked questions

What is the role of DataSourceObject in Salesforce Data Cloud?

DataSourceObject represents the schema definition of an external object or file table ingested through a DataSource connector before it is mapped to a Data Lake Object and Data Model Object.

Where are DataSourceObject files stored in an SFDX project?

They are stored in the force-app/main/default/dataSourceObjects directory with the file suffix .dataSourceObject-meta.xml.

Can DataSourceObject components be packaged in Data Cloud Data Kits?

Yes. Architects bundle DataSourceObject definitions alongside DataSource, DataStreamTemplate, and DataSrcDataModelFieldMap components inside a DataPackageKitDefinition for cross-org deployment.

What happens if I modify a field data type on an active DataSourceObject?

Changing the data type of an existing field on an active DataSourceObject connected to a running data stream is blocked. You must add a new field or recreate the stream.