FieldDefinition

Represents a standard or custom field, providing row-based access to field metadata. Contrast FieldDefinition with EntityParticle, which represents each element of a field that can be presented in a user interface. FieldDefinition has parity with metadata type Field.

Introduced in API version 32.0.

describeSObjects(), query(), search()

Query

SOQL Limitations

SOSL Limitations

• Type: reference

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 41.0

• Description: Indicates the person or group associated with this field. The business owner understands the importance of the field’s data to your company and might be responsible for determining the minimum security classification.

• Relationship name: BusinessOwner

• Relationship type: polymorphic

• Refers to: Group, User

• Type: picklist

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 41.0

• Description: Indicates whether the field is in use. Valid values include:

This field is available in API version 45.0 and later.

• Possible values:

  • Active — Active

  • DeprecateCandidate — DeprecateCandidate

  • Hidden — Hidden

• Type: multipicklist

• Required: No

• Properties: Filter, Nillable

• Introduced: API version 47.0

• Description: The compliance acts, definitions, or regulations related to the field’s data. Valid values include:

This field is available in API version 47.0 and later.

• Possible values:

  • PII — PII — Personally Identifiable Information

  • HIPAA — HIPAA — Health Insurance Portability and Accountability Act

  • GDPR — GDPR — General Data Protection Regulation

  • PCI — PCI — Payment Card Industry

  • COPPA — COPPA — Children’s Online Privacy Protection Act

  • CCPA — CCPA — California Consumer Privacy Act

  • PersonalInfo — PersonalInfo — Personal information. For use with the Enhanced Personal Information Management feature. Only available if Enhanced Personal Information Management and Digital Experiences are enabled.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 34.0

• Description: The ID of the ControllingFieldDefinition for this field. Available in Tooling API starting version 34.0.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 33.0

• Description: Data type of the field, for example Text(40) or Date/Time. The values are defined as they are in the user interface, not the corresponding API data type names. Available in Tooling API starting version 34.0.

• Type: textarea

• Required: No

• Properties: Filter, Nillable, Sort

• Introduced: API version 41.0

• Description: A description of the field definition.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Description: The unique name of the object in the API. This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. In managed packages, this field prevents naming conflicts on package installations. With this field, a developer can change the object’s name in a managed package and the changes are reflected in a subscriber’s org. Label is Record Type Name.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Description: Unique identifier for the field. Always retrieve this value before using it, because the value isn’t guaranteed to stay the same from one release to the next. To simplify queries, use this field.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Description: The durable ID for the object defined in the EntityDefinition field.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 34.0

• Description: Represents further definition of a type. Available in Tooling API starting version 34.0.

• For type textarea:

• plaintextarea

• richtextarea

• For type URL, image

• For type reference,

• externallookup

• indirectlookup

• externallookup

• For Account,

• switchablepersonname

• personname

• Type: string

• Required: No

• Properties: Create, Group, Nillable

• Description: The full name of the associated metadata object in Metadata API.

Query this field only if the query result contains no more than one record. Otherwise, an error is returned. If more than one record exists, use multiple queries to retrieve the records. This limit protects performance.

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field can be specified in the WHERE clause of a query string.

Available in Tooling API starting version 34.0.

You can’t sort or filter compound fields. This field’s value is always false for compound fields.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field can be included in the GROUP BY clause of a SOQL query. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, a query can sort on this field.

Available in Tooling API starting version 34.0.

You can’t sort or filter compound fields. This field’s value is always false for compound fields.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field’s value is calculated. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Description: If true, the field can be included in a compact layout. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 38.0

• Description: If true, the field is a compound of other fields. The default value is false. Available in Tooling API starting version 38.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 49.0

• Description: If true, the field is describable in the API. The default value is false. Available in Tooling API starting version 49.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field’s history can be tracked. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 35.0

• Description: If true, you can set field-level security on this field. Available in Tooling API starting version 35.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: Indicates whether the field stores numbers to eight decimal places regardless of what’s specified in the field details (true) or not (false). Used to handle currencies for products that cost fractions of a cent, in large quantities. If high-scale unit pricing isn’t enabled in your organization, this field isn’t returned. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field contains HTML. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 35.0

• Description: If true, the field is indexed in the database.

Internal (database) indexing is different from indexing for search.

We recommend targeting indexed fields for better response times in SOQL queries, reports, and list views.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field can be filtered for a related list. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field can be sorted for a related list. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field can be included in a related list. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field is a name field. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 34.0

• Description: If true, the field can be left out of queries on the object. Available in Tooling API starting version 34.0.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 41.0

• Description: Indicates whether the foreign key includes multiple object types (true) or not (false).

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Introduced: API version 40.0

• Description: Indicates whether a foreign key can be included in prefiltering (true) or not (false) when used in a SOSL WHERE clause. Prefiltering means to filter by a specific field value before executing the full search query. Prefiltering is supported only in WHERE clauses with the equals (=) operator.

• Default value: false

• Type: boolean

• Required: No

