Implement a common language style throughout the specifications

[gregsdennis]

There are generally two approaches to specifying requirements:

• Permissive language, with which the specification explicitly states what an implementations is allowed to do.

  The implementation can only and MUST do these things.

• Restrictive language, with which the specification only states what an implementation MUST or MUST NOT do.

  The implementation can do what it wants within these bounds.

(I do see the irony in these labels, as the "restrictive language" approach actually results in a more permissive outcome for the implementation. For this conversation, I chose to focus on the language used rather than the outcome for the implementation.)

In editing the documents, I've found that both approaches are present in our specifications. Here's an example from Core 4.3.1 where both styles exist in the same paragraph:

A JSON Schema MAY contain properties which are not schema keywords. Unknown keywords SHOULD be treated as annotations, where the value of the keyword is the value of the annotation.

We're giving permission for implementations to support unknown keywords, and then requiring (softly) that unknown keyword values be collected as annotations.

We should decide on one or the other.

Personally, I prefer restrictive language as it gives implementations freedom to explore the edges of what's possible with JSON Schema while defining the bounds of what JSON Schema is; whereas permissive language requires that an implementation only ever be the prescribed thing because it can't do something if we don't give it permission. If we still want to explicitly state what an implementation MAY do, I think that should be either in an editor's note or in documentation.

I would rewrite the example above as simply the second sentence (disregarding that we're disallowing unknown keywords moving forward):

Unknown keywords SHOULD be treated as annotations, where the value of the keyword is the value of the annotation.

With this, unknown keywords are implicitly allowed. It doesn't make sense to collect unknown keywords as annotations if they're not allowed in the first place. The first sentence in the original adds nothing.

I'd like to take a pass before the initial stable release to go through all of the language and remove these "permissions" and just let the restrictions stand. This would move us into "the spec doesn't say I can't do this" territory, which I think is more open.

Also related to #922.