Thanks for the detailed reply! I turned this into an issue on our GitHub repo here: https://github.com/18F/api-standards/issues/45.