example attribute
#121
Comments
|
Thanks for migrating the issue. I can really see the utility of |
|
@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. |
|
@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. |
|
@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. |
|
@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 |
|
BTW I like this idea :) |
|
@slurmulon cool, I wasn't familiar with hazy, but will keep it in mind. Thanks! |
|
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 |
|
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. |
|
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. |
This addresses issue json-schema-org#121. Most of the wording is lifted from "default", which is similar and can serve the same purpose. This wording explicitly allows for using "default" as an example which was not part of the original request but seems reasonable. Obviously, that part can be removed if deemed undesirable.
This addresses issue json-schema-org#121. Most of the wording is lifted from "default", which is similar and can serve the same purpose. This wording explicitly allows for using "default" as an example, without requiring that implementations do so. The "MAY be used in a root schema or any subschema" line for all of the meta-data keywords seems to have been a holdover from an earlier approach of always specifying where keywords could be used. It is not done anywhere else and raised a red flag in review of the original version of this commit, so this version removes it from all meta-data keywords.
This addresses issue json-schema-org#121. Most of the wording is lifted from "default", which is similar and can serve the same purpose. This wording explicitly allows for using "default" as an example, without requiring that implementations do so. The "MAY be used in a root schema or any subschema" line for all of the meta-data keywords seems to have been a holdover from an earlier approach of always specifying where keywords could be used. It is not done anywhere else and raised a red flag in review of the original version of this commit, so this version removes it from all meta-data keywords.
This addresses issue json-schema-org#121. Most of the wording is lifted from "default", which is similar and can serve the same purpose. This wording explicitly allows for using "default" as an example, without requiring that implementations do so. The "MAY be used in a root schema or any subschema" line for all of the meta-data keywords seems to have been a holdover from an earlier approach of always specifying where keywords could be used. It is not done anywhere else and raised a red flag in review of the original version of this commit, so this version removes it from all meta-data keywords.
This addresses issue #121. Most of the wording is lifted from "default", which is similar and can serve the same purpose. This wording explicitly allows for using "default" as an example, without requiring that implementations do so. The "MAY be used in a root schema or any subschema" line for all of the meta-data keywords seems to have been a holdover from an earlier approach of always specifying where keywords could be used. It is not done anywhere else and raised a red flag in review of the original version of this commit, so this version removes it from all meta-data keywords.
|
Merged #123, the "examples" keyword |
In our usage we found it helpful to supplement with an
exampleattribute. 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
The text was updated successfully, but these errors were encountered: