Finally there is a new kid to the block rethinking content management from the ground up: headless content management systems. In a nutshell a headless CMS separates content from its presentation, primarily enabling content to be re-used across different forms of presentation, e.g. on a website, a mobile app, or a public info screen). As an engineer, this is a dream come true: finally it is possible to implement a consistent look and feel across any presentation as content editors cannot misuse WYSIWYG editors producing HTML garbage.

At mimacom we have rebuilt our website from the ground up leveraging a headless CMS. This blog post resembles the criteria we used to decide for a headless CMS vendor and distills the nitty-gritty details we will have a closer look at next time.

If you are in the process of deciding whether a headless CMS is right for you make sure to read this great article by kentiocloud helping you to make that strategic decision. This blog post focuses more on the technical decision-making process to evaluate whether a given headless CMS vendor really meets the requirements you have (or might need to have after you read this post :-) ).

Head over to headlesscms.org for a list of headless content management systems. If you are unfamiliar with headless CMSes read the about page there for a short introduction, as this post will dive right in.

1. Content Model

Headless CMSes allow developers to define a content model: a content model defines the structure, fields and references between specific content elements. For example, a news model may contain a title, publishing date and body copy. The content model then resembles your content data structure similar to how you would define a relational database schema. Naturally, the power of a headless CMS lies within the capabilities of the content model. Evaluate the possibilities you have with a headless CMS candidate on the following features:

• Content types: The content type represents a piece of content. While this feature is named differently in nearly any CMS, the level of abstraction is typically the same. A content type for example is: a news post, a blog post, a case study, a webinar, etc, so a piece of content that is logically coherent.
• Fields: A content type is a collection of fields that contain the actual content. When modeling content, fields are used to model the content by specifying types: this gives an author a name of type text, an email of type email, and a profile photo of type image. The CMS should offer a wide variety of built-in field types that support editors to enter correct and valid content.
• Validations: Validations are used to guide editors to enter content as expected. While field types (such as text) are very generic, validations can (and should) be used to refine the content model. For example, the CMS could force authors to write a description between 150 and 250 characters length. A CMS should support different kinds of validations for different field types and should be able to display customized help messages.
• References: A content model is typically referenced. A news post has an author, and a job offer may be associated to multiple office locations, all of which are modeled as separate content types. In general, when a headless CMS allows to define references, it should also be able to constrain references based on certain criteria (think of min/max counts, etc.). It might also get interesting if your content has cyclic references.

The content model is the heart of all the work you will be doing with the CMS. If you are not able to model the specific concepts you want to manage with the CMSes feature set, the CMS might be too limiting for your use case.

2. Content Editing

Depending on the size of your project, it is also most likely you as a developer to offer support to content editors. In order to proactively keep your sanity you will want to choose a CMS with a great UX enabling non-tech-savvy users to edit content.

However, it is not only the tool itself that needs to have a great UX, it also depends on the options you have as a developer to customize form controls. A good CMS decouples the form presentation from the data type allowing you to precisely choose an editor that you feel is the right choice. Basic editors include single/multiline text inputs, radio and checkbox selects, dropdowns and date inputs. Advanced editors include tag inputs, location selectors or even JSON input with syntax highlighting.

Take special care to evaluate the editor possibilities that enable content editors to write large pieces of content with formatting. Usually, markdown is used behind the scenes to store the formatting, but that can also be a very limiting choice if you need good support for tables, for example. Also note that markdown has a lot of flavors where some features might not be present on your system of choice. It might also be helpful if the CMS supports other types of multiline text input, such as plain text, AsciiDoc or even the good old WYSIWYG HTML editor (as a last resort, of course ;-) ). Even if some formatting language such as Markdown or AsciiDoc is used behind the scenes, it is very helpful for editors if they still have some WYSIWYG guidance on the formatting. In particular, adding headlines, links and images should be fairly intuitive!

3. How to Have Fun in Any Project: i̟͖1̘̣̰͜8̰n̢̙͔

