Dynamic Document Types in Nuxeo

When one of my favorite clients at Maretha Solutions (and I won't name names-because all my clients are my favorite clients) asked me this again yesterday: "So Nuxeo still doesn't support dynamic document types?"

It reminded me how often these questions come up:

"Can I change the document type of an existing document in Nuxeo?"

"Can I dynamically create a new document type without restarting Nuxeo?"

Anyone who's run a production system that has evolved over time has likely asked these questions at some point. The short answer is still no-but keep reading to understand why not, and more importantly, what you can actually do.

Because while it's technically not possible to change the document type of an existing document in Nuxeo, you can certainly implement something that gives the user the impression that you've done exactly that.

Why isn't this possible?

The answer is simple: history.

Most Nuxeo implementations today run on MongoDB, which is technically schemaless and can store any JSON data. But Nuxeo was originally designed with SQL databases in mind.

A document type in Nuxeo is a combination of schemas. In a (very simplified) view, each schema maps to a separate table in SQL. So Nuxeo needs to know the full list of schemas ahead of time in order to initialize those structures on startup.

In the OSGi model used by Nuxeo, all document types and schemas are contributed via XML extensions and read at runtime startup. While hot reload exists, it's intended for development mode only.

If you want to add a new document type, you must contribute it through an extension point-and restart the server so that it's added to the internal registries. There are no public APIs to register document types on the fly; those registries are populated from the XML read at startup.

So what can I do if my users need dynamic document types?

Like I said earlier, you can absolutely build something that feels like dynamic document types to your users. We've done this in production.

You can allow users to define "types" at runtime by using a generic document type paired with dynamic metadata definitions. I wrote a detailed blog post explaining the technical solution here:

👉 Dynamic Document Types or Live Configuration of Schemas and Document Types in Nuxeo

What if I want to allow users to change the type of an existing document?

If that's a requirement in your business, the best approach is to design your content model properly from the start-use a base document type and attach different schemas using facets to emulate multiple "types."

But if it's too late and you're already in production, you can provide an operation that:

1. Creates a new document of the desired type.
2. Copies all metadata and content from the original document.
3. Deletes (or archives) the original.

This workaround is simple and effective. If you need something more complex-like copying the audit history or preserving versioning-you can reach out to us for help! (Also, don't hesitate to message me for the code for the operation above if you need it; it's pretty simple.)

Hope this helps clarify the mystery around dynamic document types in Nuxeo :)

← All insights