adding descriptions to schemas for docs, and changing scenarios to demonstrate more required fields
Merge branch 'fix-docs-forms2' into revision1