Cerberus 2: Proposal to clearly distinguish names for different 'schema' rules

[funkyfuture]

There are currently five rules to define constraints on container objects that are either sequences or mappings:

• items defines a sequence of individual sets of rules for each item in a sequence
• keyschema defines one set of rules that all keys of a mapping must match
• schema
  • either defines a schema for a subdocument (a mapping) with the same (slightly enhanced, actually) semantics as a 'top level' schema
  • or it defines one set of rules that all items in a sequence must match
• valueschema defines one set of rules that all values of a mapping must match

Proposal 1

the different meanings of schema have been a source of confusion among users and it also forces us to operate with some assumptions in the code and to add some necessary overhead around this.

therefore the next major relase should clarify semantics on the schema rule. it's quiet obvious that its name points to the first mentioned mapping-related semantic as it matches the overall usage of the term schema in Cerberus' nomenclature.

the name of the other rule should be chosen wisely to imply both the similarity with and the difference to the items rule.

i can think of the following atm:

• allitems (see rationale in P2)
• eachitem (see rationale in P2)
• itemsrules

Proposal 2

as the comprehension above shows, there are two categories of rules in this realm: those that define a set of rules for particular items or just any item of a container object and those that define a schema that assigns such set of rules to values identified by a key. it'd be therefore terminologically stringent to rename keyschema and valueschema to keysrules and valuesrules. as there are no name conflicts, the previous names can still be used as aliases.

with these terms, itemsrules would be a consistent choice for the previous proposal as the morpheme items implies that it concerns all of the sequence members and the morpheme rules implies that a set of rules is expected.

[funkyfuture]

note: from an implementation perspective itemrules and keyrules might actually be aliases in the end as both validate the values that an iteration over a container object yields against the given set of rules.

[funkyfuture]

i'd say we include proposal 2 in the 1.3 release with the same rationale as here.

[nicolaiarocci]

Addressed with #422

[funkyfuture]

implemented in dca2549