Version 3 review
Gary Court
1. In the spec I see "exclusiveMinimum"/"exclusiveMaximum" while in
the schema I see "minimumExcluded"/"maximumExcluded".
2. The numbering of the hyper schema sections seems off. Example, I
think 6.2.1.2.1 should be 6.2.1.3
3. For changelog entry "Replaced required attribute with optional
attribute", the words "required" and "optional" should be swapped.
4. Why is "slash-delimited" the default fragment resolution protocol?
Dot-delimited makes more sense to me.
5. I'm concerned with calling the new property "id", as I feel people
will mistakenly expect it to behave like HTML/XML treats IDs on
elements. I propose renaming this property, or having the property be
a fragment identifier.
6. I have issue with how schemas can be either an object or string
(with the latter being a URI to a schema). This works in most cases,
but becomes a serious issue with union types. How is a validator
supposed to parse ["string", "person", "#"]? What happens if I create
a schema with a URI of "string", "object", "array", etc - then try to
reference it? Despite it's verbose nature, {"$ref":"uri"} is
unmistakable; it's even easier to read as you don't have to know what
property it belongs to to understand that is is a reference.
This is what I see at the moment. I'd appreciate it if you would you
give us at least 2 weeks to look over this.
Otherwise it's looking really good! Thanks!!
> 41KViewDownload
Gary Court
detailed in this post: http://groups.google.com/group/json-schema/browse_thread/thread/e34a52e4fe470920
I haven't seen any activity from you (Kris) in the last two weeks,
busy?
-Gary
Kris Zyp
On 9/14/2010 1:50 PM, Gary Court wrote:
> 7. I would also like you to consider versioning the schema URIs as
> detailed in this post: http://groups.google.com/group/json-schema/browse_thread/thread/e34a52e4fe470920
Yes, I agree that that is a good idea.
> I haven't seen any activity from you (Kris) in the last two weeks,
> busy?
The message before this (last night) was from me ;).
--
Thanks,
Kris
Gary Court
spec here for review before submitting it?
On Sep 14, 1:54 pm, Kris Zyp <kris...@gmail.com> wrote:
> On 9/14/2010 1:50 PM, Gary Court wrote:> 7. I would also like you to consider versioning the schema URIs as
mat
presumably this should be updated to '03'
> 41KViewDownload
Kris Zyp
that needs to be updated? Obviously if we do $ref based referencing
there would need to be updates.
Kris
--
Thanks,
Kris
Gary Court
8a. Change the "type" of the root schema in "http://json-schema.org/
draft-03/schema" to a union type of ["object", "string"], and a
"format" of "uri".
8b. Move the "id" property to the core schema, as it's now a core
feature. This now makes hyper-schema optional.
8c. Fix all the "http://json-schema.org/hyper-schema-or-uri" URIs in
"hyper-schema".
8d. Re-add the "full" link to hyper-schema, for backwards
compatibility.
Andy
I have some comments on the version 03 draft from 9/1:
1. On 4.1 (Self-Descriptive Schema):
a) As written, it is not clear whether the usage of a "profile"
parameter value that indicates the core schema is just not recommended
or not allowed. I think if it makes sense to have a core schema
defined, it should also be allowed to use it in the "profile"
parameter. So the recommendation should be about the presence of the
"profile" parameter, and its value would be required to indicate
either core schema, hyper schema, or an extension schema of the hyper
schema.
b) The concept of schemas that extend the hyper schema is mentioned
only in 4.1 and 8 as a side notice. I think the possibility to extend
the schema or hyper schema is a significant concept that deserves some
more words. For example, how would property clashes between such
extension schemas and the standard schema be avoided ? (Consider an
extension schema that defines a property named "x" and in a subsequent
version of the core schema or hyper schema a property named "x" gets
added ...)
2. On 4.1, 6.1, 8: It is not clear whether the schema identifiers are
meant to be just identifying URIs, or in addition be resolvable URLs.
The text in 6.1 and 8 uses the term "URI" and thus implies just the
identifiying use, while 4.1 first talks about the locations where the
schema documents can be found, and then defines the profile parameter
such that one can conclude it would reference these resolvable
locations.
I think it would help to define two terms:
- "schema identifier" - a URI identifying a schema
- "schema location" - a URL referencing the resolvable location of a
schema document
and then stick to these terms throughout the document. Other places
besides those mentioned above, would be all uses of "URI referring to
a schema" or The Clarify that the schema identifiers are URIs that
only identify the schema and that the resolvable locations of the
schema document are defined by the "describedby" link (if I understood
that correctly).
3. On 5.1 (type): It is not clear whether the value null is allowed
for properties of types string, number, integer, boolean, or how a
permission or prohibition for a value of null for these types could be
described. The description of the null type gives some hint to that,
allowing the suspicion that a value of null by default is not allowed,
and can be allowed by defining a type union that includes the null
type. If this interpretation is correct, I must say that I find this
approach rather unusual. Most other languages have an attribute that
defines nullability. There are already several properties that define
additional constraints on the value, why not define one more for
nullability.
4. On 5.2 (properties):
a) I think I don't understand the first sentence at all.
b) The second sentence refers to a case ("when ...") that I think is
always the case. ??
5. On 5.21 (format):
a) On the definition of additional custom formats: It is not clear
what the format property value would be in this case. I suggest that a
URI is used to *identify* the format, and the URL to a location with a
document describing it is used only in addition, e.g. via a link.
Probably that suggests that the type of the format property becomes a
union of these enum values and an object that allows to express the
identifying URI and a link to the description document. The object
would be indicated by a new value "custom" in the list.
b) Use of MIME media types: I don't think it is a good idea ot mix the
namespace of the values defined in this list, with the namespace of
MIME media types. Instead, the same approach as suggested for a) could
be used, with a value of "mime-media-type" (or so) indicating its use.
c) On utc-millisec: midnight of 1/1/1970 can be interpreted to be 24h
after 00:00 of that day. That is not likely what you wanted. I suggest
to change midnight to 00:00.
d) On regex: Clarify what regular expression flavor this indicates.
Hopefully the same as stated for the "pattern" property.
e) On color: Clarify where CSS colors are defined and add an according
reference to 9.1.
f) On style: Clarify where CSS styles are defined and add an according
reference to 9.1.
g) On phone: Clarify what E.123 is, if it is a definition of phone
formats, then add an according reference to 9.1.
h) A value for host names would be good. Probably, both short and full
host names would be allowed, to be detailed by the schema using that
format value.
i) On street-address, locality, region, postal-code: Nice try, but
probably not very useable across the world. Unless some international
verification has happened, I suggest to be careful here.
j) On country: I think instead of the country names, the country codes
defined in ISOxyz would be better. And a value for the language codes
(also in some ISO spec). I can look up the ISO spec numbers if needed.
6. On 6. (Hyper Schema):
a) The first sentence of the introductory paragraph is quite
confusing. The second sentence then really clarifies it. Can we omit
the confusing first sentence and change the second sentence to use
"core schema" where it says "JSON schema" ?
b) I find the term "hyper schema" confusing because it communicates
the notion that this would be some sort of meta schema that describes
the schema itself. How about "hypermedia extension schema" ?
7. On 6.1 (id):
a) It is not clear what relative URIs would be relative to.
b) If the "id" property value is meant to be the unique identification
of a schema, then I suggest it should be part of the core schema
definition. This is really not bound to resource relations, but a
property of the schema itself.
8. It is not clear how an object can be defined to conform to a
particular other JSON schema. I would expect that the "id" value of
that other JSON schema is somehow referenced when defining the object,
but I did not find how that would be done.
9. On 5.14 (uniqueItems): It is not clear what "unique" means in case
the array items are of type object or array. Either define that or
(probaly easier for now) restrict the use of this property to arrays
with items of a scalar type (number, string, ...).
10. On 5.15 (pattern): A reference to "ECMA 262/Perl 5" which is the
basis for the definition in this section should be added to section
9.1.
11. On 6.2.1 (Link Description Object): As written, this defines links
for use within a schema document. I think there is a need to define a
concept of links also for use by JSON instances. For that, a JSON
schema for links would need to be defined and made referencable.
12. On 6.2.1.2.1 (targetSchema): It is not clear whether the property
value is a schema identifier (as in the schema URIs) or a resolvable
location (as in the "describedby" link) or an inline schema definition
(i.e. "by value").
13. On 6.10 (alternate): Use of "JSON schemas": I guess it would help
to use "JSON schema documents" instead.
14. General: There are many usages of (lower case) "should" in the
draft that either ought to be mandatory and thus use (upper case)
"SHALL"/"MUST" as defined in RFC2119, or that are definitions rather
than provisions. This occurs in: 5.2, 5.4, 5.15, 5.18, 5.21, 5.14,
6.2, 6.2.1.1, 6.2.1.2, 6.2.1.3.3, 6.3.1, 6.5, 6.6, 6.8, 8.
15. General: There are many usages of (lower case) "may" or "must" in
the draft that ought to be (upper case) "MAY" or "SHALL"/"MUST" as
defined in RFC2119.
This is only a first shot of comments. I think there is much more to
say.
Andy
Andy
There are no provisions currently for describing that the instance
document is an object with a set of properties whose number and names
are not known at the time of the schema definition.
For example, if one wanted to transmit a UML instance specification
(an instance of a UML class that has property values) in JSON and
wanted to represent the UML instance specification as the top-level
object in JSON, that has one JSON property for each property in the
UML instance specification, with the same name asthat property, then
that is not possible today with JSON Schema.
Instead, one would have to define one JSON schema for each UML class.
Or one would have to revert to meta-model approaches like having an
array of JSON objects each of which represents a (UML) property whose
name is represented as a "name" (JSON) property. Which reduces the
simplicity JSON tries to achieve.
The same problem exists if one wanted to use JSON Schema to describe
associative arrays as described in
http://ekrantz.com/index.php/2007/06/06/json-and-associative-arrays.html,
at least in cases where the key value is not known at schema
definition time and is actually part of the "data". The UML example
above is one scenario where that is the case.
It would be great if we could come up with something in JSON Schema
that addresses this. Note, W3C XML Schema has the same limitation, but
that should not discourage us ;-)
Andy
Andy
References to schemas are now described using phrases like "schema or
a URI referencing a schema". This implies that one can have either the
schema identifier URI as a string value, or a JSON object that is a
schema definition. If one uses the schema reference, one cannot use
the "description" property anymore to describe the property that is of
the object type defined by the referenced schema.
Example, using an inline schema and a description:
{
. . .
"properties": {
"address": {
"description": "The address of ...",
"type": "object",
"properties": {
. . . # schema for an address
}
}
}
}
When referencing an address schema instead of defining the schema
inline, this becomes (according to the new referencing cabaility
defined in version 03):
{
. . .
"properties": {
"address": "http://some.org/json-schemas/address"
}
}
One might argue that the description of property "address" is now
simply part of the definition of schema "address". However, the
reality is that a part of the description applies to the type
"address", and another part of it applies to the usage of that type as
a particular property. This difference can be seen easily by adding a
second address property:
{
. . .
"properties": {
"myaddress": "http://some.org/json-schemas/address",
"myparentsaddress": "http://some.org/json-schemas/address"
}
}
It would be good to have the ability to specify a description also
when referencing a schema.
That could be done by a syntax that references a schema as a property
(maybe "id" ?) of a schema definition. Obviously, we would need to
define rules which properties in such a schema definition could be
used together.
{
. . .
"properties": {
"myaddress": {
"description": "My own address ...",
"id": "http://some.org/json-schemas/address", # reference to a
schema
}
}
}
At this point, I realized that the "extends" property basically does
that:
{
. . .
"properties": {
"myaddress": {
"description": "My own address ...",
"extends": "http://some.org/json-schemas/address", # reference
to a base schema
"properties": {
. . . # additional properties to the referenced schema (if
allowed by it)
}
}
}
}
I find it somewhat unusual to state that I extend a base schema, just
because I want to provide a description of the property that is not
even meant to be an additional description of the base type, but of
its usage.
Not sure where to go from here, I guess this requires some discussion.
Andy
Andy
In 5.24 (extends), it says "The schema MAY NOT ...".
This is likely meant to be a prohibition, when I read that sentence.
If so, it should be changed to "MUST NOT" or "SHALL NOT".
Note, RFC2119 does not define the key word "MAY NOT" at all.
Fwiw, the ISO Guidelines (the ISO alternative to RFC2119) define "may
not" with the same meaning as "may", i.e. as a permission (to do or
not to do ;-).
Andy
Kris Zyp
On 9/17/2010 10:42 AM, Andy wrote:
> [snip]
> {
> . . .
> "properties": {
> "myaddress": {
> "description": "My own address ...",
> "extends": "http://some.org/json-schemas/address", # reference
> to a base schema
> "properties": {
> . . . # additional properties to the referenced schema (if
> allowed by it)
> }
> }
> }
> }
>
> I find it somewhat unusual to state that I extend a base schema, just
> because I want to provide a description of the property that is not
> even meant to be an additional description of the base type, but of
> its usage.
Currently schema referencing URLs are allowed in union types, and it
seems we could be more permissive and allow them as direct values for a
type as well, so you could write:
{
. . .
"properties": {
"myaddress": {
"description": "My own address ...",
"type": "http://some.org/json-schemas/address", # reference
to a base schema
}
}
}
However, I believe this would have have exactly the same behavior as
using "extends", it would just be a different spelling, which makes it
seem less compelling.
--
Thanks,
Kris
Kris Zyp
> Dot-delimited makes more sense to me.
http://tech.groups.yahoo.com/group/json/message/1473?threaded=1
(I had forgot that it didn't occur in this group.)
> 5. I'm concerned with calling the new property "id", as I feel people
> will mistakenly expect it to behave like HTML/XML treats IDs on
> elements. I propose renaming this property, or having the property be
> a fragment identifier.
of precedence for "id" to refer to one's own identity.
Thanks,
Kris
Gary Court
> Do you have a suggestion for a better name? It seems there are plenty
> of precedence for "id" to refer to one's own identity.
If I were to choose one, I would say "uri". But having thought about
this, I'd like to withdraw my proposal as json-ref's "self" link has
already behaved this way for some time.
-Gary
> --
> You received this message because you are subscribed to the Google Groups "JSON Schema" group.
> To post to this group, send email to json-...@googlegroups.com.
> To unsubscribe from this group, send email to json-schema...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/json-schema?hl=en.
>
>
Kris Zyp
On Sep 17, 9:12 am, Andy <andreas.r.ma...@gmx.de> wrote:
> Kris,
> I have some comments on the version 03 draft from 9/1:
>
> 1. On 4.1 (Self-Descriptive Schema):
> a) As written, it is not clear whether the usage of a "profile"
> parameter value that indicates the core schema is just not recommended
> or not allowed. I think if it makes sense to have a core schema
> defined, it should also be allowed to use it in the "profile"
> parameter. So the recommendation should be about the presence of the
> "profile" parameter, and its value would be required to indicate
> either core schema, hyper schema, or an extension schema of the hyper
> schema.
hyper schema? The core schema exists for systems that do not have a
hyper-text capable protocol, but this section specifically refers to
situations where such a protocol is available.
> b) The concept of schemas that extend the hyper schema is mentioned
> only in 4.1 and 8 as a side notice. I think the possibility to extend
> the schema or hyper schema is a significant concept that deserves some
> more words. For example, how would property clashes between such
> extension schemas and the standard schema be avoided ? (Consider an
> extension schema that defines a property named "x" and in a subsequent
> version of the core schema or hyper schema a property named "x" gets
> added ...)
different than extending any other schema (that might change in the
future)? Also, here I suggested that clashing may be far less
hazardous than not clashing/matching ("clashing" is obviously a
negative spin on the concept):
http://www.sitepen.com/blog/2009/09/02/json-namespacing/
> 2. On 4.1, 6.1, 8: It is not clear whether the schema identifiers are
> meant to be just identifying URIs, or in addition be resolvable URLs.
> The text in 6.1 and 8 uses the term "URI" and thus implies just the
> identifiying use, while 4.1 first talks about the locations where the
> schema documents can be found, and then defines the profile parameter
> such that one can conclude it would reference these resolvable
> locations.
> I think it would help to define two terms:
> - "schema identifier" - a URI identifying a schema
> - "schema location" - a URL referencing the resolvable location of a
> schema document
> and then stick to these terms throughout the document. Other places
> besides those mentioned above, would be all uses of "URI referring to
> a schema" or The Clarify that the schema identifiers are URIs that
> only identify the schema and that the resolvable locations of the
> schema document are defined by the "describedby" link (if I understood
> that correctly).
for someone and a URN for someone else. We have been consistent of in
using URI in the schema, and have not dictated the extent of which
systems may be used on the schemas (those that can't resolve a URI
obviously aren't going to be retrieve targets).
> 3. On 5.1 (type): It is not clear whether the value null is allowed
> for properties of types string, number, integer, boolean, or how a
> permission or prohibition for a value of null for these types could be
> described. The description of the null type gives some hint to that,
> allowing the suspicion that a value of null by default is not allowed,
> and can be allowed by defining a type union that includes the null
> type. If this interpretation is correct, I must say that I find this
> approach rather unusual. Most other languages have an attribute that
> defines nullability. There are already several properties that define
> additional constraints on the value, why not define one more for
> nullability.
in the text. It is true that most languages have a concept of
nullability, but I don't think most modern CS researches would agree
that that is a feature :). Nulls tend to make less sense in data. Also
introducing a "nullable" property would violate our principles of
defaulting to false and defaults being the most permissive schema. We
would have to make it "nonNullable" (or something like that), which
seems unnecessarily confusing.
referenced schema is to be retrieved? Isn't that defined by the URL
itself?
> 9. On 5.14 (uniqueItems): It is not clear what "unique" means in case
> the array items are of type object or array. Either define that or
> (probaly easier for now) restrict the use of this property to arrays
> with items of a scalar type (number, string, ...).
>
> 10. On 5.15 (pattern): A reference to "ECMA 262/Perl 5" which is the
> basis for the definition in this section should be added to section
> 9.1.
D?
> 11. On 6.2.1 (Link Description Object): As written, this defines links
> for use within a schema document. I think there is a need to define a
> concept of links also for use by JSON instances. For that, a JSON
> schema for links would need to be defined and made referencable.
> 12. On 6.2.1.2.1 (targetSchema): It is not clear whether the property
> value is a schema identifier (as in the schema URIs) or a resolvable
> location (as in the "describedby" link) or an inline schema definition
> (i.e. "by value").
>
> 13. On 6.10 (alternate): Use of "JSON schemas": I guess it would help
> to use "JSON schema documents" instead.
>
> 14. General: There are many usages of (lower case) "should" in the
> draft that either ought to be mandatory and thus use (upper case)
> "SHALL"/"MUST" as defined in RFC2119, or that are definitions rather
> than provisions. This occurs in: 5.2, 5.4, 5.15, 5.18, 5.21, 5.14,
> 6.2, 6.2.1.1, 6.2.1.2, 6.2.1.3.3, 6.3.1, 6.5, 6.6, 6.8, 8.
>
> 15. General: There are many usages of (lower case) "may" or "must" in
> the draft that ought to be (upper case) "MAY" or "SHALL"/"MUST" as
> defined in RFC2119.
>
> This is only a first shot of comments. I think there is much more to
> say.
for the next draft.
Thank you,
Kris
Kris Zyp
On Sep 17, 9:53 am, Andy <andreas.r.ma...@gmx.de> wrote:
> Here is one more:
>
> There are no provisions currently for describing that the instance
> document is an object with a set of properties whose number and names
> are not known at the time of the schema definition.
>
> For example, if one wanted to transmit a UML instance specification
> (an instance of a UML class that has property values) in JSON and
> wanted to represent the UML instance specification as the top-level
> object in JSON, that has one JSON property for each property in the
> UML instance specification, with the same name asthat property, then
> that is not possible today with JSON Schema.
>
> Instead, one would have to define one JSON schema for each UML class.
>
> Or one would have to revert to meta-model approaches like having an
> array of JSON objects each of which represents a (UML) property whose
> name is represented as a "name" (JSON) property. Which reduces the
> simplicity JSON tries to achieve.
>
> The same problem exists if one wanted to use JSON Schema to describe
> definition time and is actually part of the "data". The UML example
> above is one scenario where that is the case.
>
> It would be great if we could come up with something in JSON Schema
> that addresses this. Note, W3C XML Schema has the same limitation, but
> that should not discourage us ;-)
described with additionalProperties?
Kris
Gary Court
key of an object. This is something I would like to see as well.
Perhaps a "pattern" like attribute for any additional properties, say:
{
"type":"object",
"additionalProperties":{},
"namePattern":"\d+"
}
Where "namePattern" (lack of a better name) must match the key of each
additional property in order to validate.
-Gary
Dean Landolt
I believe what Andy is proposing is way to place restrictions on the
key of an object. This is something I would like to see as well.
Perhaps a "pattern" like attribute for any additional properties, say:
{
"type":"object",
"additionalProperties":{},
"namePattern":"\d+"
}
Where "namePattern" (lack of a better name) must match the key of each
additional property in order to validate.
Why not make additionalProperties a schema for keys?
{
"foo": {"type": "string", "pattern": "^foo."},
additionalProperties: {"pattern": "bar|baz"}
}
It still evaluates to true for backcompat but allows further restrictions to be placed on keys.
Gary Court
> > Dot-delimited makes more sense to me.
>
> Based on the discussion here:http://tech.groups.yahoo.com/group/json/message/1473?threaded=1
> (I had forgot that it didn't occur in this group.)
assessment that slash-delimited is the better choice.
One of the points brought up by Jacob is the use of a tailing
delimiter after the hash (#) symbol. He initially states that it could
be left off for brevity, but then later replies and states that it
should be required in order to reliably distinguish between the two
formats. I completely agree that fragment resolutions should start
with the delimiter after the hash because:
1. Is the proper way to represent a child instance, where hash (#) is
the root object and the delimiter after it represents the name after
it is a property of the root object
2. Allows a parser to determine what fragment delimiter the URI is
written in
3. Allows a parser to support unique fragment identifiers. E.g, the
sub schem in {"properties":{"a":{"id":"#foo"}}} could be referenced
using the URIs "#/properties/a" or "#foo".
Because of this, we should update the fragment resolution example in
the specification to include the initial delimiter:
fragment identifier resolution
------------------- ----------
# self, the root of the resource itself
#.foo the object referred to by the foo property
#.foo.another prop the object referred to by the "another
prop"
property of the object referred to by the
"foo" property
#.foo.another prop.baz the string referred to by the value of
"baz"
property of the "another prop" property of
the object referred to by the "foo" property
#.foo.anArray.0 the first object in the "anArray" array
Thanks!
-Gary
Kris Zyp
Great points, that definitely makes sense for slash-delimited. But
aren't we just including dot-delimited because it already exists? If we
introduce dot-delimited starting with a dot, than there are three
formats, dot delimited, dot delimited starting with a dot, and slash
delimited (starting with a slash). That doesn't seem helpful.
I think I will update the spec to do the examples using slash-delimited
(starting with a slash) to encourage use of that format.
--
Thanks,
Kris
Gary Court
To clarify about dot-delimited: what I'm saying is that dot-delimited
seems currently broken. It makes sense to have sub referencing with
fragment resolution start with a dot. I'll elaborate with an example:
Assume we have a JSON document, with URI "doc". The root element of
the document would have a URI of "doc#".
In JavaScript, if I had a variable to this document, it might look
like:
var doc = {...};
Thus, the JS variable "doc" is equivalent to the URI "doc#".
If I wanted to access a property of the doc object, I would use (in
JS):
doc.subproperty
Therefore, when referencing by URI, it would make sense to reference
the subproperty with "doc#.subproperty".
-Gary
Kris Zyp
On 9/22/2010 11:21 PM, Gary Court wrote:
> Great to hear!
>
> To clarify about dot-delimited: what I'm saying is that dot-delimited
> seems currently broken. It makes sense to have sub referencing with
> fragment resolution start with a dot. I'll elaborate with an example:
>
> Assume we have a JSON document, with URI "doc". The root element of
> the document would have a URI of "doc#".
> In JavaScript, if I had a variable to this document, it might look
> like:
> var doc = {...};
> Thus, the JS variable "doc" is equivalent to the URI "doc#".
> If I wanted to access a property of the doc object, I would use (in
> JS):
> doc.subproperty
> Therefore, when referencing by URI, it would make sense to reference
> the subproperty with "doc#.subproperty".
I understand why dot-delimited is broken, but if we agree that
slash-delimited is superior, why aren't we just pointing people to
slash-delimited? What is the point of creating another version of
dot-delimited, if we don't want them to use it anyway? The only reason
that dot-delimited is included in the spec is because (I think) it is
currently being used. If it is there just to acknowledge existing
practice, is pointless to change the behavior of dot-delimited to
something that no longer matches reality. We would need to create a
third resolution strategy which doesn't seem helpful.
--
Thanks,
Kris
Gary Court
that. I'm just saying that while we are in this section, why not fix
dot-delimited as well? Or, have the specification (under
dot-delimitation only) state that both forms should be acceptable, so
as not to break backwards compatibility. It's not a big deal, just a
nice to have on my part.
-Gary
Kris Zyp
On 9/23/2010 1:24 PM, Gary Court wrote:
> We *should* be pointing people to slash-delimited, I'm not refuting
> that. I'm just saying that while we are in this section, why not fix
> dot-delimited as well? Or, have the specification (under
> dot-delimitation only) state that both forms should be acceptable, so
> as not to break backwards compatibility.
That sounds fine, we can do that.
--
Thanks,
Kris
Greg Olszewski
Thanks for taking the time to prepare another version! It looks good,
but I have a few concerns.
First a nit. The hyper-schema isn't valid JSON. There's an illegal
trailing comma in this bit:
"requires" : {
"type" : ["string", "http://json-schema.org/hyper-schema-or-uri"],
},
A larger concern for me are the changes to the semantics of "minimum"
and "maximum" as well as the change that properties are now optional
unless stated (in version two they were required unless stated). I
don't understand the reasoning for the changes, so this seems less
than ideal, but, as long as the schema uri includes a version, it's
workable.
If you expect further changes of this kind, consider adding either a
"version" key, or making "extends" a required attribute, so that the
various formats can be distinguished reliably.
In my opinion, it'd be preferable to leave the semantics the same as
the previous draft, since the change makes extra work. One example of
the extra work is that all of the examples in the spec need updating
from version 2 to version 3 semantics. There's several instances of
"optional" : true, which is now the default, and confusing (since
"optional" isn't defined in this draft). Also, for the examples to
retain their meaning from the previous draft, they'll need to be
updated with "required" : "true" for every key which doesn't have
"optional" : "true" removed from it.
I'm going to go implement "#" support in my validation code and try to
get it validating the new "schema schema".
Thanks again!
Regards,
Greg
Gary Court
> unless stated (in version two they were required unless stated). I
> don't understand the reasoning for the changes
"optional" schema attribute` thread here:
http://groups.google.com/group/json-schema/browse_thread/thread/b193f4b349c075c9
Kris Zyp
On 9/26/2010 2:12 PM, Greg Olszewski wrote:
> Hi Kris,
>
> Thanks for taking the time to prepare another version! It looks good,
> but I have a few concerns.
>
> First a nit. The hyper-schema isn't valid JSON. There's an illegal
> trailing comma in this bit:
>
>
> "requires" : {
>
> "type" : ["string", "http://json-schema.org/hyper-schema-or-uri"],
>
> },
>
>
> A larger concern for me are the changes to the semantics of "minimum"
> and "maximum" as well as the change that properties are now optional
> unless stated (in version two they were required unless stated).
It seems like if we expect JSON Schema to continue to grow in usage that
it would be better to correct and improve the design now rather than
waiting until later or leaving it with a sub-optimal design.
> I
> don't understand the reasoning for the changes, so this seems less
> than ideal, but, as long as the schema uri includes a version, it's
> workable.
>
> If you expect further changes of this kind, consider adding either a
> "version" key, or making "extends" a required attribute, so that the
> various formats can be distinguished reliably.
Does this provide a significant reliability advantage over versioned
schema URIs? I'd prefer to not have to introduce another property if
versioning can be handled by existing mechanisms.
--
Thanks,
Kris
Gary Court
are resolved against. The two logical choices would be the instance or
the defining schema. To me it would seem that it should be relative to
the instance's URI.
Sky Sanders
validator will be provided?
I much prefer the direction that V3 is going vs V2 and need to make an
implementation decision fairly soon.
Thanks,
Sky
On Sep 28, 10:58 pm, Gary Court <gary.co...@gmail.com> wrote:
> The specification does not state what object relative "pathStart" URIs
> are resolved against. The two logical choices would be the instance or
> the defining schema. To me it would seem that it should be relative to
> the instance's URI.
>
> On Sep 1, 1:18 pm, Kris Zyp <kris...@gmail.com> wrote:
>
>
>
>
>
>
>
Gary Court
that we are getting close, but there are a couple outstanding issues
left to discuss. And the bigger job of getting the spec and schema/
examples flushed out and reviewed for correctness. If I were to take a
guess, I'd say this could likely be accomplished within a month.
From a validator standpoint, I know that JSV could be updated to
support draft 3 within a couple of days.
I too am excited for V3. But all great works of art require
patience :-)
-Gary
Kris Zyp
On 10/4/2010 1:21 PM, Gary Court wrote:
> I can only speak for myself, but my feeling on the specification is
> that we are getting close, but there are a couple outstanding issues
> left to discuss. And the bigger job of getting the spec and schema/
> examples flushed out and reviewed for correctness. If I were to take a
> guess, I'd say this could likely be accomplished within a month.
What do you see as the key outstanding issues?
I think that it may be worth considering the "release early, release
often" iterative approach, and try to submit a version 3 soon and defer
more review and corrections to draft 4. I think version 3 is better than
version 2 at this point. The biggest concern about releasing a version 3
prematurely would be introducing any new problems by our changes. There
may be some valid concerns with verifying the new changes in version 3,
which may indeed need some more review. Just wanted to make sure we know
what needs to get done.
--
Thanks,
Kris
Sky Sanders
commonly serialized to json
unix-time : http://en.wikipedia.org/wiki/Unix_time
guid : http://en.wikipedia.org/wiki/Globally_unique_identifier
Gary Court
1. A new attribute that allows restrictions to be placed on property
names of objects
2. Abandoning schemas-can-be-uris VS changing "requires" to two
attributes
3. Specification and schemas need to be updated to use versioned URIs
I'll address the first item in a new thread shortly.
I think the second item needs more input from other people then just
me and Kris.
The third item is a todo that could be done this week.
-Gary
Kris Zyp
On 10/4/2010 8:35 PM, Greg Olszewski wrote:
> Hi,
>
>>> If you expect further changes of this kind, consider adding either a
>>> "version" key, or making "extends" a required attribute, so that the
>>> various formats can be distinguished reliably.
>> Does this provide a significant reliability advantage over versioned
>> schema URIs? I'd prefer to not have to introduce another property if
>> versioning can be handled by existing mechanisms.
>>
> Versioned schema URIs solve half of the problem that's concerning me.
> They provide a mechanism to distinguish different versions of the
> json-schema definition. They don't, by themselves, offer a
> mechanism to recognize what version of the json-schema definition
> a particular schema adheres to.
>
> I see that there's a mechanism to reference these versioned URIs when
> json-schema is used in a protocol which provides media type definitions.
> Outside of that context, I don't see a mechanism to reference the URIs
> defined.
>
> Identification could be more reliable if a mechanism to reference the URIs
> existed within the schema itself. It would be more reliable if the draft
> RFC said that when json-schema is used outside of a protocol providing
> media type definitions, this mechanism SHOULD be used.
>
> Identification is reliable if json-schema has a mechanism to reference
> the versioned schema schema URIs, and the draft RFC says it MUST
> be used when an external mechanism isn't.
>
> I'm not certain whether the reliability that offering a mechanism would
> provide is a significant advantage. It certainly would allow less work in
> some cases. Whether that is a significant advantage likely depends
> on how often incompatible changes are made to the definition.
Would it help to disambiguate versions if we had an empty "base" schema
for each version of the spec? So you could do:
{
"name":"some schema",
"extends":"http://json-schema.org/v3/base",
"properties":{
...
The base would also be an empty schema (doesn't add any constraints),
but validators could use it as an indication of the schema version.
Or we could reintroduce the "$schema" attribute (maybe without the $),
as way to refer to the meta-schema (that indicates the schema version).
--
Thanks,
Kris
Gary Court
link. In fact, JSV already uses this for switching between schemas to
validate with.
Chris Miles
On 05/10/10 06:47, Gary Court wrote:
> I'd like to see "$schema" be used as draft 2 already defines this
> link. In fact, JSV already uses this for switching between schemas to
> validate with.
>
>
I've thought that should be the case - i.e. data presented could include
a $schema including $schema properties on embedded objects but I've not
been able to make it work. Could you give an example?
{
"$schema":"http://base.com/s1",
"data":[
{
"$schema":"http://base.com/one-sort",
"one-sort-data":vvv ...
},
{
"$schema":"http://base.com/another-sort",
"another-sort-data":vvv ...
}
]
}
Could I register with JSV schemas s1, one-sort, another-sort and then
JSV.validate this data?
What would the s1 schema look like, would it have to refer to one-sort
and another-sort or could $schema handle that when "data":{"type":"array"}?
Chris
Greg Olszewski
>> If you expect further changes of this kind, consider adding either a
>> "version" key, or making "extends" a required attribute, so that the
>> various formats can be distinguished reliably.
>
> Does this provide a significant reliability advantage over versioned
> schema URIs? I'd prefer to not have to introduce another property if
> versioning can be handled by existing mechanisms.
>
Versioned schema URIs solve half of the problem that's concerning me.
They provide a mechanism to distinguish different versions of the
json-schema definition. They don't, by themselves, offer a
mechanism to recognize what version of the json-schema definition
a particular schema adheres to.
I see that there's a mechanism to reference these versioned URIs when
json-schema is used in a protocol which provides media type definitions.
Outside of that context, I don't see a mechanism to reference the URIs
defined.
Identification could be more reliable if a mechanism to reference the URIs
existed within the schema itself. It would be more reliable if the draft
RFC said that when json-schema is used outside of a protocol providing
media type definitions, this mechanism SHOULD be used.
Identification is reliable if json-schema has a mechanism to reference
the versioned schema schema URIs, and the draft RFC says it MUST
be used when an external mechanism isn't.
I'm not certain whether the reliability that offering a mechanism would
provide is a significant advantage. It certainly would allow less work in
some cases. Whether that is a significant advantage likely depends
on how often incompatible changes are made to the definition.
Hoping this makes things clearer,
Greg
Gary Court
data you are validating. I'm still looking into the feasibility of
reacting to links in the instance data.
Chris Miles
I can see that I can refer from one schema to another using
{"$ref":"another-schema"} but when I register the other schema to JSV I
don't think JSV is reading the $schema. At present I'm doing my own
registration to make things work. Should I not be able to register:
{
"$schema":"http://json-schema.org/hyper-schema#",
"id":"http://somewhere.com/another-schema#",
"type":"object",
etc
}
by passing it to JSV.registerSchema, i.e. could not registerSchema work
out what the URI is for the supplied schema?
Greg Olszewski
> I'd like to see "$schema" be used as draft 2 already defines this
> link. In fact, JSV already uses this for switching between schemas to
> validate with.
>
Sounds good. A pointer in the RFC to that part of the hyper-schema would have
helped me find this on my own.
Greg
Greg Olszewski
> link. In fact, JSV already uses this for switching between schemas to
> validate with.
>
Replying again, pardon please.
I made orderly output "$schema" properties. Here's an example:
http://trap.mtview.ca.us/~noop/with_dollar_schema.txt
Did I do this in a way such that JSV will recognize that's the schema
is adhereing to RFC draft 2 ?
Thanks,
Greg
Kris Zyp
On 10/4/2010 5:24 PM, Gary Court wrote:
> The issues I have on my list are:
>
> 1. A new attribute that allows restrictions to be placed on property
> names of objects
> 2. Abandoning schemas-can-be-uris VS changing "requires" to two
> attributes
Just to give a defense of my position on this... My hope with JSON
Schema is that it would be as easy as possible for authors in the most
common cases (and that more sophisticated cases be possible). From what
I have seen with schema usage, linking schemas is used far more than the
multiple forms of "requires". Consequently, I think it is much higher
priority that linking be as simple as possible, and removing the need to
embed target URLs in {"$ref":"..."} obviously simplifies the structure
of schemas that are doing linking. If the consequence of this highly
used feature means splitting "requires" into two attributes (or removing
one of the forms), which is arguably not even more complicated (having
two different forms in a single attribute might actually be more
confusing than having distinct attributes for some people) seems well
worth it.
Using the URIs as links fits much better with the hyper-schema driven
approach as well. JSON referencing was developed as a format to achieve
linking, but is really anachronistic next to the more flexible and
succinct linking available with hyper-schemas. While we have made a way
for JSON referencing to be described with hyper-schemas, it is
definitely not the most elegant use of a hyper schema.
--
Thanks,
Kris
Monica Keller
it be possible for you to put the latest with Gary's changes on the
website ?
Also could we mark on the spec which sections are normative and which
are not. Generally examples are not. I really like your use of them
but if there are conflicts the specification directives need to win.
You can set up post commit hooks on github which convert the xml to
html or use the xslt
Gary Court
recognize that referencing other schemas is quite common when writing
schemas. Here are my thoughts on the situation:
A. Up until this point, there has been no understanding of URIs or
links in the core schema. All linking and resolving of URI has been
left to definitions in the Hyper Schema. A simple validator that only
validated with the core JSON Schema has never had to keep track of
what instance had what URI, and never had to do a lookup to resolve a
link/reference. By moving referencing into the core JSON Schema, now
simple validators MUST keep track of the URI of instances, and do URI
resolving. This now complicates simple validators, and also starts to
blur the lines between core and hyper.
B. The other aspect is that a schema can be either and object of
attributes or a string of a reference: Objects are must easier to
classify then strings are. The context of an object can be determined
by its properties, and the content of those properties. A string,
however, is much harder to determine it's context programatically as
URIs can look very similar to any other random string.
So... what I am getting at with this is that if a reference is an
object (like {$ref}), it's much easier for a validator to recognize
that compared to any other object; unlike a string which could be a
URI, could be something else that looks like a URI. This comes into
play with attribute type collisions (for example, "type" or
"requires"), when a string now has multiple meanings.
C. Finally, my thoughts on "requires": I'd actually like to see this
attribute removed and replaced with something that is more referencing
friendly. What I mean (and I've stated this in other threads) is that
"requires" is the only attribute that applies restrictions to the
parent/containing instance of the instance. When another schema tries
to reference a schema that has this attribute, it then applies that
restriction to itself (the parent schema/instance) which is probably
not the behavior intended by the referenced schema's author. I believe
that JSON Schema should avoid applying restrictions to parent
instances as much as enforcing that the default value is false. My
solution to this would be to move the "requires" attribute behavior
into the parent schema. This would also eliminate the need to have
this attribute accept a schema. This is how I would envision this
attribute to look like:
{
"properties" : {
"city" : {},
"state" : {},
"country" : {}
},
"dependencies" : {
"city" : ["state", "country"],
"state" : "country"
}
}
Anyways, let me know what your thoughts are on my above thoughts. Thanks!
-Gary
Kris Zyp
On 10/12/2010 12:11 PM, Gary Court wrote:
> I understand your reasoning, and that is a fair assessment. I too
> recognize that referencing other schemas is quite common when writing
> schemas. Here are my thoughts on the situation:
>
> A. Up until this point, there has been no understanding of URIs or
> links in the core schema. All linking and resolving of URI has been
> left to definitions in the Hyper Schema. A simple validator that only
> validated with the core JSON Schema has never had to keep track of
> what instance had what URI, and never had to do a lookup to resolve a
> link/reference. By moving referencing into the core JSON Schema, now
> simple validators MUST keep track of the URI of instances, and do URI
> resolving. This now complicates simple validators, and also starts to
> blur the lines between core and hyper.
>
If we considered JSON referencing to be applicable to core schemas (as
the core meta-schema suggests), than a referencing aware schema
validator has always had to do reference resolution.
However, it is desirable to separate this out from the core schema, and
to the degree that we can at least separate the core schema definition
from the resolution semantics of hyper schema, we should be able to do
the same with schemas as strings. We could word the spec such that hyper
schema is defined as allowing a string-URL as an alternate to an object
(rather than stating this in each property), thereby making that all
core schema properties that accept schemas, also accept strings in the
context of hyper schema.
> B. The other aspect is that a schema can be either and object of
> attributes or a string of a reference: Objects are must easier to
> classify then strings are. The context of an object can be determined
> by its properties, and the content of those properties. A string,
> however, is much harder to determine it's context programatically as
> URIs can look very similar to any other random string.
> So... what I am getting at with this is that if a reference is an
> object (like {$ref}), it's much easier for a validator to recognize
> that compared to any other object; unlike a string which could be a
> URI, could be something else that looks like a URI. This comes into
> play with attribute type collisions (for example, "type" or
> "requires"), when a string now has multiple meanings.
I do acknowledge that these semantics demand a more involved bootstrap
process (although presumably all the tools that are needed for the
bootstrapping should be available if the implementation supports hyper
schemas). But of course again I appeal to the expectation that there
should be vastly more schema authors than validator authors, and this
design is clearly biased towards the schema authors.
> C. Finally, my thoughts on "requires": I'd actually like to see this
> attribute removed and replaced with something that is more referencing
> friendly. What I mean (and I've stated this in other threads) is that
> "requires" is the only attribute that applies restrictions to the
> parent/containing instance of the instance. When another schema tries
> to reference a schema that has this attribute, it then applies that
> restriction to itself (the parent schema/instance) which is probably
> not the behavior intended by the referenced schema's author. I believe
> that JSON Schema should avoid applying restrictions to parent
> instances as much as enforcing that the default value is false. My
> solution to this would be to move the "requires" attribute behavior
> into the parent schema. This would also eliminate the need to have
> this attribute accept a schema. This is how I would envision this
> attribute to look like:
>
> {
> "properties" : {
> "city" : {},
> "state" : {},
> "country" : {}
> },
> "dependencies" : {
> "city" : ["state", "country"],
> "state" : "country"
> }
> }
That sounds like a good improvement to me. However, how does this
eliminate the need for referencing schemas? Would property values still
accept schemas (like if you wanted to say that the presence of a
"state" property required that the country be "US" or "Canada")?
--
Thanks,
Kris
Gary Court
> the core meta-schema suggests), than a referencing aware schema
> validator has always had to do reference resolution.
>
> However, it is desirable to separate this out from the core schema, and
> to the degree that we can at least separate the core schema definition
> from the resolution semantics of hyper schema, we should be able to do
> the same with schemas as strings. We could word the spec such that hyper
> schema is defined as allowing a string-URL as an alternate to an object
> (rather than stating this in each property), thereby making that all
> core schema properties that accept schemas, also accept strings in the
> context of hyper schema.
It's true that you can't bootstrap the core schema without hyper
schema. But in most implementations the references can be added in via
language and validator specific means.
I started looking at this issue another way and I've changed my mind
about point A: what if we have simple validators as validators that
implement the core schema and full validators also implement hyper
schema. Then, referencing schemas should be apart of the core schema
as it's a feature that is used quite commonly (as you've stated). I
can get behind that.
So then, the argument about this subject is less about "should it be
in the next spec", but rather "what format referencing should take". I
pose this question: Is {"$ref" : "someURI"} that much harder to write
then "someURI"? In my opinion, the former is easier for a person to
read and understand that it is a reference. From a validator
standpoint, the process of transforming either format to a schema is
relatively the same amount of processing (assuming the validator is
using a simple link resolution).
Also, by moving to a string only format, we potentially limit the
ability to specify additional metadata with our reference. With an
object you can always add additional properties. Meaning, we still
need to support referencing with links (via hyper-schema); which now
means we have two ways of referencing other schemas. And I don't think
we should be duplicating functionality.
> That sounds like a good improvement to me. However, how does this
> eliminate the need for referencing schemas? Would property values still
> accept schemas (like if you wanted to say that the presence of a
> "state" property required that the country be "US" or "Canada")?
This can still be accomplished with union types:
{
"type" : [
{
"properties" : {
"state" : {},
"country" : { "enum" : ["US", "Canada"] }
},
"dependencies" : {
"state" : "country"
}
},
{
"properties" : {
"state" : { "disallow" : "any" }
}
}
]
}
This does make it more lengthy, but avoids us from having string type
collisions with property name and schema URI....
Actually, I just realized that if you had multiple relationships, your
union types would grow exponentially. That would be bad.
Perhaps this new attribute should only accept schemas? Or maybe simply
naming properties must be wrapped in an array.
A schema dependency example would then look like:
{
"properties" : {
"state" : {},
"country" : {}
},
"dependencies" : {
"state" : {
"properties" : {
"country" : { "enum" : ["US", "Canada"], "required" : true }
}
}
}
}
While a simple dependency would look like:
{
"properties" : {
"state" : {},
"country" : {}
},
"dependencies" : {
"state" : ["country"]
}
}
FYI, Canada has provinces, not states :-) But I understand for the
sake of example.
Kris Zyp
schema.
> In my opinion, the former is easier for a person to
> read and understand that it is a reference. From a validator
> standpoint, the process of transforming either format to a schema is
> relatively the same amount of processing (assuming the validator is
> using a simple link resolution).
>
> Also, by moving to a string only format, we potentially limit the
> ability to specify additional metadata with our reference. With an
> object you can always add additional properties.
references (meta-schema's could override the "self" definition from
schema/links/0).
> Meaning, we still
> need to support referencing with links (via hyper-schema); which now
> means we have two ways of referencing other schemas. And I don't think
> we should be duplicating functionality.
calling the string-value-as-a-self-reference as a different than other
forms of links?
Kris
Gary Court
> calling the string-value-as-a-self-reference as a different than other
> forms of links?
What I am referring to is that if we implement schemas-can-be-uris,
there are then two ways of referencing a schema:
"uri://to/schema"
...and...
{"$ref" : "uri://to/schema"}
And if a validator only implemented the core schema specification, it
would only accept the first method. Meaning schemas written using the
second method would be unusable in that validator. If the only way to
reference was the second method, then it doesn't matter if the
validator supported hyper-schema or not for referencing to work.
Although it is extra characters, the second method is forward
compatible with Hyper schema, backwards compatible with older drafts,
doesn't type collide with other property values, and is easier to
visually identify from other strings that it is a reference.
-Gary
Kris Zyp
On Oct 27, 6:45 pm, Gary Court <gary.co...@gmail.com> wrote:
> > This is referencing by links, what other forms are there? Are you
> > calling the string-value-as-a-self-reference as a different than other
> > forms of links?
>
> What I am referring to is that if we implement schemas-can-be-uris,
> there are then two ways of referencing a schema:
>
> "uri://to/schema"
> ...and...
> {"$ref" : "uri://to/schema"}
>
> And if a validator only implemented the core schema specification, it
> would only accept the first method. Meaning schemas written using the
> second method would be unusable in that validator. If the only way to
> reference was the second method, then it doesn't matter if the
> validator supported hyper-schema or not for referencing to work.
having a separate hyper-schema driven link resolution seems like we
have two referencing mechanisms, which seems undesirable. The point of
having a separate core schema is that it can be implemented in the
absence of location resolution mechanisms. Having to support $ref
referencing in the core schema would defeat the purpose.
>
> Although it is extra characters, the second method is forward
> compatible with Hyper schema, backwards compatible with older drafts,
> doesn't type collide with other property values, and is easier to
> visually identify from other strings that it is a reference.
compatibility with schemas from older drafts. In terms of readability,
the extra characters may help if all you are doing is looking for
references, but it terms of overall readability, the direct URLs are
seems far cleaner and more readable to me.
Kris
Gary Court
>
>
> On Oct 27, 6:45 pm, Gary Court <gary.co...@gmail.com> wrote:
>> > This is referencing by links, what other forms are there? Are you
>> > calling the string-value-as-a-self-reference as a different than other
>> > forms of links?
>>
>> What I am referring to is that if we implement schemas-can-be-uris,
>> there are then two ways of referencing a schema:
>>
>> "uri://to/schema"
>> ...and...
>> {"$ref" : "uri://to/schema"}
>>
>> And if a validator only implemented the core schema specification, it
>> would only accept the first method. Meaning schemas written using the
>> second method would be unusable in that validator. If the only way to
>> reference was the second method, then it doesn't matter if the
>> validator supported hyper-schema or not for referencing to work.
>
> Having a special $ref-based referencing (for core schema), and then
> having a separate hyper-schema driven link resolution seems like we
> have two referencing mechanisms, which seems undesirable. The point of
> having a separate core schema is that it can be implemented in the
> absence of location resolution mechanisms. Having to support $ref
> referencing in the core schema would defeat the purpose.
Obviously I agree that we should only have one method of referencing.
Are you proposing that we remove "full" links from hyper-schema in
favor of schemas-can-be-uri referencing?
>>
>> Although it is extra characters, the second method is forward
>> compatible with Hyper schema, backwards compatible with older drafts,
>> doesn't type collide with other property values, and is easier to
>> visually identify from other strings that it is a reference.
>
> It is not difficult for schema validators to maintain backwards
> compatibility with schemas from older drafts. In terms of readability,
> the extra characters may help if all you are doing is looking for
> references, but it terms of overall readability, the direct URLs are
> seems far cleaner and more readable to me.
I just think we should use objects for referencing to prevent type
collisions, and to keep referencing consistent across the various
drafts.
-Gary
Andi
1) To make it clear: Is it really only for JSON data? I mainly
validate data that is already inside my JS engine, and validators are
implemented in other languages. I am not going to validate JSON
(strings) but data that is directly available.
My data can be incompatible with JSON because of
a) referencing (not explicit by refs but inside my language
implementation)
b) ambiguous mappings between JSON's and other languages' data types.
2) I18n
Make it possible to define text ("title", "description") both as
strings and as objects, where the names define the language tag and
the strings are a localized version.
3) "type"
I don't understand that I can use several schemas (in addition to the
strings). "type" is already a property of a schema, so why should
point type itself to a schema?
To allow several schemas, it would be much clearer to use an array of
schemas as schema, like:
...
properties: {
a: [{
// schema 1
}, {
// schema 2
}]
}
...
Isn't this more consequent?
4) "uniqueItems": Why shouldn't complex values be compared?
5) "maxDecimal" - Make clear that this can be negative as well.
6) "id" - Define a pattern that excludes "." and "#" (and other
characters?)
7) Why is "default" only used in hyper schema? I usually need it in
any case.
X) Errors
- In 3) I still see "optional", but it is replaced by "required"
- Take a look at 5) in the draft. You defined a property "maximum:
125" there.
On 14 Sep., 20:54, Kris Zyp <kris...@gmail.com> wrote:
> On 9/14/2010 1:50 PM, Gary Court wrote:> 7. I would also like you to consider versioning the schema URIs as
> > detailed in this post:http://groups.google.com/group/json-schema/browse_thread/thread/e34a5...
>
> Yes, I agree that that is a good idea.
>
> > I haven't seen any activity from you (Kris) in the last two weeks,
> > busy?
>
> The message before this (last night) was from me ;).
>
> --
> Thanks,
> Kris
Andi
change.
On 26 Sep., 21:12, Greg Olszewski <g...@fantoccini.com> wrote:
> Hi Kris,
>
> Thanks for taking the time to prepare another version! It looks good,
> but I have a few concerns.
>
> First a nit. The hyper-schema isn't valid JSON. There's an illegal
> trailing comma in this bit:
>
> "requires" : {
>
> "type" : ["string", "http://json-schema.org/hyper-schema-or-uri"],
>
> },
>
> A larger concern for me are the changes to the semantics of "minimum"
> and "maximum" as well as the change that properties are now optional
> than ideal, but, as long as the schema uri includes a version, it's
> workable.
>
> "version" key, or making "extends" a required attribute, so that the
> various formats can be distinguished reliably.
>
> the previous draft, since the change makes extra work. One example of
> the extra work is that all of the examples in the spec need updating
> from version 2 to version 3 semantics. There's several instances of
> "optional" : true, which is now the default, and confusing (since
> "optional" isn't defined in this draft). Also, for the examples to
> retain their meaning from the previous draft, they'll need to be
> updated with "required" : "true" for every key which doesn't have
> "optional" : "true" removed from it.
>
> I'm going to go implement "#" support in my validation code and try to
> get it validating the new "schema schema".
>
> Thanks again!
>
> Regards,
> Greg
Gary Court
> My review is based on http://github.com/kriszyp/json-schema
>
> 1) To make it clear: Is it really only for JSON data? I mainly
> validate data that is already inside my JS engine, and validators are
> implemented in other languages. I am not going to validate JSON
> (strings) but data that is directly available.
> My data can be incompatible with JSON because of
> a) referencing (not explicit by refs but inside my language
> implementation)
> b) ambiguous mappings between JSON's and other languages' data types.
JSON Schema is for validating JSON only. Validating datatypes that are
outside of the JSON specification are beyond the goals of this
specification.
> 2) I18n
> Make it possible to define text ("title", "description") both as
> strings and as objects, where the names define the language tag and
> the strings are a localized version.
This is an interesting topic as we've mostly avoided i18n talk in the
specification. I think we should create a new thread on this topic.
Technically it's currently possible to do i18n in JSON Schema by using
an after-process translate lookup of the value of
"title"/"description" attributes.
> 3) "type"
> I don't understand that I can use several schemas (in addition to the
> strings). "type" is already a property of a schema, so why should
> point type itself to a schema?
> To allow several schemas, it would be much clearer to use an array of
> schemas as schema, like:
>
> ...
> properties: {
>
> a: [{
> // schema 1
> }, {
> // schema 2
> }]
> }
> ...
>
> Isn't this more consequent?
If we were to implement union types in this manner, then JSON Schema's
could be objects, arrays, or strings. This would cause further type
collisions with other attribute values (like "items").
> 4) "uniqueItems": Why shouldn't complex values be compared?
My guess is that this was originally defined this way because in
JavaScript {} !== {}, or [] !== []. And is very computationally
expensive to deep compare objects/arrays. However, there really isn't
any technical reason with this should be in there, and could be
removed.
> 5) "maxDecimal" - Make clear that this can be negative as well.
Actually, this attribute should be replaced as it unfairly assumes the
number is in base 10.
> 6) "id" - Define a pattern that excludes "." and "#" (and other
> characters?)
Yes, the "id" attribute should be defined in the core schema JSON, but
with a "format" of "uri" rather then a pattern.
> 7) Why is "default" only used in hyper schema? I usually need it in
> any case.
I too have been wondering why this was moved. Perhaps Kris can explain
this decision.
-Gary
Andi
On 3 Nov., 00:03, Gary Court <gary.co...@gmail.com> wrote:
> On Tue, Nov 2, 2010 at 2:59 PM, Andi <andreaskal...@gmx.de> wrote:
> > My review is based onhttp://github.com/kriszyp/json-schema
> > 1) To make it clear: Is it really only for JSON data? I mainly
> > validate data that is already inside my JS engine, and validators are
> > implemented in other languages. I am not going to validate JSON
> > (strings) but data that is directly available.
> > My data can be incompatible with JSON because of
> > a) referencing (not explicit by refs but inside my language
> > implementation)
> > b) ambiguous mappings between JSON's and other languages' data types.
>
> JSON Schema is for validating JSON only. Validating datatypes that are
> outside of the JSON specification are beyond the goals of this
> specification.
languages in terms of establish JSON Schema's vocabulary as a
standard. Is there a list of all known implementations?
> > 2) I18n
> > Make it possible to define text ("title", "description") both as
> > strings and as objects, where the names define the language tag and
> > the strings are a localized version.
>
> This is an interesting topic as we've mostly avoided i18n talk in the
> specification. I think we should create a new thread on this topic.
>
> Technically it's currently possible to do i18n in JSON Schema by using
> an after-process translate lookup of the value of
> "title"/"description" attributes.
case for having it in one place.
>
>
>
>
>
>
>
>
> > 3) "type"
> > I don't understand that I can use several schemas (in addition to the
> > strings). "type" is already a property of a schema, so why should
> > point type itself to a schema?
> > To allow several schemas, it would be much clearer to use an array of
> > schemas as schema, like:
>
> > ...
> > properties: {
>
> > a: [{
> > // schema 1
> > }, {
> > // schema 2
> > }]
> > }
> > ...
>
> > Isn't this more consequent?
>
> If we were to implement union types in this manner, then JSON Schema's
> could be objects, arrays, or strings. This would cause further type
> collisions with other attribute values (like "items").
evaluated, for example:
{
type:['string', {type: 'integer', minimum:5}],
minLength:1
}
This is not very clear.
> > 4) "uniqueItems": Why shouldn't complex values be compared?
>
> My guess is that this was originally defined this way because in
> JavaScript {} !== {}, or [] !== []. And is very computationally
> expensive to deep compare objects/arrays. However, there really isn't
> any technical reason with this should be in there, and could be
> removed.
> > 5) "maxDecimal" - Make clear that this can be negative as well.
>
> Actually, this attribute should be replaced as it unfairly assumes the
> number is in base 10.
powerful.
> > 6) "id" - Define a pattern that excludes "." and "#" (and other
> > characters?)
>
> Yes, the "id" attribute should be defined in the core schema JSON, but
> with a "format" of "uri" rather then a pattern.
> > 7) Why is "default" only used in hyper schema? I usually need it in
> > any case.
>
> I too have been wondering why this was moved. Perhaps Kris can explain
> this decision.
instance. It's really useful.
>
> -Gary
Kris Zyp
On 11/3/2010 5:14 AM, Andi wrote:
>
> On 3 Nov., 00:03, Gary Court <gary.co...@gmail.com> wrote:
>> On Tue, Nov 2, 2010 at 2:59 PM, Andi <andreaskal...@gmx.de> wrote:
>>> My review is based onhttp://github.com/kriszyp/json-schema
>>> 1) To make it clear: Is it really only for JSON data? I mainly
>>> validate data that is already inside my JS engine, and validators are
>>> implemented in other languages. I am not going to validate JSON
>>> (strings) but data that is directly available.
>>> My data can be incompatible with JSON because of
>>> a) referencing (not explicit by refs but inside my language
>>> implementation)
>>> b) ambiguous mappings between JSON's and other languages' data types.
>> JSON Schema is for validating JSON only. Validating datatypes that are
>> outside of the JSON specification are beyond the goals of this
>> specification.
> OK, on the other hand we must not ignore implementations in other
> languages in terms of establish JSON Schema's vocabulary as a
> standard. Is there a list of all known implementations?
There was one on the google groups site, but I realize that they plan to
take that down, so I put up an updated list here:
http://www.json-schema.org/implementations.html
>>> 2) I18n
>>> Make it possible to define text ("title", "description") both as
>>> strings and as objects, where the names define the language tag and
>>> the strings are a localized version.
>> This is an interesting topic as we've mostly avoided i18n talk in the
>> specification. I think we should create a new thread on this topic.
>>
>> Technically it's currently possible to do i18n in JSON Schema by using
>> an after-process translate lookup of the value of
>> "title"/"description" attributes.
> Of course, you can save localized versions elsewhere, but it's a good
> case for having it in one place.
i18n/locationalization is applicable to any JSON data, so solutions
shouldn't be specific to JSON Schema. HTTP/REST has great mechanisms for
i18n, that's my preferred approach to switch to different locales. On
the otherhand, if there are i18n schemes that can be described by JSON
Schema, that might be interesting. Do you have such a proposal?
I don't care whether it is divisibleBy or maxDecimal. There were some
that wanted to go back to maxDecimal. Maybe we need to vote on some of
these things.
>>> 6) "id" - Define a pattern that excludes "." and "#" (and other
>>> characters?)
>> Yes, the "id" attribute should be defined in the core schema JSON, but
>> with a "format" of "uri" rather then a pattern.
> Is a simple id (like "mySchema") a URI?
Yes, that is a perfectly valid relative URI.
>>> 7) Why is "default" only used in hyper schema? I usually need it in
>>> any case.
>> I too have been wondering why this was moved. Perhaps Kris can explain
>> this decision.
> I use default to set a value, if it is required but not given in the
> instance. It's really useful.
It was proposed that the core schema should just consist of attributes
that are used for validation. The "default" attribute is does affect
validation, but rather informs agents how to setup new instances.
--
Thanks,
Kris
Martijn Faassen
On Tue, Nov 2, 2010 at 9:59 PM, Andi <andrea...@gmx.de> wrote:
> 4) "uniqueItems": Why shouldn't complex values be compared?
Agreed on this question. It's trivial to implement this kind of
comparison in Python
(where objects are Python dicts and arrays are Python lists).
> 5) "maxDecimal" - Make clear that this can be negative as well.
I asked in my own feedback what the description even means, and I'm
still not sure. Perhaps some examples would help.
Regards,
Martijn
Andi
way:
{
item: {
de: 'Samstag',
de_BY: 'Sonnabend'
},
item2: {
...
}
}
Then I use an underscore function to get the right version in the
context of a user, like:
_.locale('item', 'de_BY')
The localized data do not need to be strings, it can be any data type.
If "de_BY" does not exist, it will try to get "de", then "en" etc.
Usually, I do not want to create separate schemas for different
locales.
Why shouldn't we use this in JSON Schema?
Code: https://github.com/akidee/underscorex/blob/master/index.js#L106
The best use case for this are single localized objects inside
structured data, but not localizing a whole site.
> >>> 6) "id" - Define a pattern that excludes "." and "#" (and other
> >>> characters?)
> >> Yes, the "id" attribute should be defined in the core schema JSON, but
> >> with a "format" of "uri" rather then a pattern.
> > Is a simple id (like "mySchema") a URI?
>
> Yes, that is a perfectly valid relative URI.
>
> >>> 7) Why is "default" only used in hyper schema? I usually need it in
> >>> any case.
> >> I too have been wondering why this was moved. Perhaps Kris can explain
> >> this decision.
> > I use default to set a value, if it is required but not given in the
> > instance. It's really useful.
>
> It was proposed that the core schema should just consist of attributes
> that are used for validation. The "default" attribute is does affect
> validation, but rather informs agents how to setup new instances.
mode to shorten a string ;)
default must be part of the core schema, it's like the SQL default. If
you take a look around (I remember ROR or Symphony), you always want
default values in a schema!
Andi
_.locale(object.item, 'de_BY')
Kris Zyp
awesome work to get this improved and in much better shape. I would like
to get this published soon. I know there are still plenty of discussion
and improvements to be made for JSON Schema, but I think the major
topics for draft-03 have been addressed, and it is time to get this
submitted to IETF. Let me know if you think there are any blockers that
need to address. Hopefully other continuing discussions and topics can
be directed for draft-04.
Thanks,
Kris
Martijn Faassen
On Fri, Nov 12, 2010 at 3:21 AM, Kris Zyp <kri...@gmail.com> wrote:
> I have attached the latest version of draft-03. Gary Court has done some
> awesome work to get this improved and in much better shape. I would like
> to get this published soon. I know there are still plenty of discussion
> and improvements to be made for JSON Schema, but I think the major
> topics for draft-03 have been addressed, and it is time to get this
> submitted to IETF.
Cool! I just sent you a push request with a few more language fixes to
the spec, I hope you can merge them.
> Let me know if you think there are any blockers that
> need to address.
I think the biggest issue I have with draft 03 is that it doesn't
really clarify the rules for extends. I posted my analysis just now,
along with some suggestions. My worry is that the rules for extends as
stated describe that validators should validate extending schemas and
reject them if they break rules, and that this is difficult to
implement. When implementing draft 02 this was the biggest source of
confusion. I still have to think very carefully each time I think
about this section, and I'm still not sure I'm getting it right each
time. I think it would help to add the minimal implementation
suggestion I made (check against both schemas without an attempt at
merging them), if that at least is correct.
Too bad the ability to use a schema in the submission link properties
wasn't discussed, but I don't think that's a blocker.
Regards,
Martijn
Kris Zyp
http://www.ietf.org/id/draft-zyp-json-schema-03.txt
I believe the HTML version will eventually be available at:
http://tools.ietf.org/html/draft-zyp-json-schema-03
(doesn't seem to be there yet, not sure if I have to do anything but
wait).
Thank you everyone for your help in getting this out!
Thanks,
Kris
Gary Court
Thanks to everyone for their involvement in this!
-Gary
Martijn Faassen
Thanks Kris!
Regards,
Martijn