Editorial: Fix schema documentation for flag

[snuggs]

This was annoying to no end and had to make 2 dozen changes before figured out it was flag not flags.

• - Change documentation flags -> flag
• - Provide example for flag

Addresses:
- #626

References:
- #623
- a140245

[Elchi3]

I'm very sorry about this nasty typo in our docs!

Note that we now found out that there are multiple flags sometimes, so we're now considering to make this actually flags for real and of type array. See this issue #546

Until that is resolved, this PR looks correct to me, though. So lets merge it.