CustomField

Represents the metadata associated with a field. Use this metadata type to create, update, or delete custom field definitions on standard, custom, and external objects or standard field definitions on standard objects.

This type extends the Metadata metadata type and inherits its fullName field.

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Important

Only standard fields that you can customize are supported, that is, standard fields to which you can add help text or turn on history tracking or Chatter feed tracking. Other standard fields aren't supported, including system fields (such as CreatedById or LastModifiedDate) and auto number fields. Some standard picklist fields aren’t supported. See Unsupported Metadata Types. By default, a custom object doesn’t have any standard fields that are customizable.

Specify the full name whenever you create or update a field. For example, a custom field on a custom object:

1MyCustomObject__c.MyCustomField__c

An example of a custom field on a standard object:

1Account.MyAcctCustomField__c

An example of a standard field on a standard object:

1Account.Phone

An example of a custom field on an external object:

1MyExternalObject__x.MyCustomField__c

In Metadata API, external objects are represented by the CustomObject metadata type.

These custom field types aren’t available for external objects.

Auto number (available only with the cross-org adapter for Salesforce Connect)
Currency (available only with the cross-org adapter for Salesforce Connect)
Formula
Location
Master-detail relationship
Picklist and multi-select picklist (available only with the cross-org adapter for Salesforce Connect)
Rollup summary
Text (encrypted)
Text area (rich)

Note

Declarative Metadata File Suffix and Directory Location

Custom fields are user-defined fields and are part of the custom object or standard object definition. See CustomObject for more information. Standard fields are predefined on standard objects.

Retrieving a component of this metadata type in a project makes the component appear in any Profile and PermissionSet components that are retrieved in the same package.

Note

Retrieving Fields on Custom or Standard Objects

When you retrieve a custom or standard object, you return everything associated with the object, except for standard fields that aren't customizable. You can also retrieve only specific fields for an object by explicitly naming the object and fields in package.xml. The following definition in package.xml creates the files objects/MyCustomObject__c.object and objects/Account.object, each containing the requested field definitions.

1<types>
2  <members>MyCustomObject__c.MyCustomField__c</members>
3  <members>Account.MyCustomAccountField__c</members>
4  <members>Account.Phone</members>
5  <name>CustomField</name>
6</types>

Retrieving or Deploying Fields on Data 360 Objects

When you retrieve a Data 360 object, such as a data lake object (DLO) or data model object (DMO), not all custom field properties are returned. The properties returned depend on the data type of the custom field.

When you deploy a Data 360 object via Metadata API, in API version 60.0 or later, the call succeeds only if the properties are supported by the custom field's data type. If you include a property that isn't supported by the field's data type, the API returns an error.

Data 360 objects support these data types.

Boolean/Checkbox
Date
DateTime
Email
Lookup (DMOs only)
Number
Percent
Phone
Text
Url

Version

Custom and standard fields are available in API version 10.0 and later.

Fields

Unless otherwise noted, all fields are creatable, filterable, and nillable.

