document how definitions are flattened