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.

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.

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:

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:

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)

This type extends Metadata and inherits its fields.

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.

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.

When you retrieve a 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 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.

objects support these data types.

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

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

  • Type: string
  • Required: No
  • Introduced: API version 45.0
  • Description: 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.
  • Type: string
  • Required: No
  • Introduced: API version 45.0
  • Description: 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.
  • Type: string (enumeration of type string)
  • Required: No
  • Introduced: API version 45.0
  • Description: Indicates if the field is in use.
  • Possible values:
    • Active
    • DeprecateCandidate
    • Hidden

  • Type: boolean

  • Required: No

  • Description: 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.

  • Type: string (enumeration of type string)
  • Required: No
  • Introduced: API version 47.0
  • Description: Compliance acts, definitions, or regulations related to the field’s data.
  • Possible values:
    • CCPA
    • COPPA
    • GDPR
    • HIPAA
    • PCI
    • PII
  • Type: string
  • Required: No
  • Version: Deprecated in the Spring ‘19 (API version 45.0) release.
  • Description:
  • Type: string
  • Required: No
  • Description: If specified, represents the default value of the field.

  • Type: DeleteConstraint (enumeration of type string)

  • Required: No

  • Description: Deletion options for lookup relationships.

    For more information on lookup relationships, see Object Relationships Overview.

  • Possible values:

    • 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.
  • Type: boolean
  • Required: No
  • Description: Reserved for future use.
  • Type: string
  • Required: No
  • Description: Description of the field.
  • Type: string
  • Required: No
  • Description: Display format of the field.
  • Type: boolean
  • Required: No
  • Description: 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.
  • Type: ElementType (enumeration of type string)
  • Required: No
  • Description: Reserved for future use.
  • Type: EncryptionScheme (enumeration of type string)
  • Required: No
  • Introduced: API version 44.0
  • Description: For encrypted fields, determines which encryption scheme a field takes. This value pertains to Shield Platform Encryption, not Classic Encryption.
  • Possible values:
    • CaseInsensitiveDeterministicEncryption
    • CaseSensitiveDeterministicEncryption
    • None
    • ProbabilisticEncryption
  • Type: boolean
  • Required: No
  • Type: string
  • Required: No
  • Introduced: API version 32.0
  • Description: 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.
  • Type: boolean
  • Required: No
  • Description: 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.

  • Type: FieldManageability (enumeration of type string)

  • Required: No

  • Description: Determines who can update the field after it’s released in a managed package. 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.

  • Possible values:

    • 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.
  • Type: string
  • Required: No
  • Description: If specified, represents a formula on the field.
  • Type: TreatBlanksAs (enumeration of type string)
  • Required: No
  • Description: Indicates how to treat blanks in a formula. Valid values are BlankAsBlank and BlankAsZero.

  • Type: string

  • Required: No

  • Description: 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.

  • Type: string.
  • Required: No
  • Description: 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.
  • Type: boolean
  • Required: No
  • Description: 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.
  • Type: string
  • Required: No
  • Description: Content of field-level help. For more information, see Define Field-Level Help.
  • Type: boolean
  • Required: No
  • Introduced: API version 43.0
  • Description: 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.
  • Type: boolean
  • Required: No
  • Type: boolean
  • Required: No
  • Introduced: API version 32.0
  • Description: Available only for external objects. Indicates whether the custom field is available in filters (true) or not (false).
  • Type: boolean
  • Required: No
  • Introduced: API version 32.0
  • Description: 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.
  • Type: boolean
  • Required: No
  • Introduced: API version 32.0
  • Description: Available only for external objects. Indicates whether the custom field is sortable (true) or not (false).
  • Type: string
  • Required: No
  • Description: Label for the field. You can’t update the label for standard picklist fields, such as the Industry field for accounts.
  • Type: int
  • Required: No
  • Description: Length of the field.

  • Type: LookupFilter

  • Required: No

  • Description: 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.

  • Type: EncryptedFieldMaskChar (enumeration of type string)

  • Required: No

  • Description: For encrypted fields, specifies the character to be used as a mask.

    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.

  • Possible values:

    • asterisk
    • X

  • Type: EncryptedFieldMaskType (enumeration of type string)

  • Required: No

  • Description: For encrypted text fields, specifies the format of the masked and unmasked characters in the field.

    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.

  • Possible values:

    • 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.
  • Type: string
  • Required: No
  • Introduced: API version 39.0
  • Description: 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.
  • Type: Picklist
  • Required: No
  • Description: 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.
  • Type: boolean
  • Required: No
  • Description: Indicates whether existing rows are going to be populated (true) or not (false).
  • Type: int
  • Required: No
  • Description: Precision, or number of digits in a number value. For example, the number 256.99 has a precision value of 5.
  • Type: string
  • Required: No
  • Introduced: API version 32.0
  • Description: 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.
  • Type: string
  • Required: No
  • Description: Reference this field has to another object.
  • Type: string
  • Required: No
  • Description: Label for the relationship.
  • Type: string
  • Required: No
  • Description: Value for one-to-many relationships. For example, if MyObject has a relationship to YourObject, the relationship name can be YourObjects.

  • Type: int

  • Required: No

  • Description: 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.

  • Type: boolean
  • Required: No
  • Introduced: API version 25.0
  • Description: 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.
  • Type: boolean
  • Required: No
  • Description: Indicates whether the field requires a value on creation (true) or not (false).
  • Type: boolean
  • Required: No
  • Type: int
  • Required: No
  • Description: 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.
  • Type: string (enumeration of type string)
  • Required: No
  • Introduced: API version 45.0
  • Description: Sensitivity of the data contained in the field.
  • Possible values:
    • Public
    • Internal
    • Confidential
    • Restricted
    • MissionCritical

  • Type: int

  • Required: No

  • Description: 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.
  • Type: boolean
  • Required: No
  • Description: Indicates whether to remove markup (true) or preserve it (false). Used when converting a rich text area to a long text area.
  • Type: string
  • Required: No
  • Description: Field on the detail row that’s being summarized. This field can’t be null unless the summaryOperation value is count.
  • Type: FilterItem[]
  • Required: No
  • Description: 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.
  • Type: string
  • Required: No
  • Description: Master-detail field on the child that defines the relationship between the parent and the child.
  • Type: SummaryOperations (enumeration of type string)
  • Required: No
  • Description: Represents the type of sum operation to be performed.
  • Possible values:
    • Count
    • Min
    • Max
    • Sum
  • Type: boolean
  • Required: No
  • Introduced: API version 18.0
  • Description: 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.

  • Type: boolean

  • Required: No

  • Description: 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.

  • Type: boolean
  • Required: No
  • Introduced: API version 29.0
  • Description: 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. For more information, see Report on Historical Changes.
  • Type: boolean
  • Required: No
  • Type: boolean
  • Required: No
  • Description: 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)
  • Required: No
  • Description: 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.
  • Type: boolean
  • Required: No
  • Description: Indicates whether the field is unique (true) or not (false).

  • Type: ValueSet

  • Required: No

  • Introduced: API version 38.0

  • Description: 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.

  • Type: int
  • Required: No
  • Description: Number of lines shown for the field.

  • Type: boolean (enumeration of type string)

  • Required: No

  • Description: 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.

    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.

  • Possible values:

    • 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.

