Concept Name Tags

This page is out of date – it refers to the way that Concept Name Tags were used in OpenMRS versions before 1.7.

Here is a short post mentioning how Concept Name Tags are used in modern OpenMRS versions:

ConceptNames are the words or phrases used to express the idea of a Concept within a particular locale. Because there may be many names for any concept, tags were introduced as a way of annotating names to indicate specialization, or the intended use.

Here is a focused subset of the data model showing the context of ConceptNameTags:

Concepts can have multiple names and descriptions. ConceptNames can have multiple tags.

While the ConceptNameTag facility is general purpose, the core framework uses tags to indicate the preferred name to use for a particular locale.

Preferred Concept Name Tags

Originally, concepts had only one official name, a short name, and possible synonyms. With the model shown above, all possible text representations for a concept are considered names. Tags are used to differentiate between the set of names for a concept.

ConceptNames can be have one or both of two preferred tag variants:

Tag Pattern

Variable Substitution



xx = ISO-639 two letter language code

Indicates that the name is preferred for all locales which share the language


YY = ISO-3166 two letter country code

Indicates the preferred name to use within a country.

Preferred Language Rules:

  1. "preferred language" tag can only be applied to any compatible locale (same language, regardless of country)
  2. only one "preferred language" tag is allowed per language

Preferred Country Rules:

  1. "preferred country" tag can be applied to generic or country specific locale
  2. multiple "preferred country" tags are possible, however
  3. only one "preferred_ country" tag per language/country combination is allowed

This scheme provides considerable flexibility because preferences do not have to exactly match up with the specified locale, as long as the language is compatible. For instance, consider the following names:

Concept Name





preferred_US, preferred_GB



spotty skin





preferred, preferred_FR





The preferred name is the recommended name to use within a particular locale. The locale can be specified as just the language, or for a country. When requesting the preferred name for a Concept, the collection of available names is searched for a ConceptName from a compatible locale which has a preferred tag. If the requested locale only specifies language, then the name may be from any country with a compatible language which is tagged as "preferred language". If the country is specified, then all compatible names are searched for a name with the "preferred country" tag.

It is possible that no name is tagged appropriately for the requested locale, so the result may be null.


The "best" name also uses the preferred tags to rank the available names according the following rules, ordered from "best" to "less good":

  1. preferred name in matching country (for example, tagged as PREFERRED_UG for preferred in Uganda)
  2. preferred name in matching language (for example, tagged as PREFERRED_EN for preferred name in English)
  3. any name in matching country (for example, matching Uganda)
  4. any name in matching language (for example, matching English)