Most websites today are offered in multiple languages. While modern CMSes typically have built-in support for content translations, the actual implementations differ a lot. While rebuilding the mimacom website we faced quite some challenges concerning translations. The following list gives you a head start when thinking about internationalization for your project:

• Is all content translated? Really? Typically, when offering translated content all content is being translated. However, sometimes it is necessary to publish content only in a single language. And that doesn’t need to be the primary language. For example, if news postings are managed through the platform, some news may only be relevant for a local target audience and thus need not be translated to all the other languages. Make sure your CMS supports publishing content only in certain languages, as not every CMS supports this use case.
• Can assets be translated? Assets such as images and videos may in fact contain content that needs to be translated. A CMS should be able to handle translations of assets, as well as help content editors to reference the correct translation when using the asset.
• Content model translation? The headless CMS should be capable of selectively translating parts of the content. For example, when modeling people you don’t want to translate their names, but their biography. Moreover, the CMS should be able to properly handle translations of references between content models (i.e. one-to-many or many-to-many relations between content elements).

4. Workflow and Approval Process

When more than two people will now or in the future edit content with the CMS there should be some way to define a workflow process. A highly useful feature in such a workflow is a review step before publishing changes to a piece of content. As a developer using Git-based tools this seems like a modest requirement, but in fact not a lot of CMSes are capable of really displaying a diff between two versions of a piece of content with a comment-like UI.

If you have a decently large editors team figure out if it is possible to customize the workflow from draft to published. Maybe you require the legal departments approval before you publish? Although a very advanced requirement, it might largely improve the editor experience and reduce the likelihood of wrong contents being published.

Limiting editors to manage certain types of content is also very useful. Imagine a company website where you have a section with company news and another with job offers. Chances are high that not the same person will edit content in both sections, so constrain editing rights to certain parts of the content helps reduce accidental mistakes.

While the workflow of editors may seem a lesser concern for developers, a CMS supporting advanced workflows eases the implementation and lets developers focus on the important things of the project. Also, if the workflow has a good API support it is even possible to tailor things further and integrate the CMS into an existing application landscape.

5. Content Versioning

Content is a function over time. Editors create content, change it after a while and may eventually delete the content altogether. While a CMS primarily serves (and should serve) the latest version of the content a version history can sometimes be very useful.

For example, versioned content may be rolled back in case something went wrong during editing. One of the most useful features of versioned content is the ability to show the changes between two versions of the content. This plays in nicely with review and workflow processes. Also, when content is versioned it is possible to show an audit log of whom changed which content when, which might come in handy for regulatory reasons.

Content versioning may be nice, but special care needs to be taken when relying on the feature. CMSes can’t solve all the problems, especially when dealing with a lot of references between content. I haven’t come across a headless CMS that supports versioning and always results in consistent models (as semantically reverting to an older version of a piece of content should also roll back any transitively referenced pieces of content).

6. Content Structure as Code

The CMS should enable the content structure to be stored as code. Storing the structure as code makes the content model live alongside the code that uses the structure. If the content structure is not managed through code it becomes increasingly difficult to reason about and change the current content structure.

As a minimum requirement to support content structure as code the CMS should at least have a well-defined API that can be used to alter the content structure. Alternatively, a client-side programming SDK could also do the trick.

If possible, it is a good idea to store the content structure as JSON, as good tooling support for JSON files exists. For example, you could use JSON schema to validate the content structure files for syntactical (and also some semantic) correctness. Taking that approach further, you could use the JSON schema to mock data and build continuous integration pipelines.

Having defined the structure once, also allows to setup multiple, staged instances of the CMS to have a development, a staging and a production version running different versions of content and code. Contentful wrote a nice article explaining the CMS as code approach.

7. Migration Support

As a CMS with structured data is very similar to a relational database the whole concept of migrations also applies here. Changes to the content structure will likely result in data migrations in form of transformations to be required. To reduce manual efforts, it is really nice if the CMS offers a standardized way to deal with migrations.

