add rough docs for unevaluatedItems

[micshar92]

One thing that guided me was my concurrence with @jdesrosiers on #198:

I feel like UJS shouldn't be a cookbook of useful patterns and I feel like that's mostly what this is contributing. Since we don't have a cookbook, I'd be ok with merging this, but I do worry that it could be a slippery slope that results in ever increasing bloat

I included five examples: the ones I deemed to be the most common use cases. These were based on my conversations with others, a lot of Slack messages, and the unevaluateditems.json in the test suite repo. I linked to that document at the bottom of the page in a note box and gave a short list of other cases readers might need. Five examples was already adding bloat to the page, and I don't think I can part with any of them. What do you think?

Feel free to remove, edit, or add things. I validated and checked multiple times, but I could have made some grievous factual error. This is just a rough draft, and I'm still lacking in "professional experience." I hope the links and other style bits turn out right.

Oh, and you don't mind if I add a link on my portfolio site to prove I wrote this, do you?

[micshar92]

@Julian @jdesrosiers Hello again. If you don't mind, please review my changes to the array.rst page. The new website (looking spiffy btw) is probably a priority at this moment, but I landed an interview for a good job recently and I feel my open-source experience maybe helped contribute to that. (of course it's just an interview) So I want to follow up here, even if the UJS website is soon to be overhauled. Thanks!

[Julian]

Sorry I missed this somehow. Will have a look!

[Julian]

Oh, and you don't mind if I add a link on my portfolio site to prove I wrote this, do you?

And definitely feel free to do that!

[Julian]

Left you some notes, lemme know what you think!

[jdesrosiers]

I'm looking forward to reviewing this when I'm back from vacation. Sorry for the delay.

[micshar92]

@Julian I don't know if people are automatically alerted when I submit a PR so I'm writing this comment.

Here's draft 2 of 3. Anything else to edit before the final? (@jdesrosiers I'll wait for you, no big deal)

I noticed, for instance, this section breaks style with the rest of the page because it has no red x or green check boxes. But I don't think that'll matter much.

[Julian]

Cool! I'll have another read.

I don't know if people are automatically alerted when I submit a PR so I'm writing this comment.

In general folks who are subscribed to the thread might get emails when you reply to individual comments and/or push commits, though definitely leaving a comment is still helpful/common, as people often are waiting for whenever you're done addressing a round of comments before doing another review (I certainly was) so yeah definitely will take another look now thanks again!

[micshar92]

@Julian @jdesrosiers Third and next-to-final draft up. See any improvements, let me know.

[Julian]

Nice! Took another skim, think this looks more or less good to me! Let's see what Jason thinks when he's back, I think next week.

Thanks again for the PR!

[jdesrosiers]

Thanks again for taking on this task. It's not an easy one.

For this first round of review, I'm just including syntax and code style issues. Make sure to build the site and preview locally to make sure everything is rendering as expected. See the README for instructions and let me know if you have any problems. I fixed an issue with the build this morning, so you'll want to rebase your branch before attempting the build.

[micshar92]

Fourth draft up.

See the README for instructions and let me know if you have any problems.

Well...
I just learned what Docker was yesterday, so my knowledge of it is lacking. Nonetheless, I got this error when trying to build in the VS Code terminal: (see attached image) So I can't build the site. Good to at least get experience with Docker, since I imagine it's a necessary technical writer skill. But do you know what this error means? To my knowledge, I followed the directions exactly.

[jdesrosiers]

@micshar92 It looks like the build doesn't work in windows. Everything is harder in windows. I'm working on it. I have a hack that I think should get it working for you until I figure out what the real problem is.

In Dockerfile change, ENTRYPOINT ["./entrypoint.sh"] to CMD ["/bin/bash", "./entrypoint.sh"]. Then you'll need to use docker-compose up --build instead of docker-compose up every time you need to rebuild. Let me know if that doesn't work.

[micshar92]

Grrrr sorry I'm so incompetent! After about eight hours of trying to resolve why my localhost refused to connect, I restarted and fixed the problem somehow, but now after connecting, my browsers throw a 404. Surely I'm doing something stupid, right? (my backend app developer brother insists it's easier than I'm making it.)

[jdesrosiers]

@micshar92, don't feel bad, this was definitely not trivial to debug (and it's not on you to debug it anyway). The problem appears to be windows changing the line ending encoding. I think if you undo the hack I gave earlier and convert the line endings in entrypoint.sh from CRLF to LF, the build should work.

