add some deeper explanations to docs
minor improvement to validation logic for optional objects
add and improve tests
bump version