I just created https://java.net/jira/browse/JAX_RS_SPEC-549 "Clarify documentation ambiguities", in the hope that the Expert Group can help us solve a couple of issues. -- My company's smarter than your company (unless you work for Red Hat)