Represents one entry in a set of filter criteria.

  • Type: string
  • Required: Yes
  • Description: Name of the field specified in the filter.
  • Type: FilterOperation (enumeration of type string)
  • Required: Yes
  • Description: Filter operation for this filter item.
  • Possible values:
    • equals
    • notEqual
    • lessThan
    • greaterThan
    • lessOrEqual
    • greaterOrEqual
    • contains
    • notContain
    • startsWith
    • includes
    • excludes
    • within — (DISTANCE criteria only)
  • Type: string
  • Required: No
  • Description: 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.
  • Type: string
  • Required: No
  • Description: Final column in the filter contains a field or a field value. Approval processes don’t support valueField entries in filter criteria.

Represents the metadata associated with a lookup filter.

Introduced in API version 30.0.

Replaces the NamedFilter component, which was removed as of API version 30.0.

  • Type: boolean
  • Required: Yes
  • Description: Required. Indicates whether the lookup filter is active (true) or not (false).
  • Type: string
  • Required: No
  • Description: Advanced filter conditions.
  • Type: string
  • Required: No
  • Description: Description of what this filter does.
  • Type: string
  • Required: No
  • Description: Error message that appears if the lookup filter fails.
  • Type: FilterItem[]
  • Required: No
  • Description: Required. Set of filter conditions. You can have up to 10 FilterItems per lookup filter.
  • Type: string
  • Required: No
  • Description: 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.
  • Type: boolean
  • Required: Yes
  • Description: 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.

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

