The power of Tags and Comments

2020 09 01 head

A software architect models customer domains and maps them to excellent software constructs. The solution shall support future customer groups and expand to store additional information.

Tags, also called labels, provide an informal ontology to classify customer data.

Tags are extensible and are machine-readable.

Comments empower users to store relevant unstructured information.

Comments are only for human beings.

What are good approaches to provide searchable tags and labels and avoid wild growth of useless records?

Can you as a designer govern the ontology defined through labels?


Tags add semantic information to business entities. Tags are often defined as a crowd ontology without enforced schemas.

Invest in domain modeling to define and maintain tags, and you will move tags to full-fledged ontology into your domain models. This ontology supports meaningful search, segmentation and reporting over historical and geographical raw data.

Tags with associated values are also used to decorate unrelated entities with orthogonal information. For example, you can associate geographical coordinates – GIS – to pictures, meetings, or addresses.

A tag has three parts:

  • An optional namespace to classify the tag in the overall ontology.

  • A mandatory name to uniquely identify the tag in the context of its optional namespace.

  • An optional value providing details to the tag.

For example, we could define a tag such as geo:longitude=50.167958 to provide the meta-information of longitude to an entity. This tag has a namespace geo, a name longitude and a double value 50.167958.

Additional information is available under link:../../../docs/core/models/ Below the source code in modern Java is

public record Tag(String namespace, @NotNull String name, String value) {}

You should strongly consider the introduction of tag types to constrain the possible values of a specific tag. For example, you can define that the namespace geo contains only the longitude and latitude tags. Both these tags have mandatory values of type double. Once your design supports tag types, you can add generic validation rules in the user interface and in business logic for all existing tags.

The ontology enforcement allows consistent reporting and data drilling over departments in your company and over time.


Comments provide human-readable information and hints for entities.

An author writes a comment at a specific time. Comments shall usually be immutable. To respect human fallibility, a correction mode can be supported. If changed, the new comment replaces the older one and is marked as edited. The edition feature is part of the workflow and not part of the domain model.

An author can be another computer system. It can provide information about its actions through comments. If the deletion of comments is disabled, the comment history is an audit trail documenting what happened over time with an entity instance.

Beware that the authors define an external identifier space. If your application requires a user account, you can connect the author with the user account. The consequence is that you should only disable these accounts and never delete them.

Policy should be defined to handle the fact that collaborators quit the company over time and are no more active users; but they are still referenced as authors.

The code in Java is

public class Comment implements HasOid, HasTags {
    private long oid;
    private LocalDateTime created;
    private String author;
    private String text;
    private Set<Tag> tags;

    // getters and setters


Our architecture follows the principles of domain-driven design. Comments are always associated with a specific bounded domain of the overall application. For example, we often model the persistence view of a domain through a database schema. Each bounded domain has an own independent scheme and could have a persistence store for comments.

Tags are classification information associated with an instance and should be stored within the entity. The set of tags is often transformed to a textual representation and stored in a column. The search features of the underlying database can be applied for selecting instances of interest.

Tag types are a medium to define an ontology and create valid tag instances. A set of tag types shall always be associated with a specific domain of the application.

We provide a Java library CRM implementing these constructs. More information is available under tangly open source components.

Related concepts are discussed in our blog series