added an example of an optional value

[w01fe]

Thanks for the PR. Can you please provide some context for why you think this belongs in the first example? maybe is already explained later in the readme (along with many of the other commonly used schema features).

[yogthos]

A friend of mine started using compojue-api, he's new to Clojure. He ran into a situation where he was selecting data from the database and some keys were nil. He was not able to immediately figure out what to do.

Not a single example in the readme illustrates this directly, not even in the optional section itself. I think it would be helpful to have the first example cover all the basics.

[w01fe]

There are other important concepts, like optional-key, that aren't covered in the first example either -- it's already pretty packed with new things for a newcomer, it seemed to me.

What do you feel is missing with the maybe example later in the readme?

[dmuylwyk]

I'm the friend mentioned by yogthos.

I interpreted the present wording to mean maybe operates at the schema level; not on values directly. It wasn't until we found other examples elsewhere that the necessary functionality became clear.

It's a common case so it's worth explicitly illustrating the use and implementation.

[yogthos]

The optional-key has several examples further down however. I personally don't find the first example that crowded, but perhaps it might make sense to have a section with common patterns close to the top, then explain these in detail later in the readme.

[w01fe]

Hi, thanks for your input! I'm not sure I understand, could you elaborate on what you mean? If there's a high-level concept that's not clear, I would like to make sure we address that issue as well.

Since you seem to feel strongly about it, I'm fine with updating the lead example. But can you please:

• Fix the last part of the example (where the error is thrown), which is now inconsistent with the definition
• avoid re-using the :d key -- maybe call it possibly-nil or rename the other keys to avoid key re-use -- I think this makes the example easier to read.

Thanks again for your help!

[dmuylwyk]

Meant to add: it was the values that were nil. optional-key did not meet my needs.

In fact, optional-key led me to search for something like optional-value, which seems intuitive, and this likely caused me to overlook maybe. Yogthos's recommendation is minor but it would have saved me a headache.

[yogthos]

Any chance of this getting merged in? :)

[w01fe]

Thanks for following up. Happy to merge once the two issues in my last comment are addressed.

Cheers!

[yogthos]

👍

[frenchy64]

It seems the problem here is that new users cannot associate the word "maybe" with "nilable" from the readme. I don't think this change fixes that, I pushed this instead: https://github.com/plumatic/schema/commit/b6f8c770362ab3b47b21d11d18734df2dece45a5