[📝 Docs]: Review texts of the new use cases page of the upcoming release 3 of the website.

[benjagm]

Is your feature request related to a problem? Please describe

We have created a new use cases page for our docs but we need to add all the texts with something inspiring.

You can see that page here: https://web-release-3.website-2v2.pages.dev/overview/use-cases

Source: https://github.com/json-schema-org/website/tree/web-release-3/pages/overview/use-cases
Data: https://github.com/json-schema-org/website/blob/web-release-3/data/use-cases.json

Branch: https://github.com/json-schema-org/website/tree/web-release-3

Describe the solution you'd like

Compelling use cases

Describe alternatives you've considered

No response

Additional context

No response

Are you working on this?

No

[benjagm]

@jviotti We'd love to get your collaboration for this page. I think it will take 2 hours of your time.

[jviotti]

Here are some prominent use cases from my notes:

• Form Generation: Render an HTML form from a JSON Schema as a source of truth
• Write API Specifications: Virtually all popular API specifications formats out there are based in JSON Schema
• Type Code Generation: Take a JSON Schema and generate programming language type definitions. Note this can also include database SQL definitions, etc
• Validation: Often an extension of the API specification one, to validate request/responses, but also for any general purpose validation, like config files, etc
• Documentation Generation: Take a JSON Schema to produce nice markdown/HTML docs. Typically used with APIs mostly as far as I can see
• Data Serialization: What I'm personally working on with JSON BinPack
• Databases: A variety of use cases here. For example, MongoDB can use JSON Schema for collection constraints, and also for querying (the filter part of a select!)
• IDE integration: For auto-complete, correction, etc
• Test Generation: There are a few products out there to generate random matching instances given schemas for e2e or even property based testing
• Schema Extraction: Given a set of schema-less instances, derive a schema to better understand the data

What do you think? Its a bit of a rough list, and some have a degree of overlap, but we can polish them together

[jviotti]

Some of those have a certain degree of overlap or are too specific. Here is a revised list:

• Data Validation: The one people know the most about. You can use JSON Schema to validate arbitrary JSON documents in the context of APIs (request/responses), configuration files, or general purpose data modeling like the Genomic Data Commons (https://gdc.cancer.gov/developers/gdc-data-model) in the scientific space

• UI Generation: JSON Schema can be used to automatically generate user interfaces that adhere to a given schema. This is very commonly done for generating web forms (like Typeform) or embedded forms within a web app (sign up form?)

• Code Generation: Similarly to the UI generation use case, you can generate code out of a JSON Schema. For example, you can generate TypeScript type definitions or even SQL to model your database tables

• Documentation: Because schemas serve as the source of truth, you can generate pretty documentation for a data structure using JSON Schema. This commonly done in the context of APIs with OpenAPI, etc, but also in IoT with WoT, and I saw some config file documentation generated in this way too

• Data Serialization: Compress JSON data for storage/transmission. For example: https://jsonbinpack.sourcemeta.com

• Automated Testing: Good definitions of input/output that schemas provide enable contract and property based testing scenarios. For example: https://schemathesis.readthedocs.io/en/stable/

• Schema Inference: This is pretty useful in data science. You may have huge JSON datasets and don't know the structure well. You can use tools that will derive a JSON Schema from the data for you to better understand it and act on it

• Semantics Gathering: JSON Schema can produce annotations that augment the given data. This is very convenient in data science too. If you have good schema definitions, combine them with your JSON datasets, add back the annotations, and get back richer data

[jviotti]

@benjagm I think a good intro for this page would be a couple paragraphs explaining that JSON is the most popular data format in existence right now, used pretty much across every industry that you can think of. So JSON Schema being the industry-standard schema language for JSON, its applicability is huge.

[benjagm]

I like it the second iteration. The use cases need to be inspiring to both developers and business.

[benjagm]

@benjagm I think a good intro for this page would be a couple paragraphs explaining that JSON is the most popular data format in existence right now, used pretty much across every industry that you can think of. So JSON Schema being the industry-standard schema language for JSON, its applicability is huge.

Can we get you support for it?

[jviotti]

I wrote about this in the book and on my papers. I can prepare a few paragraphs!

[gregsdennis]

It would probably be a good idea to include @awwright's https://github.com/json-schema-org/json-schema-spec/blob/main/jsonschema-use-cases.xml as a source for this. It's the entire purpose of that file.

[benjagm]

It would probably be a good idea to include @awwright's https://github.com/json-schema-org/json-schema-spec/blob/main/jsonschema-use-cases.xml as a source for this. It's the entire purpose of that file.

100%!! Thanks for sharing. I wasn't aware of this!

I'll use this and check with Juan an you

[jviotti]

That's great. It covers many that I suggested, plus we can augment the list with some more I noted above

[kwennB]

I want to take this up. @benjagm