`example` attribute

[geemus]

In our usage we found it helpful to supplement with an example attribute. It was particularly helpful in documentation cases to ensure that reasonable values would be displayed for human consumption. Just wanted to put this forward as something that might be more broadly useful. Thanks!

See also: json-schema/json-schema#104

[Relequestual]

Thanks for migrating the issue. I can really see the utility of example for generating human readable docs.
I would steer clear of generating example values automatically though (having looked at the old issue). It seems like that wasn't your intent, and would complicate things.

[geemus]

@Relequestual yeah, we have stuck predominantly to manually entering these values and it usually seems like the right thing to do. There are a couple cases, in particular, where automatic makes a bit more sense though. For instance, I'm not sure how much value you get from manually specifying an example for datetime (where epoch or midnight january 1st, 2000 or really any particular datetime). I think that can be done in whatever doc-generation tools one might build though, vs these manual examples which would need to live down in the schema itself.

[slurmulon]

@geemus Just wanted to note that there are many schema rules in which automatic example data cannot be generated for, such as arbitrary RegEx patterns, rules with array / object size constraints, etc. If you need something for generating random data within your examples/schema, you could use a tool called hazy to tokenize your examples with randomly generated data, that way you rarely have to come up with example data yourself (requires pre-processing, has a simple lib)

The obvious limitation here is that this tool doesn't concern itself with the schemas or their rules, but it should at least save you some time when it comes to writing example/ data. It does support embedding though so you can at least keep things DRY.

[geemus]

@slurmulon agreed.

Automatic examples are only possible in a limited context, and are of somewhat dubious value (plus there are other ways to handle this). Manual examples seem like they could be valuable.

[slurmulon]

@geemus yeah, you'll be forced to do manual for many values. We've just found that hazy helps alleviate this a bit and ultimately makes our fixture data (in your case, schemas) easier to read / understand

[slurmulon]

BTW I like this idea :)

[geemus]

@slurmulon cool, I wasn't familiar with hazy, but will keep it in mind. Thanks!

[slurmulon]

Could not expect you to, It's just a no-name node library that I wrote to help maintain example / test data. Hoping somebody will get some use out of it besides me :P

[handrews]

I'm in favor of this- both major JSON Schema projects that I've been involved with independently added this for the exact same reasons.

[Relequestual]

I personally would see this as a way to give manual examples where the expected input isn't clear. I don't see this as a field which would pre-fill a form with a placeholder. As stated, this would be for human readable documentation.