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.
Only standard fields that you can customize are supported, that is, standard fields to which you can add help text or enable history tracking or Chatter feed tracking. Other standard fields aren't supported, including system fields (such as CreatedById or LastModifiedDate) and autonumber fields. All standard picklist fields are supported except for Lead.CampaignMemberStatus, Opportunity.ForecastCategoryName, and Order.Status.
You must specify the full name whenever you create or update a field. For example, a custom field on a custom object:
An example of a custom field on a standard object:
An example of a standard field on a standard object:
An example of a custom field on an external object:
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.
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 will create the files objects/MyCustomObject__c.object and objects/Account.object, each containing the requested field definitions.
<types> <members>MyCustomObject__c.MyCustomField__c</members> <members>Account.MyCustomAccountField__c</members> <members>Account.Phone</members> <name>CustomField</name> </types>
Custom and standard fields are available in API version 10.0 and later.
|Field Name||Field Type||Description|
|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.
|defaultValue||string||If specified, represents the default value of the field.|
|deleteConstraint||DeleteConstraint (enumeration of type string)||
Provides deletion options for lookup
relationships. Valid values are:
|deprecated||boolean||Reserved for future use.|
|description||string||Description of the field.|
|displayFormat||string||The display format.|
|displayLocationInDecimal||boolean||Indicates how the value of a Geolocation custom field appears in the user interface. If true, the geolocation appears in decimal notation. If false, the geolocation appears as degrees, minutes, and seconds.|
|encrypted||boolean||true) or not (false). This field is available in API version 34.0 and later.Indicates whether this field is encrypted (|
|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 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).|
|formula||string||If specified, represents a formula on the field.|
|formulaTreatBlankAs||TreatBlanksAs (enumeration of type string)||Indicates how to treat blanks in a formula. Valid values are BlankAsBlank and BlankAsZero.|
|fullName||string||Inherited from Metadata, this field is not defined in the WSDL for this metadata type. It must be specified when creating, updating, or deleting. See create() to see an example of this field specified for a call.|
|indexed||boolean||Indicates if the field is indexed. If this field is unique or the externalId is set true, the isIndexed value is set to true. This field has been deprecated as of version 14.0 and is only provided for backward compatibility.|
|inlineHelpText||string||Represents the content of field-level help. For more information, see “Defining Field-Level Help” in the Salesforce Help.|
|isFilteringDisabled||boolean||Available only for external objects. Indicates whether the custom field is available in filters. This field is available in API version 32.0 and later.|
|isNameField||boolean||Available only for external object fields of type text. For each external object, you can specify one field as the name field. If you set this to true, make sure that 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. This field is available in API version 32.0 and later.|
Indicates whether the
child records in a master-detail relationship on a custom object
can be reparented to different parent records. The default value
This field is available in API version 25.0 and later.
|label||string||Label for the field. You cannot update the label for standard picklist fields, such as the Industry field for accounts.|
|length||int||Length of the field.|
Represents the metadata associated with a lookup
filter. Use this metadata type to create, update, or delete lookup
This field is available in API version 30.0 and later.
|maskChar||EncryptedFieldMaskChar (enumeration of type string)||
For encrypted fields, specifies the character to be used as a
mask. Valid values are enumerated in |
For more information on encrypted fields, see “Classic Encryption for Custom Fields” in the Salesforce Help.
|maskType||EncryptedFieldMaskType (enumeration of type string)||EncryptedFieldMaskType For more information on encrypted fields, see “Classic Encryption for Custom Fields” in the Salesforce Help.For encrypted text fields, specifies the format of the masked and unmasked characters in the field. Valid values are enumerated in|
|picklist||Picklist||If specified, the field is a picklist, and this field enumerates the picklist values and labels.|
|populateExistingRows||boolean||Indicates whether existing rows will be populated (true) or not (false).|
|precision||int||The precision for number values. Precision is the number of digits in a number. For example, the number 256.99 has a precision of 5.|
|referenceTargetField||string||Available only for indirect lookup relationship fields on external objects. 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. This field is available in API version 32.0 and later.|
|referenceTo||string||If specified, indicates a reference this field has to another object.|
|relationshipLabel||string||Label for the relationship.|
|relationshipName||string||If specified, indicates the value for one-to-many relationships. For example, in the object MyObject that had a relationship to YourObject, the relationship name might 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. For more information, see the Salesforce Help.|
|required||boolean||Indicates whether the field requires a value on creation (true) or not (false).|
|scale||int||The scale for the field. Scale is 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.|
|startingNumber||int||If specified, indicates the starting number for the field. When you create records, Starting Number’s value increments to store the number that will be assigned to the next auto-number field created.|
|stripMarkup||boolean||Set to true to remove markup, or false to preserve markup. Used when converting a rich text area to a long text area.|
|summarizedField||string||Represents the field on the detail row that is being summarized. This field cannot be null unless the summaryOperation value is count.|
|summaryFilterItems||FilterItem||Represents the set of filter conditions for this field if it is a summary field. This field will be summed on the child if the filter conditions are met.|
|summaryForeignKey||string||Represents the master-detail field on the child that defines the relationship between the parent and the child.|
|summaryOperation||SummaryOperations (enumeration of type string)||Represents the sum operation to be performed. Valid values are enumerated in SummaryOperations.|
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” in the Salesforce
This field is available in API version 18.0 and later.
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.
For more information, see “Track Field History” in the Salesforce Help.
Field history tracking isn’t available for external objects.
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.
Available in API
version 29.0 and later.
For more information, see “Report on Historical Changes” in the Salesforce Help.
|trueValueIndexed||boolean||This is only relevant for a checkbox field. If set, true values are built into the index. This field has been deprecated as of API version 14.0 and is only provided for backward compatibility.|
|type||FieldType||Indicates the field type for the field. Valid values are
enumerated in FieldType.
For standard fields on standard objects, the type field is optional. 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).|
|visibleLines||int||Indicates the number of lines displayed for the field.|
Sets the minimum sharing
access level required on the master record to create, edit, or
delete child records. This field applies only to master-detail
or junction object custom field types.
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 master record and “Read/Write” access to the other master record, users won't be able to create, edit, or delete child records.
Fields use additional data types. For more information, see Metadata Field Types.
This field type is used in maskChar. It is a string with two valid values: asterisk or X. For more information on encrypted fields, see Classic Encryption for Custom Fields in the Salesforce online help.
This field type is used in maskType. Valid values are:
For more information on encrypted fields, see Classic Encryption for Custom Fields in the Salesforce online help.
|active||boolean||Required. Indicates whether or not the lookup filter is active.|
|booleanFilter||string||Specifies advanced filter conditions. For more information on advanced filter conditions, see “Getting the Most Out of Filter Logic” in the Salesforce Help.|
|description||string||A description of what this filter does.|
|errorMessage||string||The error message that appears if the lookup filter fails.|
|filterItems||FilterItem||Required. The set of filter conditions. You can have up to 10 FilterItems per lookup filter.|
|infoMessage||string||The information message displayed on the page. Use to describe things the user might not understand, such as why certain items are excluded in the lookup filter.|
|isOptional||boolean||Required. Indicates whether or not the lookup filter is optional.|
Lookup filters use additional data types. For more information, see Metadata Field Types.
Represents one entry in a set of filter criteria.
|field||string||Represents the field specified in the filter.|
|operation||FilterOperation (enumeration of type string)||Represents the filter operation for this filter item. Valid values are enumerated in FilterOperation.|
|value||string||Represents the value of the filter item being operated upon, for example, if the filter is my_number_field__c > 1, the value of value is 1.|
|valueField||string||Specifies if the final column in the filter contains a field or a
Approval processes don't support valueField entries in filter criteria.
This is an enumeration of type string that lists different filter operations. Valid values are:
Represents the type of a summaryOperation. Valid values are:
The following example shows a field definition for a custom field that is named Comments__c.
<?xml version="1.0" encoding="UTF-8"?> <CustomObject xmlns="http://soap.sforce.com/2006/04/metadata"> .... <fields> <fullName>Comments__c</fullName> <description>Add your comments about this object here</description> <inlineHelpText>This field contains help text for this object</inlineHelpText> <label>Comments</label> <length>32000</length> <type>LongTextArea</type> <visibleLines>30</visibleLines> </fields> .... </CustomObject>
The following 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.
<?xml version="1.0" encoding="UTF-8"?> <CustomObject xmlns="http://soap.sforce.com/2006/04/metadata"> <fields> <fullName>MyCustomAccountField__c</fullName> <description>A custom field on the Account standard object.</description> <externalId>false</externalId> <inlineHelpText>Some help text.</inlineHelpText> <label>MyCustomAccountField</label> <length>100</length> <required>false</required> <trackFeedHistory>false</trackFeedHistory> <trackHistory>false</trackHistory> <type>Text</type> <unique>false</unique> </fields> <fields> <fullName>Phone</fullName> <trackFeedHistory>false</trackFeedHistory> <trackHistory>true</trackHistory> </fields> </CustomObject>