Use Cases and Requirements document

[awwright]

This is a document I've been working on for a little bit that I think would be very relevant to some of the discussion right now.

We're trying to figure out what parts of the specification are "stable," but (IMO) stability is something that you determine with respect to a particular use case. An example I pointed out earlier, if I publish a GPU-intensive program that stops being effective as a space heater because I improved the algorithm, too bad for you because it was never "stable" for home heating purposes, only cat detection purposes (or whatever).

This document would describe the use cases that we actually intend to support; when we make changes to the specification, we can point to this document and say "this feature in Use Cases would break if we made this change." Or we can make a change and point at this to say "yes, the change breaks cat detection, but JSON Schema was never intended to perform image analysis."

Here's a PDF rendering (note how it's not a "draft"): jsonschema-use-cases.pdf

While it currently specifies applications as "Use Cases," a "Requirements" section would be expanded to actually list the particular methods that implement each use case.

[Relequestual]

This is actually super useful, so thanks.
I think there are a few things missing...

• Code generation, specifically "models" or classes, which is a really common use case, and "types" for typed languages
• UI generation, mostly generating forms or other UI elements, which are pretty common. (Some impelementations have larger followings than we do... at least I think)
• Documentation generation - I've seen at least 3 articles talk about JSON Schema primerily for generating documentation. I don't see that covered in your doc

Given how frequently I see these things, I'd expect them to be explicitly called out.

---

You mention database constraints in section 3.7. Can you explain why this is in section 3 as opposed to a note in section 4, aka a use case for extensions.

Given this work, maybe you could propose a short bulleted list of what's "in scope" for our charter work?
👉 json-schema-org/community#286 (comment)

[gregsdennis]

Overall, I question the need for this document. The use cases that @Relequestual mentioned exist as a result of not explicitly listing use cases. I fear that explicitly listing use cases will hinder our users' creativity as they will see that their need doesn't fit within the scope of the project and they'll go find another solution.

Furthermore, some of these are not areas that we have, in the past, officially supported. By declaring them, you are changing our stance on that. While I agree that we should start supporting some of these, I don't know that we have the expertise or personnel required to do so to the degree that declaring "officially supported use cases" would necessitate.

Personally, I think data validation and annotation should remain our focus, and we should isntead encourage others to devise new use cases and join our community in order to support and spread knowledge of their ideas.

[awwright]

I updated the PDF rendering: jsonschema-use-cases.pdf

[gregsdennis]

Looks good. Just some minor nits.