Field Name	Field Type	Description
businessOwnerGroup	reference	Group associated with this field. The business owner group understands the importance of the field’s data to your company, and can be responsible for determining the minimum security classification. This field is available in API version 45.0 and later.
businessOwnerUser	reference	Person associated with this field. The business owner understands the importance of the field’s data to your company, and can be responsible for determining the minimum security classification. This field is available in API version 45.0 and later.
businessStatus	picklist	Indicates if the field is in use. Valid values are: `Active` `DeprecateCandidate` `Hidden` This field is available in API version 45.0 and later
caseSensitive	boolean	Indicates whether the field is case-sensitive (`true`) or not (`false`). For indirect lookup relationship fields on external objects, this attribute affects how this custom field’s values are matched against the values of the referenceTargetField.
complianceGroup	multipicklist	Compliance acts, definitions, or regulations related to the field’s data. Valid values are: `CCPA` `COPPA` `GDPR` `HIPAA` `PCI` `PII` This field is available in API version 47.0 and later.
customDataType	string	Deprecated in the Spring ‘19 (API version 45.0) release.
defaultValue	string	If specified, represents the default value of the field.
deleteConstraint	DeleteConstraint (enumeration of type string)	Deletion options for lookup relationships. Valid values are: `Cascade`—Deletes the lookup record and associated lookup fields. `Restrict`—Prevents the record from being deleted if it's in a lookup relationship. `SetNull`—Default value. If the lookup record is deleted, the lookup field is cleared. For more information on lookup relationships, see Object Relationships Overview.
deprecated	boolean	Reserved for future use.
description	string	Description of the field.
displayFormat	string	Display format of the field.
displayLocationInDecimal	boolean	Indicates how the geolocation values of a custom location field appear in the user interface. If `true`, the geolocation values appear in decimal notation. If `false`, the geolocation values appear as degrees, minutes, and seconds.
elementType	ElementType (enumeration of type string)	Reserved for future use.
encrypted	boolean	Indicates whether this field is encrypted (`true`) or not (`false`). This value pertains to Shield Platform Encryption, not Classic Encryption. This field is available in API version 34.0 through 43.0.
encryptionScheme	EncryptionScheme (enumeration of type string)	For encrypted fields, determines which encryption scheme a field takes. Valid values are: `CaseInsensitiveDeterministicEncryption` `CaseSensitiveDeterministicEncryption` `None` `ProbabilisticEncryption` This value pertains to Shield Platform Encryption, not Classic Encryption. This field is available in API version 44.0 and later.
externalDeveloperName	string	Available only for external objects. Name of the table column on the external data source that maps to this custom field in Salesforce. Corresponds to the External Column Name in the user interface. This field is available in API version 32.0 and later.
externalId	boolean	Indicates whether the field is an external ID field (`true`) or not (`false`). This property is returned only if the custom field data type is auto number, email, number, or text.
fieldManageability	FieldManageability (enumeration of type string)	Determines who can update the field after it’s released in a managed package. Valid values are: `Locked`—The field can’t be updated. `DeveloperControlled`—The creator of the record can update the field with a package upgrade. `SubscriberControlled`—Anyone with proper permissions can update the field. The field can’t be updated with a package upgrade. Available only for fields on custom metadata types. If the field type is `MetadataRelationship`, and the manageability of the entity definition field is: Subscriber-controlled, then the Field Definition field must be subscriber-controlled. Upgradeable, then the Field Definition field must be either upgradeable or subscriber-controlled.
formula	string	If specified, represents a formula on the field.
formulaTreatBlanksAs	TreatBlanksAs (enumeration of type string)	Indicates how to treat blanks in a formula. Valid values are `BlankAsBlank` and `BlankAsZero`.
fullName	string	Full name of the object. It must be specified when creating, updating, or deleting the object. See `createMetadata()` to see an example of this field specified for a call. This value can't be `null`.
globalPicklist	string.	If this custom field is a picklist that’s based on a global picklist, globalPicklist is the name of the global picklist whose value set this picklist inherits. A custom picklist that’s based on a global picklist is restricted. You can only add or remove values by editing the global picklist. This field is available only in API version 37.0.
indexed	boolean	Indicates whether the field is indexed (`true`) or not (`false`). If this field is unique or the externalId is set `true`, the isIndexed value is set to true. This field is available only in API version 14.0 and earlier.
inlineHelpText	string	Content of field-level help. For more information, see Define Field-Level Help.
isAIPredictionField	boolean	Available for number type custom fields when you use Einstein Prediction Builder. Indicates whether the field can store and display Einstein prediction data on an object (`true`) or not (`false`). Use Einstein Prediction Builder to determine the data for the target field. This field is available in API version 43.0 and later.
isFilteringDisabled	boolean	Available only for external objects. Indicates whether the custom field is available in filters (`true`) or not (`false`). This field is available in API version 32.0 and later.
isNameField	boolean	Available only for external object fields of type text. Indicates whether the custom field is the name field (`true`) or not (`false`). For each external object, you can specify one field as the name field. If you set this value to `true`, ensure the external table column identified by the externalDeveloperName attribute contains name values. This field is available in API version 32.0 and later.
isSortingDisabled	boolean	Available only for external objects. Indicates whether the custom field is sortable (`true`) or not (`false`). This field is available in API version 32.0 and later.
label	string	Label for the field. You can't update the label for standard picklist fields, such as the Industry field for accounts.
length	int	Length of the field.
lookupFilter	LookupFilter	Metadata associated with a lookup filter definition. This field is only available in API version 30.0 and earlier. The metadata associated with a lookup filter is now represented by the lookupFilter field in the CustomField component. LookupFilter isn't supported on the article type object.
maskChar	EncryptedFieldMaskChar (enumeration of type string)	For encrypted fields, specifies the character to be used as a mask. Valid values are: `asterisk` `X` This value pertains to Classic Encryption, not Shield Platform Encryption. For more information on encrypted fields, see Classic Encryption for Custom Fields in Salesforce Help.
maskType	EncryptedFieldMaskType (enumeration of type string)	For encrypted text fields, specifies the format of the masked and unmasked characters in the field. Valid values are: `all`—all characters in the field are hidden. This option is equivalent to the Mask All Characters option in Salesforce. `creditCard`—The first 12 characters are hidden and the last four appear. This option is equivalent to the Credit Card Number option in Salesforce. `lastFour`—all characters are hidden but the last four appear. This option is equivalent to the Last Four Characters Clear option in Salesforce. `nino`—all characters are hidden. Salesforce automatically inserts spaces after each pair of characters if the field contains nine characters. This option is equivalent to the National Insurance Number option in Salesforce. `sin`—all characters are hidden but the last four appear This option is equivalent to the Social Insurance Number option in Salesforce. `ssn`—The first five characters are hidden and the last four appear This option is equivalent to the Social Security Number option in Salesforce. This value pertains to Classic Encryption, not Shield Platform Encryption. For more information on encrypted fields, see Classic Encryption for Custom Fields in Salesforce Help.
metadataRelationshipControllingField	string	In custom metadata relationships, represents the controlling field that specifies the standard or custom object in an entity definition metadata relationship. Required when creating a field definition or entity particle metadata relationship on a custom metadata type. The object specified in the controlling field determines the values available in its dependent field definition or entity particle. For example, specifying the Account object filters the available fields in the field definition to Account fields only. This field is available in API version 39.0 and later.
picklist	Picklist	If specified, the field is a picklist, and this field counts the picklist values and labels. This field is available only in API version 37.0 and earlier. In later versions, use valueSet instead.
populateExistingRows	boolean	Indicates whether existing rows are going to be populated (`true`) or not (`false`).
precision	int	Precision, or number of digits in a number value. For example, the number 256.99 has a precision value of 5.
referenceTargetField	string	Specifies the custom field on the parent object to match against this indirect lookup relationship field, whose values come from an external data source. The specified custom field on the parent object must have both externalId and unique set to `true`. Available only for indirect lookup relationship fields on external objects. This field is available in API version 32.0 and later.
referenceTo	string	Reference this field has to another object.
relationshipLabel	string	Label for the relationship.
relationshipName	string	Value for one-to-many relationships. For example, if MyObject has a relationship to YourObject, the relationship name can be YourObjects.
relationshipOrder	int	This field is valid for all master-detail relationships, but the value is only non-zero for junction objects. A junction object has two master-detail relationships, and is analogous to an association table in a many-to-many relationship. Junction objects must define one parent object as primary (0), the other as secondary (1). The definition of primary or secondary affects delete behavior and inheritance of look and feel, and record ownership for junction objects. 0 or 1 are the only valid values, and 0 is always the value for objects that aren't junction objects.
reparentableMasterDetail	boolean	Indicates whether the child records in a master-detail relationship on a custom object can be reparented to different parent records (`true`) or not (`false`). The default value is `false`. This field is available in API version 25.0 and later.
required	boolean	Indicates whether the field requires a value on creation (`true`) or not (`false`).
scale	int	Scale, or the number of digits to the right of the decimal point in a number. For example, the number 256.99 has a scale of 2.
securityClassification	picklist	Sensitivity of the data contained in the field. Valid values are: `Public` `Internal` `Confidential` `Restricted` `MissionCritical` This field is available in API version 45.0 and later.
startingNumber	int	Starting number for the field. When you create records, the Starting Number value increments to store the number that will be assigned to the next auto number field created. You can’t retrieve the starting number of an auto number field through the Metadata API. To specify a Starting Number while deploying, add a `startingNumber` tag for your field to your package.xml file. For example: `<startingNumber>42</startingNumber>` If you deploy without specifying a Starting Number value in your package.xml file, the default starting number for standard fields is `0`. The default starting number for custom fields is `1`.
stripMarkup	boolean	Indicates whether to remove markup (`true`) or preserve it (`false`). Used when converting a rich text area to a long text area.
summarizedField	string	Field on the detail row that’s being summarized. This field can't be null unless the summaryOperation value is `count`.
summaryFilterItems	FilterItem[]	Set of filter conditions for this field if it's a summary field. This field is summed in the child if the filter conditions are met.
summaryForeignKey	string	Master-detail field on the child that defines the relationship between the parent and the child.
summaryOperation	SummaryOperations (enumeration of type string)	Represents the type of sum operation to be performed. Valid values are: `Count` `Min` `Max` `Sum`
trackFeedHistory	boolean	Indicates whether the field is enabled for feed tracking (`true`) or not (`false`). To set this field to `true`, the enableFeeds field on the associated CustomObject must also be `true`. For more information, see Customize Chatter Feed Tracking. This field is available in API version 18.0 and later.
trackHistory	boolean	Indicates whether history tracking is enabled for the field (`true`) or not (`false`). Also available for standard object fields (picklist and lookup fields only) in API version 30.0 and later. To set trackHistory to true, the enableHistory field on the associated standard or custom object must also be true. Field history tracking isn’t available for external objects.
trackTrending	boolean	Indicates whether historical trending data is captured for the field (`true`) or not (`false`). An object is enabled for historical trending if this attribute is `true` for at least one field. This field is available in API version 29.0 and later. For more information, see Report on Historical Changes.
trueValueIndexed	boolean	Relevant only for a checkbox field. If set, `true` values are built into the index. This field is available only in API version 14.0 and earlier.
type	FieldType (enumeration of type string)	Type of field. Optional for standard fields on standard objects. This field is included for some standard field types, such as picklist or lookup, but not for others. The type field is included for custom fields.
unique	boolean	Indicates whether the field is unique (`true`) or not (`false`).
valueSet	ValueSet	Set of values that make up a picklist on a custom field. Each value is defined as a CustomValue. If this custom field is a picklist that uses a global value set, valueSet is the name of the global value set whose values this picklist inherits. A custom picklist that uses a global value set is restricted. You can only add or remove values by editing the global value set. A ValueSet component has either a valueSetDefinition or a valueName specified, but never both. This field is available in API version 38.0 and later.
visibleLines	int	Number of lines shown for the field.
writeRequiresMasterRead	boolean	Minimum sharing access level required on the primary record to create, edit, or delete child records. This field applies only to master-detail or junction object custom field types. `true`—Allows users with Read access to the primary record permission to create, edit, or delete child records. This setting makes sharing less restrictive. `false`—Allows users with Read/Write access to the primary record permission to create, edit, or delete child records. This setting is more restrictive than `true`, and is the default value. For junction objects, the most restrictive access from the two parents is enforced. For example, if you set to `true` on both master-detail fields, but users have Read access to one primary record and Read/Write access to the other primary record, users aren't able to create, edit, or delete child records.

