Well the same apply IMHO to merge operation that is in org.jboss.jca.common.metadata.Metadata too. If we still need it (I'm not sure at the moment, but probably it will be) we can add an interface MergeableMetadata to be implemented by metadata for which make sense.
Am I wrong?
The Metadata class is there to have a single point of access to all metadata - both ra.xml and jboss-ra.xml. And a merge of thoese.
It also contains a simple method to validate the structure from a resource adapter level.
Feel free to move this functionality around, but document the structures in doc/developerguide/en/modules/metadata.xml