jhthorsen / jhthorsen/json-validator

Documentation is wrong/misleading

Open
#271 0 comments 0 reactions 1 assignee Claimed by @tyrrminal View on GitHub
documentation help wanted
Dominant language
Perl
Stars
60
Forks
64
PR merge metrics
No merged PRs in 30d

Description

* JSON::Validator version: 5.14
* Perl version: 5.38
* Operating system: Debian 12.1

### 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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.