Fields use additional data types. For more information, see Metadata Field Types.

MktDataModelFieldAttributes

Represents the Data 360 data model field attributes for a custom field. This type is a subtype of CustomField.

Field Name	Field Type	Description
definitionCreationType	DefinitionCreationType enumeration	How the object was added. Valid values are: `Bridge` `Custom` `Derived` `Standard` `System` In API version 62.0 and later, additional valid values are: `Activation_Audience` `Ad_Audience_Insights` `ADG` `Calculated_Insight` `CG_Audience` `Chunk` `Directory_Table` `External` `Problem_Records` `Segment_Membership` `Semantic` `Transform` `Vector_Embedding` In API version 67.0 and later, additional valid values are: `Ad_Audience_Insights` `Auxiliary` `Clean_Room` `Deletion_Records` `Problem_Records`
invalidMergeActionType	InvalidMergeActionType (enumeration of type string)	Action to take when an invalid merge occurs for a field used to merge data. Valid values are: `Drop` `Keep` `Override`
isDynamicLookup	boolean	Indicates whether existing data is queried for the field’s unique values (`true`) or not (`false`).
labelOverride	string	Custom label that overrides the field’s default display label in the data model. If unspecified, the default label is used. Maximum length is 255 characters. This field is available in API version 65.0 and later.
mappingAlertType	MappingAlertType (enumeration of type string)	Type of alert shown when this field isn't mapped in the data model. This field is available in API version 65.0 and later. Valid values are: `None`—No alert is shown when the mapping is incomplete or invalid. `Warning`—A non-blocking warning is shown when the field mapping is incomplete or invalid. `Error`—A blocking error prevents saving when the mapping is invalid.
masterLabel	string	Master label for the field. Maximum length is 40 characters. This field is available in API version 65.0 and later.
primaryIndexOrder	int	Position of the field in the primary key, starting at `1`. If specified, the field is part of the primary key. For a compound primary key, the value specifies the field’s position in the key.
refAttrDeveloperName	string	Developer name of the field in the reference model. Applies only to standard fields.
mktDatalakeSrcKeyQualifier	string	Developer name of the MktDataLakeSrcKeyQualifier configured in the field.

