Entities, Bundles, Fields and Field instances

Drupal 7 introduces a number of new apis and with those comes new jargon. Untangling that could be daunting. I'll try to briefly sketch what is what and relate it to terminology outside of the Drupal world.

This post is a work in progress, I am regularly revising the text from feedback.

Note Revised paragraph order and wording, clarified wording of definitions, added references, corrected glitches


An entity is an abstract data type in drupal. An Entity type is required to implement the Entity interfaces as defined in the core Entity API. It is a generalisation of the node, comment, user, taxonomy term types of previous versions of Drupal. In Drupal 7, only the R from CRUD is specified in core, but work is underway to fill the gap in next versions. There is a contributed Entity API module, which aims to do it. Entities can have multiple bundles


Bundles are groups of fields. A bundle is a specialisation, an instance of an entity. If node is an entity, then an article is an bundle. This allows distinguishing the kinds and types within the system - kinds classify types, types classify values (concrete objects)


Fields are the incarnation of the CCK data type of the same name moved to Drupal core. What are they? The answer can be found by reading Field Api. In essence, a field is a primitive drupal data type implementing the interface described in those pages. Fields have an associated schema, formatter(s), widget(s) and settings. Example field types - file field, text field, etc... Modules can define new field types.

Field Instances

A Field Instance is a concrete specialisation of a field type. It captures the field type together with its configuration - schema, formatter and widget. Field instances are attached to bundles.

Fieldable objects

The term is sometimes used for entities and bundles.

This concludes the quick jargon tour. And last something to ponder - can a field be an entity?


  1. Field API
  2. Field API datastructures
  3. Entity API contributed module. Provides Entity CRUD and metadata
  4. Drupal 7 Entities And Fields-Transitioning To D7 presentation slides from Copenhagen
  5. Drupal 7 Entities And Fields-Transitioning To D7 video of the presentation
  6. How Drupal 7 fields are changing the way you write modules

Needs some work...

- 'Entities are "abstract" types of things'
- 'Entities are required to implement the Entity interfaces as defined in the core Entity API.'

Should I be using these definitions in a training?

your call

Can't judge. Don't know your audience. But you are right - the definitions or explanations in words do need more work. Part of the problem is that it is not yet the middle of the road of the evolution of entities, and we are still half blind.


Strictly speaking Entities are the generalisation of the node, comment and co types. What kind of generalisation? That is defined by the interface described in hook_entity_info.

Entities are abstract, as you can't make a concrete entity value. That is an entity value is an entity type. For example the node entity has values post, blog, story in older versions of drupal. The kind, or the type of a type, the classes of types are other explanations which apply IMHO, but all of these are overloaded with other meaning and not that precise - the first one is least problematic, just assume loose typing.

The core Drupal api is unifying the treatment of entities via the DrupalEntityControllerInterface. Currently are required load, and resetCache, the rest is still left to the entity type definitions hook_entity_info and family.


I revised the text to be more compact. Added references. If you have others, please add in a comment.

Powered by Drupal, an open source content management system