I have a custom multimedia schema in my DXA 2.0 Java implementation called HighResolutionImage, next to the Image schema which comes out of the box (as part of the DXA Core Module).

I created a class like this:

    entityName = "HighResolutionImage",
    vocabulary = SDL_CORE,
    prefix = "s")
public class HighResolutionImage extends Image {
    private String copyright;

Note that the entityName has to be equal to the title of the multimedia schema minus spaces - multimedia schemas don't have root element names, so the title is used to map the content to properties in your class.

By the way, I first tried to extend MediaItem instead of Image, but I needed to copy a lot of boiler plate code (toHtmlElement etc), so I thought this would be the easier solution. Anyway, it didn't solve the problem either.

I added the following line to my module initializer:

@RegisteredViewModel(modelClass = HighResolutionImage.class)

Unfortunately, I got the following exception:

com.sdl.webapp.common.api.mapping.semantic.SemanticMappingException: Ambiguous semantic mapping for http://www.sdl.com/web/schemas/core:HighResolutionImage, found these mappings: [class com.xxx.dxa.modules.xxx.model.HighResolutionImage, class com.xxx.dxa.modules.xxx.model.HighResolutionImage]

For some reason, the semantic mapping for my entity was added twice.

When I removed the @RegisteredViewModel line, the entity wasn't found at all (I placed a breakpoint in the ViewModelRegistryImpl to make sure of this).

After some experimenting, I found that DXA adds the model to the registry twice, once because of the RegisteredViewModel annotation, and once because of the entityName property in the SemanticEntity annotation on the model itself. I couldn't change the latter, because I needed to pick up some metadata fields from the schema, so I ended up renaming my class from HighResolutionImage to HighResolutionImageModel. This works!

My conclusion is: if you want to introduce your own multimedia schemas, you cannot give the entity model class the same name as your schema. That sounds like a bug to me.

My question (sorry for the long detour), is: can anyone confirm my suspicion?

  • Thanks for sharing your analysis! Very useful. I have seen similar spurious errors being reported and this sounds like a plausible explanation. Obviously, this is defective and should be reported as an issue on GitHub Commented Oct 19, 2018 at 6:27

1 Answer 1


Your analysis sounds plausible (see my comment).

This indeed sounds defective, but note that if your View Model Type already has the same name as your semantic type/entity, you don’t need a SemanticEntity annotation at all. Same goes for the SemanticProperty annotation.

So, this should work too:

public class HighResolutionImage extends Image {
  public String copyright;

See class Paragraph in the Core Module as an example of a View Model Type without any SemanticEntity/Property annotations.


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.