[Docs] Updated Examples Section

[aku1310]

In Other Examples:

• Added more use cases of JSON Schema
• Added a short summary and index at the top

In Miscellaneous Examples:

• Removed Geographical Locations example as it is more suited in 'Other Examples' section
• Renamed it to Generic Examples

In Modelling a File System:

• Added a short summary before the index

Please let me know what you think about this and any changes required.

[benjagm]

Nice job. I am providing some small suggestions for better consistency among the different example pages.

We'll need more people reviewing the examples.

[aku1310]

Nice job. I am providing some small suggestions for better consistency among the different example pages.

We'll need more people reviewing the examples.

Thank you! I've made the suggested changes.

[benjagm]

Looks good to me. Nice job!

I'd love to get at least another review.

[gregsdennis]

These examples look good, and it appears you put some time into them. However, I would expect each example to showcase some different feature set.

For instance, if you're starting from the top, "blog post" adds nested properties, a feature that "address" doesn't have. But then "book" just illustrates the same feature set that "address" did. Does having "book," then, hold any real value?

To me, these all look like basically the same example. (Maybe that's needed for this page; I'm not sure.)

[gregsdennis]

If you're going to use the "speech" form of these properties (e.g. "published date" instead of publishedDate), I think it should be without formatting. Otherwise, just use the actual property names. Similarly for the other summaries. We should be consistent as well.

[spacether]

How about using the publishedDate form instead? Having a space in a key is not something that I have seen widely used in json in my experience.

[gregsdennis]

Yes, that would fall under

Otherwise, just use the actual property names.

[jeremyfiel]

nice job on the examples. I believe you spent significant effort on these and the community is grateful for contributions like this. I agree with Greg on the necessity for similar examples. The other thing I would caution is JSON Schema providing too many schema examples of things. You don't want to imply these are the preferred schema objects for the entities listed. Not to discredit your effort, but the schemas provided are also quite basic. No referencing, or composition of multiple schemas is used. No examples of particular keywords like propertyNames, $anchor, $dynamicRef, prefixItems, additionalItems and even some of these keywords defined together, what are the different behaviors you can create with them like this example: dynamic properties with constraints of only lower case with an underscore, and must be type: number.

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "propertyNames": {
        "pattern": "^[a-z_]+$"
    },
    "patternProperties": {
        "": {
            "type": "number"
        }
    }
}

#valid
{
    "any_property_name": 33,
    "im_a_new_property": 66
}

#invalid
{
    "I_am_not_WORKING": 33,
    "BIG_FAIL": 66
}

#invalid
{
    "any_property_name": "33",
    "im_a_new_property": 66
}

I believe a majority of JSON Schema users require additional education in those areas and this is where it should be provided.

e.g.
how does referencing work with multiple schemas?
how can I compose 30 subschemas into something useful?
how can I design and effectively use component schemas in a large project, across domains or products?

In an enterprise design, I can guarantee your schema is never straight forward like name: <string> or address: <string>. there are ids and codes and descriptions for everything!

Just as an example, we have a person defined in a top level schema in 4 lines of code, but if I blow out the schema of person, it's 1400 lines of code of all the composed schemas we are using. I wouldn't expect JSON Schema to show me an example of that type of schema, but I would love to see how I should compose all of the subschemas to create that behemoth. How would I dissect reusable components and refactored the schemas to use them?

"person": {
            "description": "The candidate personal data",
            "$ref": "../../../../../common/person/personType_v01.json"
        }

[aku1310]

@gregsdennis @jeremyfiel Thank you for the reviews! I'll definitely modify the examples as I do see how they can seem repetitive and basic. Will research more on how I can improve them with your suggestions and then update the PR soon!

[aku1310]

I apologize for the delay in updating this PR 😅

I have added some more properties to the examples such as $dynamicRef, $anchor, etc., and also removed some redundant examples which were showcasing something new.

Please let me know what you think about this.

[gregsdennis]

It looks like there are some misunderstandings around $dynamic* and $anchor. It'd be good to review how those work. Unfortunately we don't really have good docs for $dynamic* just yet (that I'm aware of) so you'll likely just need to try to read the spec (we can answer questions, too), but here's $anchor.

[aku1310]

It looks like there are some misunderstandings around $dynamic* and $anchor. It'd be good to review how those work. Unfortunately we don't really have good docs for $dynamic* just yet (that I'm aware of) so you'll likely just need to try to read the spec (we can answer questions, too), but here's $anchor.

Thank you! I'll go over this by the weekend, and update the PR soon.

[Relequestual]

Hey @aku1310, firsly, thanks again for taking the time and making the effort to try and improve our learning resources.
Did you still want to continue to improve your PR here?
If you're not wanting to spend much more time on it, maybe you could split some parts of it into a smaller PR, and then continue with other smaller PRs as time allows.
Of course, please feel freeto ask further questions if you have any.

[aku1310]

Hey @aku1310, firsly, thanks again for taking the time and making the effort to try and improve our learning resources. Did you still want to continue to improve your PR here? If you're not wanting to spend much more time on it, maybe you could split some parts of it into a smaller PR, and then continue with other smaller PRs as time allows. Of course, please feel freeto ask further questions if you have any.

Hi, I apologise for the delay in this PR, I have not been able to properly work on this for a while 😅 Only the use cases in the other examples is left for now. Would it be alright to continue in this PR only? Or I can split it up if that is preferable. I aim to get this update the PR by this weekend as I have gotten free from other work now as well 😅

[benjagm]

Would it be alright to continue in this PR only?

That is totally fine Akanksha! We are very close to get this done. If you need help or feedback let me know and I'll be happy to help.

[aku1310]

That is totally fine Akanksha! We are very close to get this done. If you need help or feedback let me know and I'll be happy to help.

Will surely ask, thank you!!

[aku1310]

It looks like there are some misunderstandings around $dynamic* and $anchor. It'd be good to review how those work. Unfortunately we don't really have good docs for $dynamic* just yet (that I'm aware of) so you'll likely just need to try to read the spec (we can answer questions, too), but here's $anchor.

Hi, as per the review, I have removed anchor from JobPosting and MovieSchema as it was not helpful there, and also updated the DeviceType example using oneOf instead of dynamicRef since oneOf` does seems like a much better choice for that example.

Please let me know what you think about this.

[gregsdennis]

The casing here needs to match what the schema expects. But the example looks a lot better now.

[aku1310]

Oh yes, I'll just update that 😅

[gregsdennis]

Overall much better. Left one more comment; just a minor thing.

[benjagm]

Excellent job @aku1310!

[Relequestual]

Thanks for all your work on this. Very much appreciated!