some documentation and move $requiredKeys to the top, in case they ever change