Custom Keywords (similar idea to custom types)

[dEv Jones]

There have been a lot of posts asking about the support for custom types, so forgive me if this is a duplicate but I couldn't find the answer I was looking for.

One of the things we are using JSON Schemas for is to generate valid seed data to mock API responses.  One problem we've encountered is that it's hard to know what kind of fake data is allowed.  E.g. a "firstName" property would expect one kind of string whereas "mailingAddress" would expect another (etc. etc. etc.).  They can't all use "Lorem Ipsum" text.

From what I understand, one of the ways that this could be solved is by providing a custom $schema and then referencing all of them using the "allOf" keyword.  

For example, if we had the normal JSON Schema definition like this (named "a.json"):

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
     "firstName": {"type": "string"},
     "mailingAddress": {"type": "string"}
  }
}

and then a custom schema type (named b.json):

{
  "$schema": "http://my-custom-schema/",
  "type": "object",
  "properties": {
     "firstName": {"type": "name"},
     "mailingAddress": {"type": "address"}
  }
}

Our schema could combine them doing something like:

{
  "allOf": ["a.json", "b.json"]
}

Since the b.json specifies a custom $schema, then schema validators SHOULD ignore it, right?  And we can code our own validator to work with schemas defined as $schema "http://my-custom-schema/".  Is that correct? 

Since this approach is a bit laborious (it effectively requires us to create 2 extra schemas to adequately describe a schema), I'm wondering if it's acceptable to add in custom keywords to accommodate the extra data?  A schema validator SHOULD ignore extra/superfluous keywords, right?

In the below schema, I've added in custom values for "x-type" to specify to our random generators what kind of fake data should be generated for each field.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
     "firstName": {"type": "string", "x-type": "name"},
     "mailingAddress": {"type": "string", "x-type": "address"}
  }
}

Is that a valid solution to add custom keywords to a schema definition?  The online validator @ https://json-schema-validator.herokuapp.com/ shows a warning for a schema like that, but not an error (it says that the keywords are unknown and will be ignored).  

There are lots of other use cases for this type of thing, but hopefully the above demonstrates a couple possible solutions.  Can someone tell me if they are valid solutions?

[Jason Desrosiers]

The first solution is not a good idea.  You should never redefine a keyword.  That way your schemas still work with standard validators.  The second solution is the way to go.  The warnings you are getting are fine.  They are to help you in case you misspelled something.  Since you are using an extra keyword on purpose, you can safely ignore these warnings.  I recommend against creating a custom meta-schema to describe your new keyword.  I'd just ignore the warnings.

[Henry Andrews]

For the sort of things you're talking about, a custom format is probably better.  You're talking about the semantics of the string:  this string is not just a string, it should have meaning as an address, or as a name.  That is what format is intended for, and why it is extensible.  Many, if not most, validators will allow registering custom formats and custom validators to run when those formats are encountered.

thanks,

-henry

---

From: Jason Desrosiers <jdes...@gmail.com>
To: JSON Schema <json-...@googlegroups.com>
Sent: Thursday, July 13, 2017 10:54 AM
Subject: [json-schema] Re: Custom Keywords (similar idea to custom types)

The first solution is not a good idea.  You should never redefine a keyword.  That way your schemas still work with standard validators.  The second solution is the way to go.  The warnings you are getting are fine.  They are to help you in case you misspelled something.  Since you are using an extra keyword on purpose, you can safely ignore these warnings.  I recommend against creating a custom meta-schema to describe your new keyword.  I'd just ignore the warnings.

On Tuesday, July 11, 2017 at 3:01:34 PM UTC-7, dEv Jones wrote:

There have been a lot of posts asking about the support for custom types, so forgive me if this is a duplicate but I couldn't find the answer I was looking for.

One of the things we are using JSON Schemas for is to generate valid seed data to mock API responses.  One problem we've encountered is that it's hard to know what kind of fake data is allowed.  E.g. a "firstName" property would expect one kind of string whereas "mailingAddress" would expect another (etc. etc. etc.).  They can't all use "Lorem Ipsum" text.

From what I understand, one of the ways that this could be solved is by providing a custom $schema and then referencing all of them using the "allOf" keyword.  

For example, if we had the normal JSON Schema definition like this (named "a.json"):

{
  "$schema": "http://json-schema.org/draft- 04/schema#",

  "type": "object",
  "properties": {
     "firstName": {"type": "string"},
     "mailingAddress": {"type": "string"}
  }
}

and then a custom schema type (named b.json):

{
  "$schema": "http://my-custom-schema/",
  "type": "object",
  "properties": {
     "firstName": {"type": "name"},
     "mailingAddress": {"type": "address"}
  }
}

Our schema could combine them doing something like:

{
  "allOf": ["a.json", "b.json"]
}

Since the b.json specifies a custom $schema, then schema validators SHOULD ignore it, right?  And we can code our own validator to work with schemas defined as $schema "http://my-custom-schema/".  Is that correct? 

Since this approach is a bit laborious (it effectively requires us to create 2 extra schemas to adequately describe a schema), I'm wondering if it's acceptable to add in custom keywords to accommodate the extra data?  A schema validator SHOULD ignore extra/superfluous keywords, right?

In the below schema, I've added in custom values for "x-type" to specify to our random generators what kind of fake data should be generated for each field.

{
  "$schema": "http://json-schema.org/draft- 04/schema#",

  "type": "object",
  "properties": {
     "firstName": {"type": "string", "x-type": "name"},
     "mailingAddress": {"type": "string", "x-type": "address"}
  }
}

Is that a valid solution to add custom keywords to a schema definition?  The online validator @ https://json-schema- validator.herokuapp.com/ shows a warning for a schema like that, but not an error (it says that the keywords are unknown and will be ignored).  

There are lots of other use cases for this type of thing, but hopefully the above demonstrates a couple possible solutions.  Can someone tell me if they are valid solutions?

--
You received this message because you are subscribed to the Google Groups "JSON Schema" group.
To unsubscribe from this group and stop receiving emails from it, send an email to json-schema...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[dEv Jones]

Thank you for the input!  So to summarize, the recommended solutions here would be to:

1. Add a custom keyword, e.g. "x-type" (which should be ignored by any existing validators)

OR

2. Use custom formats, e.g. "format": "person-name" (and those custom values for format should likewise be ignored by existing validators)

I think for our purposes of creating realistic fake data, the second option would be cleanest.  Any validation that needed to be done on a custom format could be triggered by defining a regular expression in the field's "pattern" property.  Stay tuned -- should have something worked out for a JSON-Schema-powered faker package...