[📝 Docs]: Simplify examples on getting started page

[bhavukkalra]

What Docs changes are you proposing?

Emerged out of the original issue #653. Page - getting-started-step-by-step

This issue tracks the progress on having simpler workings while explaining required keys to a new user onboarded.

Currently - explanation for required keys of "productId", "productName" is kinda confusing. The docs does mentions that they are required but it can't be observed in the changes made. It is only some time later that we see the line of code

"required": [ "productId", "productName", "price]" 

Where it starts to make sense.

A better way to write it would be

  "properties": {
    "productId": {
      "description": "The unique identifier for a product",
      "type": "integer"
    }
  },

  "required": ["productId"]

i.e Update the required key as we go along adding new attributes. Not all at once (which is currently in the docs). As it makes a proper flow of what is written in text and simultaneously in code

Original comment - https://github.com/json-schema-org/website/issues/653#issuecomment-2056423433

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[chidiadi01]

Hi @bhavukkalra, I'd love to work on this issue.

[gregsdennis]

I think the page is fine as it is. It presents a journey that I think is more akin to what a developer will experience building a schema: you define the properties, then you say which ones are required. In JSON Schema these are two different constraints, so it makes sense to help the developer start thinking that way.

[github-actions[bot]]

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:

[benjagm]

Finally we are not implementing changes.