##########
Field Path
##########

A FieldPath is a sequence of :doc:`/classes/field` instances that represent the path from the root of the schema down to a particular Field that is of interest.

If a Field instance is a "what", then a FieldPath is a "where". You can pretty easily think of a FieldPath as an array of strings where each item is the name of a field.

.. tip:: FieldPath is an appropriate tool when thinking about and interacting with schema information, but for actual record interactions we'll use :doc:`/extension-concepts/property-path`.

********************
Building an Instance
********************

.. code-block:: java

	global static FieldPath buildPath(List<Field> fields);

	global static FieldPath buildPath(Field field);

	global static FieldPath buildPath(List<String> fieldNames);

	global static FieldPath buildPath(String fieldName);

****************
Instance Methods
****************

.. code-block:: java

	// get the full chain of Fields
	global List<Field> getSequence()

	// get the Field at the end of the chain (the leaf)
	global Field getLast()

	// get the the field name of each Field in the sequence
	global List<String> getSimplePath()

*******
Example
*******

Suppose you are working with the **LastName** field on the **Contact** object in Salesforce.

If we were just working within the **Contact** object, getSequence() would be a List with one Field instance:

.. code-block:: java

	// [LastName]

	List<Field> fields = path.getSequence();
	fields.size(); // 1
	fields[0].name; // LastName
	fields[0].type; // STRING
	fields[0].isRequired; // true
	fields[0].isList; // false

However, what if we were actually building a Link against the **Account** object, and wanted to refer to related **Contact** records? There is a Master-Detail field **Contact.AccountId**, whose inverse from the **Account** side is called **Contacts** (with an S).

So in this scenario, from the perspective of the **Account** object, we'd be interested in looking at **Contacts.LastName**.

.. code-block:: java

	// [Contacts,LastName]

	List<Field> fields = path.getSequence();
	fields.size(); // 2

	fields[0].name; // Contacts
	fields[0].type; // CHILDREN
	fields[0].isRequired; // false
	fields[0].isList; // true

	fields[1].name; // LastName
	fields[1].type; // STRING
	fields[1].isRequired; // true
	fields[1].isList; // false

So the same Field (**Contact.LastName**) might be referenced with different paths. You might even have the same Field referenced by different paths in the same schema.

FieldPath helps us encapsulate this and makes it easier to work with arbitrarily-nested Fields.

.. warning::

    As you can see from methods like buildPath(List<String> fieldNames), sometimes you will have a FieldPath whose Field instances have sparsely-populated properties (in this example, only Field.name would have a value); **name** and **isList** are the only two properties you can safely assume will always be set.