schema.describe minor issues and feature suggestions

[yonjah]

I'm working on a fuzzer that would accept joi schema and would return a valid example with random data.
based on the discussion here (#946) I was using describe to
understand the schema and try to create a valid example.

I found a few places where the description is not clear enough to understand the actual schema.
Not sure if this is something joi would care to change but it can be useful

• Joi.lazy() - does not describe in any way the schema to be lazy load.
  I think the minimum will be to return the function that can be called to retrieve the schema
  but a better solution might be to actually get the schema from the function and include it's description.
• References are hard to decode and can be impossible to distinguish from valid strings
  For example in the following schema -

const testSchema = Joi.object().keys({
    a: Joi.alternatives().when('b', { is: Joi.ref('c'), then: 'x' }).try('y'),
    b: Joi.any(),
    c: Joi.number(),
    d: Joi.alternatives().when('b', { is: Joi.any().valid('ref:c'), then: 'x' }).try('y'),
});

console.log(require('util').inspect(testSchema.describe(), {depth: 6, colors: true}));

from the description it looks like o.a and o.d has the same definition, but o.a has to be 'x' when o.b === o.c and o.d has to be 'x' when o.b is the literal string ref:c.
I know chances that there are small chances for the schema ever use literal string start with 'ref:' are small but it still would be great to have an option to differentiate between those values and in general maybe a nicer description for references (including context references) might be more useful
like an actual object {ref: key} and {context: key}

Another feature that can be useful (but might be a bit specific to my use case) is to include the schema as part of the description.
This can be useful test if the generated value actually meet the required description (especially in the case of alternatives and references where you want to check if a value meet a certain condition)
alternative option will be to have a reverse method that will regenerate a schema out of a description, but it will probably be much harder to implement

[WesTyler]

At the risk of derailing the discussion, did you by chance check out Felicity for generating randomized data based on a Joi schema? If so, would you mind letting me know if there was anything about it that didn't meet your needs or expectations? Always looking to improve it, and always thrilled to have PRs and feedback :)

[yonjah]

@WesTyler I checked out felicity before starting this project even opened an issues xogroup/felicity#143
I think the main issues I had with felicity is that it didn't work with joi 13.x without adding custom hacks and error catching to the code.
I also didn't understood the design decision of using both describe and generating a schema to get an example (which I think was the main cause for it to be locked to specific version of joi).

Also I assume felicity was made with the idea to generate user readble examples for api routes.
But fuzzing actually requires generating obscure and not so common data to try to trigger edge cases that might pass validation but still break your api.

It could be great if the features and fixes could be integrated into felicity since I assume maintaining this kind of code is going to be painful.

[WesTyler]

Oh, ha! Sorry! That's what I get for trying to catch up on things at night after a vacation. I recognized your name but couldn't place it.

I'll move the ongoing discussion back over to the Felicity issue (which I've been meaning to get back to you on).

Sorry for derailing the describe() discussion here.

[Marsup]

Are you going to be able to sort it out in felicity or is this issue still needed ?

[yonjah]

@Marsup this issue isn't really about felicity. It is about issues with Joi describe output.

[Marsup]

• About lazy, I cannot provide the schema inside the function as the main goal of it is to allow circular dependencies, but I could provide the function and let you deal with that.
• About references I agree, but as you said collision are supposedly rare. It's going to be a breaking change if we provide the reference itself, or some form of it. I could start accepting it on a v15 branch maybe.
• Last suggestion could make sense if behind a Symbol I guess.

[yonjah]

* About `lazy`, I cannot provide the schema inside the function as the main goal of it is to allow circular dependencies, but I could provide the function and let you deal with that.

Providing the function is good enough

* About references I agree, but as you said collision are supposedly rare. It's going to be a breaking change if we provide the reference itself, or some form of it. I could start accepting it on a v15 branch maybe.

What ever you think. It doesn't affect my code that much but I thought it might be worth pointing it out.

* Last suggestion could make sense if behind a Symbol I guess.

That would be great.

[hueniverse]

Breaking changes:

• Lazy now includes the schema function
• All refs are objects in the format { type, key, path }
• The schema is attached using symbol Joi.schema on the description

[hueniverse]

I am reverting the last change (schema behind a symbol). It is no longer needed with the new extract() feature.