> I think the named query example is not perfect as we might be able to re-use the JPA annotation here.

"Perfection doesn't exist." :)

I'm not sure it is so important since this is just an example of a possible option. Named query should be a known concept that's why I think it might be good for an example.

But I'm open to suggestion