If the CMS offers no explicit options to migrate content, a basic starting point is a support for a lifecycle of content fields. Using lifecycle properties parts of the content model can be made invisible to editors or be hidden from API responses even though the content might still be there. That should leave enough room to implement proper content migrations.

8. Asset Management

Any modern content project also has media attached. Media obviously includes regular images such as JPG, PNG or GIF, but support for vector graphics such as SVG should also be there. Moreover, the CMS should also support videos - either self-hosted or included from a platform such as YouTube or Vimeo. Next to that, the CMS should also support hosting classical files, such as ZIP or PDF to be able to manage certain attachments.

When dealing with assets the CMS should be capable of the following:

• Resize and optimize images on the fly. There should be an API to resize and compress (with configurable quality) any image asset managed by the CMS.
• Update an existing asset. The CMS should best know where assets are used and should provide a means to update an existing asset to a newer version.
• Show where assets are used throughout the content. Also identifying orphaned assets is a plus.
• Be able to organize assets with some sort of structure, such as folders or tags. The hierarchical organization should allow to constrain choosing assets from within content (e.g. portrait photos of team members should be stored in a certain directory, allowing editors to choose only portrait photos from a team member content entry).

9. API Stability

Well, this should be a no-brainer for developers, but I’d still like to keep this on the list. Changing APIs is okay when alpha-testing a product, inconvenient during beta mode, and simply annoying when assuming the product is stable. Of course, as developers we don’t want to limit product innovation through insisting on old APIs, but proactively managing breaking changes and updates to an API well is worth very much!

Ideally, the API should be versioned with a certain guarantee that code you write today against the API will still work in a year forward. If there is a new API version out, then there should at least be good documentation on how to migrate to the new version. A CMS committed to providing a great developer experience will know how to deal with this, so keep an eye on this topic. You may simply read the last few release notes of the project to see how these issues are dealt with. Oh wait, …they don’t even have a release log?!

10. Support and Bug Fixing Policy

Maybe you are on a budget, or building a side project and this is not an issue as much as it could be. But maybe you are building a project where full-time editors are curating content each and every day. Make sure that the available support options fit to your budget and project requirements.

If the project is open-source look at the size and activity of the community. Maybe you may even become a contributor to the CMS platform? It’s also great to have access to the code in order to be able to fix bugs by yourself if things get tight.

11. Ecosystem

A content management system can be seen as a platform where naturally an ecosystem evolves over time. Depending on the goals of the CMS, the organization driving the future of the CMS and the technical architecture itself influence the degree to which an ecosystem is being or even can be built around the CMS. Having a solid ecosystem will likely solve some of the problems you encounter on the way, including:

• tooling to orchestrate the CMS itself
• extensions to enrich the CMSes functionality
• integrations to connect to other products and platforms

When evaluating a headless CMS the ecosystem can play an important part, as by its nature a headless CMS is less opinionated about tooling, but typically provides easier ways to extend the CMS or even integrate other products. For example, there could be UI extensions for content editors or even integrations to an external media management system.

12. URL support

While being agnostic about where content is published, a headless CMS should still be capable of dealing with URLs for the content it manages (as long as you intend to publish on the web, too, of course). The CMS should be able explicitly declare a slug for a piece of content and ideally also take care of its lifecycle. For example, if a slug is changed there should be a way to automatically determine previous versions of the slug to implement redirects in case they are required.

Also, URLs play an important role in search engine optimization and should be carefully considered by content editors when publishing to the web. Ideally, the CMS proposes URLs or slugs based on the title an editor enters for a piece of content.

Conclusion

Choosing the perfect CMS is impossible. However, explicitly considering the pro’s and con’s of a CMS solution based on the requirements for the project reduces the risk of surprises in the long run. Also, a CMS that offers a bunch of features more than you need today may be important if you intend to grow the project.

If you go through the above list and identify the requirements that are most important to your project make sure to try the CMS and see if they really work as expected. The market for headless CMSes still is new and marketing websites often promise more than there really is to it.