json-schema-org.github.io

json-schema-org.github.io copied to clipboard

Refs: json-schema-org/community#199

✅ Deploy Preview for condescending-hopper-c3ed30 ready!

Name	Link
🔨 Latest commit	2f0a2f8b8304afcc263a242567dc04a2890a195e
🔍 Latest deploy log	https://app.netlify.com/sites/condescending-hopper-c3ed30/deploys/64499286c407ef0007f2646b
😎 Deploy Preview	https://deploy-preview-484--condescending-hopper-c3ed30.netlify.app/learn/glossary
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

Given the reviews and discussion points towards wanting to reframe how these words are defined, without the context of "the vocabulary system" as it's likely to change a bit, maybe we should close this PR in favour of (creating a new issue to cover these definitions and then) opening a new PR?

Happy to close it -- it's odd to me to not document terms we already use because we want to redefine them, but if y'all feel that's the right way to move forward sure.

@Relequestual I have to say I agree with @Julian that it would make more sense to document these as-is. We don't know how long it will be before the next release is out, and given the lack of consensus around where these terms are going, we don't know if that release will redefine anything or just label the existing features as not-yet-stable. None of which helps people looking for definitions now. Glancing back over the discussion I thought it was going in a productive direction.

I don't think this discussion was about redefining what "dialect" means, it was about presenting it in an accurate and accessible way regardless of what words are used in the spec. In the definition provided in the spec, the word "vocabulary" can be interpreted in two ways. One way is arguably inaccurate and the other is inaccessible due to the mental gymnastics necessary to draw the appropriate conclusions. Either way, the glossary definition needs to be clear about how "vocabulary" should be interpreted or use a different word entirely.

If you interpret "vocabulary" as a Vocabulary System vocabulary, the definition is not inclusive of versions of JSON Schema that pre-date the Vocabulary System. For years we have been discussing any distinct flavor of JSON Schema as a dialect including past drafts and third-party flavors such as those used by OpenAPI 3.0 and MongoDB. Therefore, the definition in the spec doesn't reflect common usage and there should at least be wording in addition to the spec definition that covers this usage.

However, if you interpret "vocabulary" as the general concept of a vocabulary independent of the Vocabulary System, the spec definition isn't inaccurate, but you have to mentally jump through some hoops to recognize older drafts and third-party flavors as implied single vocabulary dialects. A glossary definition shouldn't require that much effort.

I'm definitely in favor of having something now, but I think the way it's currently written up is in terms of the Vocabulary System and I think that's an incomplete depiction of how the term "dialect" is commonly used.

OK sounds like both of you are indeed happy with writing something down, though I don't feel I was able to get any specific suggestions about what definition we actually use today in conversation -- I'm happy to reopen and give it another shot myself I suppose.

I don't feel I was able to get any specific suggestions about what definition we actually use today in conversation -- I'm happy to reopen and give it another shot myself I suppose.

I can try to remember to take a look at it this/next week sometime. I had a lot going on in Sept and Oct and I think I just forgot.

If you interpret "vocabulary" as a Vocabulary System vocabulary, the definition is not inclusive of versions of JSON Schema that pre-date the Vocabulary System.

Words change over time. We started talking about each section of the spec in the spec as a "vocabulary" before $vocabulary was around. We do not need to accommodate every way that anyone has ever used the word (or the word "dialect").

While the definition of "vocabulary" need not mention $vocabulary, it does need to be compatible with the current usage of the spec.

We do not need to accommodate every way that anyone has ever used the word (or the word "dialect").

I don' t know what you're trying to say here. If I, as an expert, found this ambiguous, then it's definitely going to be ambiguous to casual users who are the target audience of this glossary. I think we agreed that these terms should be defined in a generic way that isn't coupled to the vocabulary system. Currently, the wording used here sounds very much like a description of the vocabulary system. I'm only advocating that the wording be tweaked to reduce ambiguity.

@jdesrosiers the goal of these definitions should be to help people understand what these things are now, and how to use them now. Not to future-proof against possible later changes that we've not even agreed to do yet, much less agreed on their form. So yes, $vocabulary should be mentioned because that's how things work now. If there needs to be language about it being specific to 2019-09 and later, that's fine. But reading the glossary should make it clear what to look at in the spec or other documentation.

That's not the way I'm looking at it. It's not a matter of future-proof anything, it's a matter of scope. I think the glossary should describe the concept, and UJS should describe the mechanism. As you say, the concept of a vocabulary pre-dates the vocabulary system and the introduction of the vocabulary system didn't change that concept. The concept of a dialect has existed prior to the vocabulary system as well although we didn't have a name for the concept until later.

Mentioning $vocabulary is hardly getting stuck in the weeds. Not everyone reads UJS. I do not agree with your push to remove information from other sources in favor of UJS.

The concepts of vocabularies and dialects are far more important as they exist in 2019-09 and later. They don't have much useful meaning prior to that, and trying to span all of those usages just muddies both the concept and the usage.

I don't feel strongly enough about this debate it any further. @Julian, I've given you my thoughts and I support whatever direction you want to go with this PR.

All good sorry was working on some other things today so didn't chime in yet but very much appreciate the suggestions will see what you've got and I'm sure get something workable!

I've given one last shot at trying to make everyone happy here -- I think folks mostly were on board here at least with "disagree but ok"'ing this change -- given I've just tweaked it again I'll give a bit of time (days) to see if anyone pipes up again, and if not will rely on the previous OK's (and always fix something later if we care to).

Thanks both!