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

benjagm commented 6 months ago

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 commented 6 months ago

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

jviotti commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

@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 commented 6 months ago

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

benjagm commented 6 months ago

@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 commented 6 months ago

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

gregsdennis commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

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

kwennB commented 4 months ago

I want to take this up. @benjagm

benjagm commented 4 months ago

@kwennB I am working on this.

benjagm commented 4 months ago

Closed as completed.

json-schema-org / website