How Can I Create a Custom Element for Use in a DITA Topic?

[skioverlooked]

I’m currently working on a DITA-based documentation project and need to introduce a custom element to handle some specific content that doesn’t quite fit the standard DITA structure.

I know that DITA is designed to be modular and extensible, but I’m not entirely sure about the correct process for defining and implementing new elements in a way that remains compatible with existing tools and standards.

Specifically, I’d like to understand:

How to properly define a custom element for use within a DITA topic (using either a DTD or XML Schema).

Whether it’s better to specialize an existing element or create a completely new one.

How to ensure that my customization doesn’t break compatibility with standard DITA processing tools like the DITA Open Toolkit.

Where I can find official documentation, examples, or best practices for extending the DITA grammar (DTD or XSD).

If anyone has experience with DITA specialization, schema customization, or maintaining DITA compliance while extending functionality, I’d really appreciate your insights or pointers to relevant resources.

[Radu]

Hi,
Please see some answers below:

How to properly define a custom element for use within a DITA topic (using either a DTD or XML Schema).

There is a chapter on specialization in the DITA specification:
https://www.oxygenxml.com/dita/1.3/spec ... rview.html

Whether it’s better to specialize an existing element or create a completely new one.

You cannot create to my knowledge a totally new from the ground up element, you specialize an existing element which would be the base element like your element could have the base element <ph> if it's an inline element or <p> if it's a block element.

How to ensure that my customization doesn’t break compatibility with standard DITA processing tools like the DITA Open Toolkit.

As you specialize a base element, the publishing will apply by default on your element as if it's the base element instead. And you can add in time specific publishing processing for your element.

Where I can find official documentation, examples, or best practices for extending the DITA grammar (DTD or XSD).

These tutorials should help:
https://dita4practitioners.github.io/di ... tutorials/

If anyone has experience with DITA specialization, schema customization, or maintaining DITA compliance while extending functionality, I’d really appreciate your insights or pointers to relevant resources.

The Oxygen forum is a more static place, usually people register to post and receive answers on their own posts and we (the Oxygen team) answer them, if you want to ask the DITA community for something I would suggest you register and ask questions on the DITA Users List: https://dita-users.groups.io/g/main

Regards,
Radu