change interface to match other code's expectations
serialization/dumping methods; document assumptions