json-schema-org / website

JSON Schema website
https://json-schema.org
Other
52 stars 138 forks source link

✨ Enhancement: Rebuild the getting started guide #549

Closed benjagm closed 1 month ago

benjagm commented 5 months ago

Is your feature request related to a problem? Please describe

We are aware that learning JSON Schema is not easy and we also know that our docs needs a lot of improvement. But now, with the new feedback component we are even more clear about the areas that needs improvement and the getting started guide is clearly one of them.

After long consideration, I think the best approach is proceeding with a first iteration consisting on changing the section Validating JSON data against the schema.

We don't maintain or promote any validator over others and in addition we are not integrating any validator. This is great to keep our neutrality but it adds friction into new users journey. We are going to keep that neutrality but it will be great to allow the users feel the HAHA moment of getting a json message validated against a schema.

My proposal is to create a component that provides different valid and invalid examples for different uses cases following this prototype:

Screenshot 2024-04-18 at 15 51 05

The default example shown by the component is the one used for getting started. Considering that the examples are pre-recorded and we know the validation result.

  1. Initially the component shows the default schema instance. (this will be paremetrized in a yaml file)
  2. The user can select 2 or 3 different instances, valid and invalid and we show the result and the explanation why showing a green check when is valid and red cross when is invalid.
  3. We'll provide some other schema examples with instances so the users can see it working in different scenarios. We add simple and other more complex examples.
  4. We provide a download button to allow to download the schema and the selected instance so the user can try it with the validator of their choice.

The idea is let the users see the power of the json schema validation and show other real life examples to inspire them.

benjagm commented 5 months ago

Some examples:

VivekJaiswal18 commented 5 months ago

Hello @benjagm, can I help you with this in any way.

benjagm commented 5 months ago

Thanks Vivek. I still need to find some time to create a prototype with what I have in mind.

swaparup36 commented 4 months ago

Hey @benjagm can I work on this?

benjagm commented 4 months ago

Hey @benjagm can I work on this?

My apologies for the late response. I think @DhairyaMajmudar is working on this. Isn't it?

DhairyaMajmudar commented 4 months ago

Yes I am currently working on this.

github-actions[bot] commented 2 months ago

Hello! :wave:

This issue has been automatically marked as stale due to inactivity :sleeping:

It will be closed in 180 days if no further activity occurs. To keep it active, please add a comment with more details.

There can be many reasons why a specific issue has no activity. The most probable cause is a lack of time, not a lack of interest.

Let us figure out together how to push this issue forward. Connect with us through our slack channel : https://json-schema.org/slack

Thank you for your patience :heart:

github-actions[bot] commented 1 month ago

Hello! :wave:

This issue has been automatically marked as stale due to inactivity :sleeping:

It will be closed in 180 days if no further activity occurs. To keep it active, please add a comment with more details.

There can be many reasons why a specific issue has no activity. The most probable cause is a lack of time, not a lack of interest.

Let us figure out together how to push this issue forward. Connect with us through our slack channel : https://json-schema.org/slack

Thank you for your patience :heart: