View this page "JSON Schema Proposal - second draft"

[Kris Zyp]

I put together a second draft of the JSON Schema proposal, based on
the voting and dicussions of the last few weeks. One of the
significant changes is the use of a properties attribute to define the
properties of sub-objects and the use of the an items attribute to
define the items in an array.

Click on http://groups.google.com/group/json-schema/web/json-schema-proposal---second-draft
- or copy & paste it into your browser's address bar if that doesn't
work.

[David Wilhelm]

I read it over ... looks fine, except for the example.....


---8<-----

Below is a more sophisticated example, first the instance object:

{
  "name" : "John Doe",
  "born" : "1979-03-23T06:26:07Z",
  "gender" : "male",
  "address" : "object",

  "properties" :

   {"street":"123 S Main St",
    "city":"Springfield",
    "state":"CA"}
}

---8<-----

surely this should be


{
  "name" : "John Doe",
  "born" : "1979-03-23T06:26:07Z",
  "gender" : "male",
  "address" :

   {"street":"123 S Main St",
    "city":"Springfield",
    "state":"CA"}
}

?


but then the schema

  "address" : {"type":"string",

                 "format":"street-address"}}

would not validate. Shouldn't it be:

"address" : {"type: "object",  "format":"street-address"}

or something?

Dave Wilhelm




Dave

[Kris Zyp]

Thanks, should be fixed now.

Kris

[Hans L]

I'm not a pro at defining grammars, so forgive me if I'm just spouting
nonsense, but I think there is something missing in the grammar given
in this proposal.
There is a grammar rule for object-type-definition:
object-type-definition = { *(property-definition,) }

But none of the other grammar rules make use of this "object-type-
definition", so the schema grammar seems "broken" to me.

Is it supposed to be included in the following line?
type-definition = union-type-definition | simple-type-definition
would become:
type-definition = union-type-definition | simple-type-definition |
object-type-definition

On Feb 18, 7:00 pm, Kris Zyp <kris...@gmail.com> wrote:
> I put together a second draft of the JSON Schema proposal, based on
> the voting and dicussions of the last few weeks. One of the
> significant changes is the use of a properties attribute to define the
> properties of sub-objects and the use of the an items attribute to
> define the items in an array.
>

> Click onhttp://groups.google.com/group/json-schema/web/json-schema-proposal--...

[Kris Zyp]

> But none of the other grammar rules make use of this "object-type-
> definition", so the schema grammar seems "broken" to me.

Thanks, that should be fixed, the "properties" schema attribute uses the
object type definition, which is defined in the list of attributes, but it
should be included in the grammar for clarity.

> Is it supposed to be included in the following line?
> type-definition = union-type-definition | simple-type-definition
> would become:
> type-definition = union-type-definition | simple-type-definition |
> object-type-definition

The latter was the way I had it originally, but popular vote suggested the
former.

Thanks,
Kris

[David Wilhelm]

it would be nice to have a way of specifying that the properties of an
object can have any *name* but their types should be constrained...
something like

{
"type":"object",
"properties":{
"*": {"type":"string"}
}
}

[David Wilhelm]

To follow up to my own comment .... I'm essentially trying to define a
schema for an object whose properties are constrained by a schema. So
why not just have:

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

or even just

{
"type":"object",
"properties":"string"

[David Wilhelm]

Just occurred to me ... a problem with having properties be schema is
that it would be impossible to tell if we were defining the object to
have the "type" property, or referencing a schema... this would arise
for eg. if we were writing a schema for jsonschema :\ so... perhaps
the "*": {schema} syntax is safer. THough it is possible an object
could have a "*" property, it does not seem likely.

[Kris Zyp]

I removed the "*" property due to the complaints about the possibilities of
collision. Instead, there is now the additionalProperties at the schema
level (instead of the object type definition level under properties). So if
you want to define an object where all the properties are strings you can
do:
{
"type":"object",
"additionalProperties":{"type":"string"}
}

[David Wilhelm]

OK, that works .

[David Arno]

Hi all,

I have joined this group as we are looking to switch from using XML to
JSON and want to be able to validate our JSON against a schema. This
schema you are developing looks promising therefore.

Hopefully I am being dense, but I have a question regarding options.
Using RelaxNG, I can specify that some child nodes are either/ or
cases. For example:

<choice>
<element name="rangeIndex">
<data type="int"/>
</element>
<group>
<element name="min">
<data type="int"/>
</element>
<element name="max">
<data type="int"/>
</element>
</group>
</choice>

would validate either the rangeIndex child tag or both the min and max
child tags being present.

I can't see any way to specify that properties are a similar either/
or case with this JSON schema though.

Regards,
David.

[Kris Zyp]

Do you mean that these two are valid?
{rangeIndex:3}
and
{min:1,max:5}

Or these two:
{rangeIndex:3}
and
{rangeIndex:{min:1,max:5}}

These are type unions. Unfortuneately, the first set can't be expressed with
JSON Schema, the group decided to use the simpler union syntax which only
allows for union on primitives. However the second set can be expressed with
JSON Schema because we can union on primitives:
{type:"object",
properties:{
rangeIndex:{
type:["integer","object"],
properties:{
min:{type:"integer"},
max:{type:"integer"}
}
}
}
}

This means that the rangeIndex can be an object or an integer. If it is an
object than the properties attributes applies which defines which properties
it should have.
Kris

[David Arno]

Hi Kris,

It is the first case that I was referring to.

It has occurred to me that this schema may well be able to do what I
want, but it involves a convoluted inheritance/ polymorphism solution.

In both case, there is a value associated with the range or max/ min
definition. So I start with:

{"id":"basicValueObject",
"type":"object",
"properties":{
"value":{"type":"number"}
}
}

Then I can create two extended defs:

{"id":"valueObjectWithRange",
"extends":{"$ref":"basicValueObject"},
"properties":{
"range":{"type":int}
}
}

and

{"id":"valueObjectWithMinMax",
"extends":{"$ref":"basicValueObject"},
"properties":{
"min":{"type":number}
"max":{"type":number}
}
}

That way I think I could then have a schema thus:

{"description":"A data item",
"type":"object",
"properties":
{
"name": {"type":"string"},
"data" : {"type":["valueObjectWithMinMax","valueObjectWithRange"]}
}
}

Does that all sound right, or have I missed the point somewhere?

[Kris Zyp]

> "data" : {"type":["valueObjectWithMinMax","valueObjectWithRange"]}

No, this not allowed. The type attribute may only have a simple type or an
array of simple types. A simple type may only be one of the predefined
values from the spec. To reference an object using the suggested referencing
mechanism, you must use form {"$ref":"basicValueObject"}, which is
essentially like inserting the target in place. If the type unions allowed
schemas than you could write:
"data" :
{"type":[{"$ref":"valueObjectWithMinMax"},{"$ref":"valueObjectWithRange"}]}
which would be the same as writing it out:
"data" : {"type":[
{properties:{
min:{type:"number"},
max:{type:"number"}}},
{properties:{
rangeIndex:{type:"number"}}}]}
But we decided not to allow schemas in type definitions, because of the
ambiguities that can result with conflicting definitions between a type
definition schema and an outer schema that are defining the same values.
Originally, I specifed allowing object type definitions in type definitions
like this:
"data" : {"type":[
{ min:{type:"number"},
max:{type:"number"}},
{ rangeIndex:{type:"number"}}]}
But the group rejected that as well. You can look through the discussion
archives to see the reasons. However, feel free to argue for bringing back
any of these features.
Kris

[Fox Convert]

Kris,

This looks interesting. Two questions on regex patterns.

Pattern appears to be just an "accept" (white list) pattern, allowing
matches. Have you considered reject patterns also, so you can specify
patterns that cause rejection? This would work in conjunction with
other constraints, and would be checked first.

For pattern itself, instead of a single pattern, could one specify an
array of patterns, where any match is accepted? This could handle such
situations as multiple languages, cultural considerations or other
syntax (phone numbers, etc.) without requiring all to be mashed into
one giant ugly regex pattern.

Thanks.

[Kris Zyp]

The blacklist sounds reasonable since it is not possible to negate a regular
expression. I am not big specifying an array of patterns when regex already
supports union (even if it is ugly), as I like to avoid the complication of
having multiple ways of doing the same thing. Is there a precedent in other
schemas? What do others think?
Kris

----- Original Message -----
From: "Fox Convert" <rp31...@gmail.com>
To: "JSON Schema" <json-...@googlegroups.com>

Sent: Thursday, March 20, 2008 2:41 PM
Subject: Re: View this page "JSON Schema Proposal - second draft"

>

[David Wilhelm]

My 2c :

It would be easy to have optional regexes if we could have schemas in
union types... perhaps we should revisit that decision? This would
allow more finely grained options.

The idea of having a negation type, of saying 'any type but X' is
interesting, and quite possibly useful. This would allow disallowing
(sorry) certain regex patterns, but also other types too.

{
"type":"any",
"disallow": ["number", "string"]
}

Dave

[Kris Zyp]

> It would be easy to have optional regexes if we could have schemas in
> union types... perhaps we should revisit that decision? This would
> allow more finely grained options.

I think I am warming up to that idea. However, I think we need to make sure
we clarify the behavior in situations where both the base schema and the
schema inside the type union define the same attribute: An instance must
satisfy all the constraints of the base schema and all the constraints of
the union schema that it matches. Implicitly, if there is conflict, it must
satisfy the most restrictive constraint.
An example:
{properties:{
x:{type:"number",min:0},
y:{type:"number",min:0},
z:{type:"number",min:0}
},
type:[
{ type:"object",
properties:{x:{min:5}}},
{ type:"object",
properties:{y:{min:5}}},
{ type:"object",
properties:{z:{min:5}}}
]
}
This schema would enforce an instance object which had properties x,y,z that
were all zero or higher, and at least one of them had to be five or higher.

>
> The idea of having a negation type, of saying 'any type but X' is
> interesting, and quite possibly useful. This would allow disallowing
> (sorry) certain regex patterns, but also other types too.

Good idea, that has a lot broader application than just regex. Another
application that could possibly see a lot of use:
{type:"any",
disallow:"null"}
to indicate a non-nullable value.
Great ideas, David!
Thanks,
Kris

[labi]

Has anyone considered using the *.jsd extension as the official name
for json schema document :).

Labi

[labi]

[Jakob Kruse]

Yes, I have. Actually I'm using it already. Maybe we should have a
mime type as well?

/Jakob

[Kris Zyp]

> It would be easy to have optional regexes if we could have schemas in
> union types... perhaps we should revisit that decision? This would
> allow more finely grained options.

There have been several requests that it would seem could be handled by
schema unions, and negated schemas. I propose that we should reallow schemas
in the union for the type attribute. A valid instance must still pass all
the requirements of the base schema, and when the type value is an array,
the instance value must match one of the items in the array (correct
primitive type, or match one of the schemas). Perhaps we should also add the
following attribute:

disallow - This would act the same as the "type" attribute except that if
the instance value matched the primitive type value, or any of the primitive
types or schemas in an array, than the schema is not valid

So therefore we could write:
{type:[{regex:"good"},{regex:"great"}],
disallow:[{regex:"bad"}]}
which would accept "a good one", "great string" and reject "a bad one",
"good bad".
{type:[{
disallow: {
properties: {
country:{options:[{value:"US"}]}
}
}
},
{
properties: {
state:{type:"string"}
}
}
],
properties{
country:{type:"string"}
}
}

which would allow country to be any string, but if it is equals to "US",
then the state property must be included. Not pretty but it works. Or the
more attractive use is in the succint ability to define a non-nullable
value:

[Jim Norman]

Kris,

I see where you're headed with this, but the second example really
throws me. It seems to disallow state if the chosen option of country
is "US", but you're saying the opposite.

Jim Norman

[Kris Zyp]

Roughly translating the schema to JavaScript:
typeof obj.country == 'string' && (!(obj.country == "US") || typeof
obj.state == 'string')
Can you see how that says that "the country may be any string, but if it is
US, it must also have a state"?
Kris

----- Original Message -----
From: "Jim Norman" <j...@jsnorman.net>
To: <json-...@googlegroups.com>
Sent: Sunday, April 20, 2008 9:15 PM
Subject: Re: View this page "JSON Schema Proposal - second draft"

>

[Jacob]

Have more recent version of the Second Draft been removed? I can only
see this version and earlier
http://groups.google.com/group/json-schema/web/json-schema-proposal---second-draft?version=11

Jacob

[Kris Zyp]

Wow, I didn't even know you could look at version histories... Is there
something missing, or indicator that it doesn't have the latest in it? I
know there are some things we have discussed recently that I haven't added
yet, because I was waiting for feedback (disallow, schemas in the type
attribute, and requires).

Kris
----- Original Message -----

From: "Jacob" <jacob...@gmail.com>
To: "JSON Schema" <json-...@googlegroups.com>

[Jim Norman]

I can understand it now, but the syntax is so obfuscated that I would hesitate to use it.  I'm not sure I could ever get it right.  There must be a better way.  I still like requires: for its simplicity for this type of functionality.

Jim Norman

[Kris Zyp]

I like "requires" too, but I am still concerned about adding the ability to be conditional based on the value of another property with only equivalence testing. If that is really the overwhelming use case, I guess we could do it, but it just seems arbitrary to stop at equivalence as the criteria. Perhaps another possibility would be to allow the requires to take a schema, and if the property is present than the associated schema must be valid. This could check for the presence of property, the value of a property, and much more complex logic.

Kris

----- Original Message -----

From: Jim Norman

To: json-...@googlegroups.com

Sent: Thursday, April 24, 2008 4:35 PM

Subject: Re: View this page "JSON Schema Proposal - second draft"

[Kris Zyp]

BTW, I updated the current draft to add the simple version of "requires" (just a string referring to property) for now. I also added "disallow" and re-allowed schemas in type unions. Let me know if you have any objections. Oh, also I removed the spam on the page :/.

Kris

----- Original Message -----

From: Jim Norman

To: json-...@googlegroups.com

Sent: Thursday, April 24, 2008 4:35 PM

Subject: Re: View this page "JSON Schema Proposal - second draft"

[Claudio D'Angelo]

I don't undestend what is the scope of disallow. What about of?
{"type":"string", "disallow":"integer"}
What do you mean? This element must be a string and not an integer?

Maybe the use only for any type? Is really usefull?

[Kris Zyp]

> I don't undestend what is the scope of disallow. What about of?
> {"type":"string", "disallow":"integer"}
> What do you mean? This element must be a string and not an integer?

Obviously that is useless.

>
> Maybe the use only for any type? Is really usefull?

Since we are once again allowing schemas in union types and disallow arrays,
you now have the ability to compose very complex logic with disallow. For
example consider this naive XML checker that doesn't allow script tags
(obviously this doesn't really handle all XML, just is an example):
{
type:"string",
pattern:"<\w+>[^<]*</\w+>",
disallow:[{pattern:"<script>"}]
}

By using disallow with schemas you can create some pretty sophisticated
rules without much burden on the validator.
Kris

> >
>

[Claudio D'Angelo]

I understand!! And I like it! but... one clarification.

Disallow indicate a value not a type,for example:
i can write
{type : integer, disallow : [1,3,5]}
or
{type : string, disallow :["xxx", "yyy"]}

> - Nascondi testo tra virgolette -
>
> - Mostra testo tra virgolette -

[Kris Zyp]

> Disallow indicate a value not a type,for example:
> i can write
> {type : integer, disallow : [1,3,5]}
> or
> {type : string, disallow :["xxx", "yyy"]}

No, sorry, you can't do that. "disallow" is intended to be a direct negation
of "type", which makes it extremely easy to implement for validators. Plus
if you allowed values, you couldn't allow types because of the ambiguity.
Kris

[Claudio D'Angelo]

I'm confused.
In your example you use a string type in the disallow when the type of
schema instance was string but in specification you write:
This attribute may take the same values as the "type" attribute,
however if the instance matches the type or if this value is an array
and the instance matches any type or schema in the array, than this
instance is not valid.

Your example was invalid.

[Kris Zyp]

No, I used a pattern attribute in the disallow:
{

[Kris Zyp]

I updated the proposal for the new definitions for "enum" and
"options". I also updated the JSON Schema reference implementation and
schema for schema.

Click on http://groups.google.com/group/json-schema/web/json-schema-proposal---second-draft
- or copy & paste it into your browser's address bar if that doesn't
work.

[Jim]

Kris,

Just a couple of comments:

1) "required" should be "requires" in the following:
*requires
*This indicates that if this property is present, the property given by
/requires /attribute must also be present. For example if a object type
definition is defined:
|{"state":{optional:true},"town":{"required":"state",optional:true}}|

2) This links are broken:
http://groups.google.com/group/json-schema/web/json-schema-possible-formats
http://groups.google.com/group/json-schema/web/common-json-schema-definitions

Jim Norman
Kris Zyp wrote:

[Kris Zyp]

> 1) "required" should be "requires" in the following:
> *requires
> *This indicates that if this property is present, the property given by
> /requires /attribute must also be present. For example if a object type
> definition is defined:
> |{"state":{optional:true},"town":{"required":"state",optional:true}}|

Thanks, fixed that.

>
> 2) This links are broken:
> http://groups.google.com/group/json-schema/web/json-schema-possible-formats
> http://groups.google.com/group/json-schema/web/common-json-schema-definitions

They don't appear to be broken to me, although they were spammed way back
when, so I fixed that.
Kris

[Kris Zyp]

I changed the name of the "unique" property to "identity" and added
more explanation. The schema specification can now also be found at
http://json-schema.org .

[Steve Vinoski]

Overall I think the approach looks good, but isn't it confusing to
have a property named "identity" (listed in the "properties" section)
and also a property named "id" (listed in the "extending and
referencing" section)? Are they supposed to be the same, or are they
really two different properties for two different things?

[Kris Zyp]

They are different, the "identity" property specifies which property in the
schema's instances can be used for identification and referencing (different
structures have different identity properties). The identity property for
schemas is "id", that is the schema for schemas specificies that it's
instances' (schemas) "id" property is the identity property. Does that make
sense?

I updated the specification (working draft) to hopefully make them more
clear.

Thanks,

Kris
----- Original Message -----

From: "Steve Vinoski" <vin...@gmail.com>
To: "JSON Schema" <json-...@googlegroups.com>