MktDataLakeFieldAttributes

Represents the Data 360 data lake field attributes for a custom field. This type is a subtype of CustomField. Available in API version 50.0 or later.

Field Name	Field Type	Description
definitionCreationType	DefinitionCreationType (enumeration of type string)	How the object was added. Valid values are: `Bridge` `Custom` `Derived` `Standard` `System` In API version 62.0 and later, additional valid values are: `ADG` `Calculated_Insight` `CG_Audience` `Chunk` `Directory_Table` `External` `Semantic` `Vector_Embedding`
dateFormat	string	Optional date format of date and time fields. This field is available only in API version 55.0 and earlier.
externalName	string	External name of this field.
isEventDate	boolean	Indicates whether this field contains the event date for behavioral model area objects that are used to partition data (`true`) or not (`false`).
primaryIndexOrder	int	Position of the field in the primary key, starting at `1`. If specified, the field is part of the primary key. For a compound primary key, the value specifies the field’s position in the key.
isInternalOrganization	boolean	Indicates whether this field contains the value for internal organization (`true`) or not (`false`). The value of the field is the name of the internal organization. Landing objects don't have access to the Salesforce ID and use the developer name instead.
isRecordModified	boolean	Indicates whether the field is the record modified field used to calibrate latest record version (`true`) or not (`false`).
mktDatalakeSrcKeyQualifier	string	Developer name of the MktDataLakeSrcKeyQualifier configured in the field. This field is available in API version 55.0 and later.
keyQualifierName	string	Developer name of key qualifier field. This field is available in API version 55.0 and later.

