We have seen four years and Drupal 8's first release since the accepted answer was written for the question "When is it appropriate to create an Entity versus just adding a new content type?" And, entities are more central to Drupal 8 than they were in Drupal 7.(RefB, RefC, RefD)

In this new Drupal 8 world, what is the decision tree for creating a new content entity type versus a new Content Type for the content entity of type "Node"?

As you consider a response, please consider the following:

  • Is a new Content Type for the content entity type of "Node" still appropriate in 99% situations versus a new content entity type?
  • Does the decision tree now include more, better, or clearer reasons to veer away from using the "Node" content entity type and instead create a new content entity type? And if yes, what are they? Do they include:
    • Performance?
    • Security/permissions?
    • The number of modules that work with Node-entity-type Content-Types and do not work with other content entity types?
  • Perhaps -- based on the previous accepted answer that is referenced above -- the only general reason to do a custom content entity type is if you want to group Node data, e.g. with taxonomy terms, or otherwise annotate Node, e.g. with comments?

Module compatibility seems like a particularly interesting consideration for a decision tree. At present, few of the most-installed modules have a release for 8.x that is not merely alpha, beta, or rc (a release candidate). And it seems difficult to identify how many of them will work out-of-the-box with a new custom entity type versus a new Node-entity content type. There does not appear to be a project attribute to distinguish between those that are "written for entities" versus "written for node entity content types".

Take a look at pathauto, which is currently the fourth-most installed module of those that have any kind of 8.x release. Folks are working hard on a 8.x version that generally supports entities and not just Node-entity-type Content Types. But what about all the other modules? And will modules that support entities going to generally require custom content entity types to have module-specific "hooks" before the module will work with them? (Versus how the modules may just work straight out of the box with new Content Types?) That appears to be the kind of challenge the pathauto team is working with, and perhaps it is a reason to veer away from a custom content entity type?

It might also be worth mentioning that Drupal 8 core contains a UI for creating new Content Types for the content entity of type "Node", but it does not currently contain a UI for creating new content entity types. (RefX, RefY, RefZ)


4 Answers 4


