Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

funkyfuture opened this issue Apr 21, 2018 · 4 comments


Copy link

@funkyfuture funkyfuture commented Apr 21, 2018

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 added a commit to funkyfuture/cerberus that referenced this issue Apr 21, 2018
Copy link
Member Author

@funkyfuture funkyfuture commented Jun 16, 2018

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.

Copy link
Member Author

@funkyfuture funkyfuture commented Jul 6, 2018

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

Copy link

@nicolaiarocci nicolaiarocci commented Jul 9, 2018

Addressed with #422

@nicolaiarocci nicolaiarocci reopened this Jul 9, 2018
@funkyfuture funkyfuture added this to the 2.0 milestone May 6, 2019
Copy link
Member Author

@funkyfuture funkyfuture commented Nov 8, 2019

implemented in dca2549

@funkyfuture funkyfuture closed this Nov 8, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants