improving some ids
adding documentation
allowing media types to be referenced and refined