Decision tree for choosing between creating a new Node-entity-type Content Type versus a new content entity type:

  1. Are you a programmer, or do you have easy access to a programmer?
    • If no, then you are presently pretty-much limited to creating new Node-entity Content Types. (There isn't a UI in core for creating new content entity types, and the Entity Construction Kit (ECK) contrib module currently only has an alpha release.)
    • If yes, then continue...
  2. Do you know exactly which contrib modules you want to leverage for your data?
    • If no, then the safe bet is probably to just create a Node-entity Content Type.
    • If yes, do those modules already support the custom entity type(s) you're considering, or are you willing to help enhance them so they will or recreate the desired functionality in your module?
      • If no, then just creating a Node-entity-type Content Type may be best for you.
      • If yes, then continue...
  3. Will the actual content data that is enabled by your module merely help group or annotate other content data? (So that it will seldom be viewed on its own.)
    • If yes, then consider whether your module is like the existing entity types for taxonomy terms and comments. If it is, then a new entity type may be a safe bet.
    • If no, then continue...
  4. Can you clearly articulate why a new Node-entity-type Content Type will not work for you?
    • If no, then your safe bet is to probably just create a new Node-entity-type Content Type.
    • If yes, then continue...
  5. Lastly, are you sure that you can't just extend the Node-entity-type and that you want to recreate all of its useful functionality like CRUD operations?
    • If yes, then go ahead and create a new custom entity type.
    • If no, or if you're not sure, then you probably want to engage some experts to help you decide.


  1. This decision tree does not consider performance or security. I'm not sure if or when a new custom content entity type would perform better and be more or less secure than a Node-entity-type.
  2. Even if this tree is a good answer, it will probably not remain one over time due to updates in Drupal core and contrib module releases. StackExchange doesn't seem to accommodate how the "best" answer today may not be the best answer tomorrow.)
  • 1
    interesting question, and impressive answer, chapeau! (oeps: hats off!). About the "security" part in your Note (1): would Group (= a variation of "og" for D8) qualify to be considered for that? Commented Apr 16, 2016 at 14:49
  • @Pierre.Vriens, merci beaucoup! The "security" part of Note (1) was prompted by a post somewhere (I don't recall where) that creating a lot of new Content Types rather than new entity types would increase the probability that you might accidentally expose a particular content type's data. Thank you for the reference to Group. It definitely facilitates the creation of new entities by providing a ready-made alternative to security functionality that may only be for node Content Types. So, it could preclude the need for entity type developers to create security functionality themselves.
    – Jon Freed
    Commented Apr 17, 2016 at 11:21

A simple approach about that issue is to take in consideration the project purpose, size and business requirements.

  1. How default node-entity content type affect building the project in an easy, neat way closer to the architecture and data flows produced from the analytic thinking of project docs.

An important notice here the decision of creating new entity type usually took by developers or technical leads not site builders or project owners that manage the application and only focus on business.

  1. Drupal 8 depends on some symfony2 packages and is more close to frameworks, development that traditional cms talking about Drupal with that big architectural changes, I envision building a new entity is better than doing many customization and complex configurations over node-entity content types in order to leverage Drupal among other frameworks as many people don't love the way Drupal configuration and distributed settings, You may face some people comes from WordPress and used to config every thing from one form which makes them annoyed when dealing with the Drupal admin dashboard.

  2. Drupal 9 plans to totally remove hook system and replace with event dispatcher that leads to a big need for an admin interface to create a new entity as altering existing functionality from code will be much harder to people who are not developers and will be very essential to add that feature.

At the end, I see new entities tailored for the project needs gives high performance better than complex content types with big numbers of fields as we now each field adds 2 tables to the DB and needs to load its config on each request, especially with the heavy business logic required.


Plain and simple: It's not all content. The list of the content could go quite long and be confusing if you're just using content types. (ContentEntityBase could also be implemented by a custom entity thoe)

If you have an author and published state you should go for a content type.

Otherwise (assuming your a programmer) custom entities should be preferred. A lot can be easily implemented with all the interfaces (like revision-able, field-able, access restriction etc.)

In my view this is just clearer and tail-ordered architecture (and also more performant).

Thinking of reusability in several projects the effort to make the custom entities blow out .. there are also nifty helpers like drupal-code-generator. To keep custom coding (or complexity) at a low level you should consider using content types if you want:

  • To translate the 'entity' (at least in D7), there would be also an interface.
  • (open for suggestions) ..

It is a tough question that honestly I think is only understood once you have implemented it before. But as remy metioned, not everything is raw, user facing content.

In Drupal 7, the capability of creating custom entities existed, but could be a daunting task if you were rough around the edges with OOP. It was kind of half implemented (or half done, however you want to say it), which lead to ways of creating entities that were not all exactly uniform and agreed upon approaches, with mixed procedural and mixed OOP.

In Drupal 8, the idea is much more realized, and it is a lot easier to get up and running with a custom entity. Node itself is based on ContentEntityBase, as are Blocks, Users, File, and Taxonomy.

Nodes are specifically for published, visible (or authorized) content data that typically act as content (that is, in a menu, or in the sitemap, or xml sitemap, or RSS feeds, etc). Drupal was designed in a way where you could hook in to any step of the process of node operations and alter it which can have unintended consequences if you have the wrong mix of contributed modules. This is probably a controversial opinion, but it helps to divorce yourself from the idea of "everything is a node" in order to embrace the Entity concept more.

Ideal content that make great content types:

  • Article
  • Page
  • Job posting
  • Event
  • Landing Page
  • Homepage

The common thread to them is that they share a concept of a type of content. It is usually in any number of workflow states (published, promoted, sticky, archived, featured, etc - if you use custom publish options), and a large number of contributed modules interact with it directly, like Pathauto.

But lets assume you want to store data in Drupal that is internal, private, drives other data, or data that should not allow integration outside of its scope unless you allow it. What kind of data could this be? Here are some possible types:

  • Product (Drupal Commerce)
  • Line Item (Drupal Commerce)
  • Search server (ApacheSolr / SearchAPI)
  • Contact (like CRM lead)
  • Ticket (like support ticket)

What makes these so different? Why would you want an entity for contact, instead of use the User model? You could make a few arguments there, but my example would be that if you are say, collecting email addresses and names and some other meta data from a contact form, store that data as an custom entity. You prevent the user list from being polluted with non-account items, you reduce potential security issues (what if a script or someone accidentally updated those accounts to be admins or sent a mass mail?), you make internal overhead management of the actual user accounts easier, and you segment what you are capturing out to what it is, a specialized bit of data.

From here, it is largely divorced from the more automatic parts of Drupal/Node system and you can tailor the actions and experience. You determine the routes, access, and CRUD workflow.

In that mindset, it makes it easier to view why the approach to that would be done that way. Take the support ticket example - it is incoming requests, but isn't published data, and likely has a very specific workflow that is easier to setup your way than to divorce it from parts of the node system you don't want it to adhere to.

Another example would be external, imported data. In most cases, this data usually is not enriched with local Drupal data (even if it is, as an entity, you can still do it). It could be anything. Maybe it's invoices, maybe they are books, maybe it is pulling brands of beer.

Data like this is usually specific and requires control beyond what node is meant for. That isn't to say that you can't augment it by using a reference field on a node to point to your custom entity (this is how Drupal Commerce worked, at some level) to enrich the data. At the same time, you are isolating and ensuring control over your data and UI from errant contrib code going beyond it's design and interfering with your model. This is likely less of a problem in D8 than it was in D7, though some hooks remain.

The proper architecture now exists to encourage separation. Not everything is a node.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.