refactor and document field definitions