• Properties: Defaulted on create, Filter, Group, Sort

• Description: If true, the field can be filtered for a workflow. Available in Tooling API starting version 34.0.

• Default value: false

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Description: The label that corresponds to the field in the user interface. If the label has been translated, the value returned is in the user’s language.

• Type: int

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 34.0

• Description: The maximum number of bytes available to store the value in this field. Available in Tooling API starting version 34.0.

• Type: string

• Required: No

• Properties: Filter, Group, Sort

• Description: Primary label for this object. This display value is the internal label that isn’t translated. Limit: 40 characters.

• Type: complexvalue

• Required: No

• Properties: Create, Nillable, Update

• Description: Compact layout metadata, from the mns namespace.

Query this field only if the query result contains no more than one record. Otherwise, an error is returned. If more than one record exists, use multiple queries to retrieve the records. This limit protects performance.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Description: The namespace prefix associated with this object. Each Developer Edition org that creates a managed package has a unique namespace prefix. Limit: 15 characters. You can refer to a component in a managed package by using the namespacePrefix__componentName notation.

The namespace prefix can have one of the following values:

• In a Developer Edition org, the namespace prefix is set to the namespace prefix of the org for all objects that support it. There’s an exception if an object is in an installed managed package. In that case, the object has the namespace prefix of the installed managed package. This field’s value is the namespace prefix of the Developer Edition org of the package developer.
• In an org other than a Developer Edition org, NamespacePrefix is only set for objects that are part of an installed managed package. There’s no namespace prefix for all other objects.

• Type: int

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 34.0

• Description: The maximum number of digits allowed for this field. Available in Tooling API starting version 34.0.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 34.0

• Description: ID of the publisher associated with this field. Available in Tooling API starting version 34.0.

• Type: string

• Required: No

• Properties: Filter, Group, Sort

• Description: A unique external name for the field.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 34.0

• Description: Available only for indirect lookup relationship fields on external objects. Specifies the 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 in Tooling API starting version 34.0.

• Type: complexvalue

• Required: No

• Properties: Nillable

• Introduced: API version 34.0

• Description: The array of values in this field represents the possible object types of the referenced objects. For example, if a FieldDefinition represents a field on Event.WhoId, the values in this field are Contact, Lead, and custom objects with a relationship to Events. Available in Tooling API starting version 34.0.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 34.0

• Description: The value for one-to-many relationships. For example, in the object MyObject with a relationship to YourObject, the relationship name is typically YourObjects. Available in Tooling API starting version 34.0.

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 34.0

• Description: Reserved for internal use. Available in Tooling API starting version 34.0.

• Type: int

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 34.0

• Description: The number of digits to the right of the decimal in an integer. For example, 3.00 has a scale of 2. Available in Tooling API starting version 34.0.

• Type: picklist

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 41.0

• Description: Indicates the sensitivity of the data contained in this field. Valid values include: This field is available in API version 45.0 and later.

• Possible values:

  • Public — Public

  • Internal — Internal

  • Confidential — Confidential

  • Restricted — Restricted

  • MissionCritical — MissionCritical

• Type: string

• Required: No

• Properties: Filter, Group, Nillable, Sort

• Introduced: API version 35.0

• Description: The ID of the ValueType. Available in Tooling API version 35.0.

When querying or searching the FieldDefinition object, you must filter using the following syntax: WHERE EntityDefinition.QualifiedApiName ='[ObjectAPIName]'.

Example Query:

1SELECT DurableId, QualifiedApiName, Label, DataType, ValueTypeId, PublisherId, Length, Precision, Scale, EntityDefinitionId, RelationshipName
2    FROM FieldDefinition
3    WHERE EntityDefinition.QualifiedApiName = 'Customer_Sat_Survey__c' ORDER BY Label ASC NULLS FIRST

Example Query: Find Parent Object Types

Some fields can have more than one type of object in a relationship (polymorphic). For example, Task and Event can have relationships with Contact or Lead.

Use this query to retrieve a list of objects that can have a relationship with the FieldDefinition.

1SELECT QualifiedApiName, RelationshipName, ReferenceTo, ReferenceTargetField 
2FROM FieldDefinition
3WHERE EntityDefinition.QualifiedApiName = 'Event' AND QualifiedApiName = 'WhoId'

Example Query: Find the Datatypes for Account Fields

1SELECT QualifiedApiName, (Select DataType From Particles)
2FROM FieldDefinition
3WHERE EntityDefinition.QualifiedApiName ='Account'

This metadata type defines a value in the picklist and specifies whether this value is the default value. This type extends Metadata and inherits its fullName field.

Note the following when working with picklist values:

• When you retrieve a standard object, all picklist values are retrieved, not just the customized picklist values.
• When you deploy changes to standard picklist fields, picklist values are added as needed.
• You can’t set a picklist value as inactive, but if the picklist value is missing and you invoke an update() call, the missing value becomes inactive.

For more information about WorkflowFieldUpdate, see the Metadata API Developer Guide.