jhthorsen / json-validator

:cop: Validate data against a JSON schema
https://metacpan.org/release/JSON-Validator
56 stars 57 forks source link

Documentation is wrong/misleading #271

Open tyrrminal opened 11 months ago

tyrrminal commented 11 months ago

Steps to reproduce the behavior

In an attempt to diagnose an issue I was seeing in my app (which turned out to be the fourth item below), I stumbled across what seem to be some errors in the documentation.

  1. JSON::Validator::Joi POD->SYNOPSIS: the schema declaration for the email field does not include ->string causing it to default to object, so testing the sample code does not work as expected.
  2. JSON::Validator::Joi POD->SYNOPSIS: the data value for the email field should be 'jhthorsen@cpan.org' not "jhthorsen@cpan.org"
  3. JSON::Validator POD->SYNOPSIS: In the "Using Joi" section, if the code under "joi() can also validate directly" is run as written, it results in the @errors array containing a JSON::Validator::Joi object rather than any JSON::Validator::Error objects. As there is no corroborating documentation for the joi() function, I'm unsure whether this is a bug in the code, or just incorrect documentation.
  4. JSON::Validator POD->SYNPOSIS: in the "Using Joi" section under "Use joi() to build the schema", the code will partially function, but without adding ->compile, some errors (like those related to the required and strict attributes) won't be output

Expected behavior

  1. No validation errors (unless the point of this section is to demonstrate such a validation error, in which case that should be specifically called out)
  2. No errors
  3. The @errors array should contain /age: -42 < minimum(0) (JSON::Validator::Error)
  4. The expectation is that everything stated in the code would be validated, if ->validate were to be called (though as the documentation is written, it is not)

Actual behavior

  1. /email: Expected object - got string. (JSON::Validator::Error)
  2. Global symbol "@cpan" requires explicit package name (did you forget to declare "my @cpan"?)
  3. The @errors array contains only a JSON::Validator::Joi object
  4. Provided that the code was extrapolated into a complete "thought," the required attribute would be ignored, resulting in validation errors not being produced when they should be.