Right now we have haphazard comments regarding which fields are read-only/output-only, and many, such as uid aren't documented at all.

Swagger 2.0 actually supports a readOnly property tag, but we're using Swagger 1.2, which does not, officially. The official meaning doesn't match what we want, though. readOnly fields must not be included in a PUT, which would be painful for clients. We could simply document our convention, however.

We should tag fields as readonly. Maybe we could have go-restful automatically add a comment to the description in that case.