LookupFilter

Represents the metadata associated with a lookup filter. Replaces the NamedFilter component, which was removed as of API version 30.0. LookupFilter is available in API version 30.0 and later.

Field	Field Type	Description
active	boolean	Required. Indicates whether the lookup filter is active (`true`) or not (`false`).
booleanFilter	string	Advanced filter conditions.
description	string	Description of what this filter does.
errorMessage	string	Error message that appears if the lookup filter fails.
filterItems	FilterItem[]	Required. Set of filter conditions. You can have up to 10 FilterItems per lookup filter.
infoMessage	string	Information message displayed on the page. Use this field describe things the user possibly doesn't understand, such as why certain items are excluded in the lookup filter.
isOptional	boolean	Required. Indicates whether the lookup filter is optional (`true`) or not (`false`).

Lookup filters use additional data types. For more information, see Metadata Field Types.

FilterItem

Represents one entry in a set of filter criteria.

Field	Field Type	Description
field	string	Name of the field specified in the filter.
operation	FilterOperation (enumeration of type string)	Filter operation for this filter item. Valid values are: `equals` `notEqual` `lessThan` `greaterThan` `lessOrEqual` `greaterOrEqual` `contains` `notContain` `startsWith` `includes` `excludes` `within` (`DISTANCE` criteria only)
value	string	Value of the filter item being operated on, for example, if the filter is `my_number_field__c > 1`, the value of `value` is `1`.
valueField	string	Final column in the filter contains a field or a field value. Approval processes don’t support valueField entries in filter criteria.

Declarative Metadata Sample Definition

The following example shows a field definition for a custom field that’s named Comments__c.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
3....
4<fields>
5        <fullName>Comments__c</fullName>
6        <description>Add your comments about this object here</description>
7        <inlineHelpText>This field contains help text for this object</inlineHelpText>
8        <label>Comments</label>
9        <length>32000</length>
10        <type>LongTextArea</type>
11        <visibleLines>30</visibleLines>
12</fields>
13....
14</CustomObject>

This XML is the definition for two fields on the Account standard object—a custom field (MyCustomAccountField__c), and a standard field (Phone) that has history tracking enabled.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
3    <fields>
4        <fullName>MyCustomAccountField__c</fullName>
5        <description>A custom field on the Account standard object.</description>
6        <externalId>false</externalId>
7        <inlineHelpText>Some help text.</inlineHelpText>
8        <label>MyCustomAccountField</label>
9        <length>100</length>
10        <required>false</required>
11        <trackFeedHistory>false</trackFeedHistory>
12        <trackHistory>false</trackHistory>
13        <type>Text</type>
14        <unique>false</unique>
15    </fields>
16    <fields>
17        <fullName>Phone</fullName>
18        <trackFeedHistory>false</trackFeedHistory>
19        <trackHistory>true</trackHistory>
20    </fields>
21</CustomObject>

Wildcard Support in the Manifest File

This metadata type doesn’t support the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.

Metadata API Developer Guide