It looks like you might also need a fix I put in after you forked your branch, so you'll want to rebase your branch.

(In case you aren't familiar with rebasing ...)

git remote add upstream [email protected]:json-schema-org/understanding-json-schema
git pull --rebase upstream main
git push --force

[jdesrosiers]

@micshar92 I merged the build fix to main. If you rebase (as described in the previous comment), hopefully your branch will build properly now.

[micshar92]

It works... I'm just writing this because any moment now, I'll figure out how to get the changes to show up. It's still "documentation coming soon." Must be a button somewhere...

[jdesrosiers]

@micshar92 It will build what is in your working directory. There's no delay or button to push. If you aren't seeing your changes, you might be on the wrong branch. Maybe you're still on my branch that you were using to help me test the build fix and haven't switched back to your branch where your changes are.

[micshar92]

Welp, thanks for being patient. Better I make mistakes like this before I secure employment.

Seems it was throwing errors. I fixed two lines of invalid JSON-- one with an extra comma, one missing a comma-- and did docker-compose build. But then I got to this one:

It referenced this:

{
  "oneOf": [
    { "prefixItems": [true] },
    { "unevaluatedItems": false }
  ]
}
--X
[1]

...but I don't see why this schema validates. Maybe you do.

Currently, I wrote it as "For instance, in the example below, the unevaluatedItems doesn't "see inside" the prefixItems cousin before it. So since "prefixItems": [ true ] matches only length 1 arrays, and { "unevaluatedItems": false } matches only empty arrays, all instances fail validation."

[jdesrosiers]

For instance, in the example below, the unevaluatedItems doesn't "see inside" the prefixItems cousin before it. So since "prefixItems": [ true ] matches only length 1 arrays, and { "unevaluatedItems": false } matches only empty arrays, all instances fail validation.

[1] matches "prefixItems": [true] and doesn't match "unevaluatedItems": false. One of the schemas matches and the other doesn't, so oneOf passes. Perhaps you meant to use allOf rather than oneOf?

[micshar92]

D'oh that fix was obvious. Anyway, now it runs perfectly. I fixed the note block at the bottom since they don't allow lists, it seems.

So everything is now complete and accurate, to my knowledge. I'll submit the pull request.

[jdesrosiers]

I feel like this has three main parts and the first two parts have a lot of issues. I think it would make more sense to start with something more like the third part. I would make start with a simple open tuple schema, then show various ways of referencing it ($ref) in other schemas to either extend it (as in part 1) or close it (as in part2) and maybe or maybe not both (as in part 3).

[micshar92]

Things came up so this draft took awhile. Anyway, I'm running into this error now, and it doesn't make sense to me.

I ran that schema through my validator and it says there are no errors. I can't find any errors either. Am I missing something?

[Julian]

You have a trailing comma on the line with "$ref": "#" (which isn't valid JSON).

[micshar92]

Aw man, these things are so obvious in hindsight. I've had this same problem in JavaScript but with semicolons. I'm glad Python doesn't have the semicolon at the end of the line.

[micshar92]

Sixth draft up. I'm... not confident in it. It took me a couple hours, then a lightbulb went off-- surely unevaluatedItems is not as simple as I think it is now? Still, it looks great on the site. Just let me know if you have any improvements.

[jdesrosiers]

This is better.

surely unevaluatedItems is not as simple as I think it is now?

It is that simple! In fact, there appear to be some bits that you still have a slightly over complicated mental model for. Go even simpler 😃

[micshar92]

Seventh draft. Much simplified. Any changes to make?

[micshar92]

@Julian @jdesrosiers Busy? This could be the final draft before it's on the website.

[jdesrosiers]

Sorry for the delay. I have one more high-priority thing I have to get done before I can get to this. I expect to get to be able to review tomorrow.

[jdesrosiers]

We're almost there. Thanks for sticking with it. This is a hard one.

[micshar92]

Weird, I didn't get any notification of your responses. (due to the GitHub redesign?) I had to click over to the PR to see anything, so I just did these changes today.

Anyway, eighth (and maybe final?) draft is here. Everything's looking great.

[jdesrosiers]

Just one small whitespace issue to fix, then I'll approve.

[micshar92]

Dunno how that happened, but it's fixed now.

[micshar92]

@Julian This appears to be done. Please approve.

[Julian]

I did already but it still looks good to me! Thanks for the efforts.

[micshar92]

Thank you. This was an adventure in learning.