Introduced in API version 50.0.

  • Type: string
  • Required: No
  • Description: Optional date format of date and time fields. This field is available only in API version 55.0 and earlier.

  • Type: DefinitionCreationType (enumeration of type string)

  • Required: No

  • Description: How the object was added.

    In API version 62.0 and later, additional

  • Possible values:

    • Bridge
    • Custom
    • Derived
    • Standard
    • System
    • ADG
    • Calculated_Insight
    • CG_Audience
    • Chunk
    • Directory_Table
    • External
    • Semantic
    • Vector_Embedding
  • Type: string
  • Required: No
  • Description: External name of this field.
  • Type: boolean
  • Required: No
  • Description: Indicates whether this field contains the event date for behavioral model area objects that are used to partition data (true) or not (false).
  • Type: boolean
  • Required: No
  • Description: 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.
  • Type: boolean
  • Required: No
  • Description: Indicates whether the field is the record modified field used to calibrate latest record version (true) or not (false).
  • Type: string
  • Required: No
  • Introduced: API version 55.0
  • Description: Developer name of key qualifier field.
  • Type: string
  • Required: No
  • Introduced: API version 55.0
  • Description: Developer name of the MktDataLakeSrcKeyQualifier configured in the field.
  • Type: int
  • Required: No
  • Description: 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.
  • Type: UsageTag (enumeration of type string)
  • Required: No

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

  • Type: DefinitionCreationType (enumeration of type string)

  • Required: No

  • Description: How the object was added.

    In API version 62.0 and later, additional

    In API version 67.0 and later, additional

  • Possible values:

    • Bridge
    • Custom
    • Derived
    • Standard
    • System
    • Activation_Audience
    • Ad_Audience_Insights
    • ADG
    • Calculated_Insight
    • CG_Audience
    • Chunk
    • Directory_Table
    • External
    • Problem_Records
    • Segment_Membership
    • Semantic
    • Transform
    • Vector_Embedding
    • Auxiliary
    • Clean_Room
    • Deletion_Records
  • Type: InvalidMergeActionType (enumeration of type string)
  • Required: No
  • Description: Action to take when an invalid merge occurs for a field used to merge data.
  • Possible values:
    • Drop
    • Keep
    • Override
  • Type: boolean
  • Required: No
  • Description: Indicates whether existing data is queried for the field’s unique values (true) or not (false).
  • Type: string
  • Required: No
  • Type: string
  • Required: No
  • Introduced: API version 65.0
  • Description: 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.
  • Type: MappingAlertType (enumeration of type string)
  • Required: No
  • Introduced: API version 65.0
  • Description: Type of alert shown when this field isn’t mapped in the data model.
  • Possible values:
    • 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.
  • Type: string
  • Required: No
  • Introduced: API version 65.0
  • Description: Master label for the field. Maximum length is 40 characters.
  • Type: string
  • Required: No
  • Description: Developer name of the MktDataLakeSrcKeyQualifier configured in the field.
  • Type: int
  • Required: No
  • Description: 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.
  • Type: string
  • Required: No
  • Description: Developer name of the field in the reference model. Applies only to standard fields.
  • Type: MktDataModelFieldUsageTag (enumeration of type string)
  • Required: No
  • Type: string
  • Required: No
  • Type: boolean
  • Required: No
  • Type: string
  • Required: No
  • Type: string[]
  • Required: No
  • Type: string
  • Required: Yes
  • Type: boolean
  • Required: Yes

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

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.

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.