Skip to content

Status

Jump to bottom
fge edited this page Nov 6, 2011 · 83 revisions

What is supported

All section 5 of the draft is supported, apart from the limitations mentioned below. This includes:

  • union types (in type as well as in disallow),
  • full dependencies,
  • "multiple extends" (ie, an array of schemas),
  • tuple/non-tuple validation for arrays,
  • $ref (but limited, see below) with loop detection,
  • formats (but limited, see below),
  • enums,
  • etc etc.

All in all, quite a complete implementation.

Limitations

Currently no support at all for...

ALL of section 6 is for now unsupported. Mainly because I don't understand much about it... I prefer to leave it untouched rather than implementing crap :p

Also, section 5 has three missing keywords:

  • default,
  • $schema,
  • id.

The default keyword is likely never to be supported since this API is about validation only (unless, that is, I decide on doing JSON Patch along with JSON Schema). As to the two other ones, they are important schema metadata which are in the plans. Just not yet, though.

$ref limitations

The draft says $ref can be specified by any types of URIs. The support is limited to URLs for now. JSON paths, however, are supported, including as fragments in URL. Therefore, these will work as values to $ref:

HOWEVER: for now, $ref will only resolve JSON Path only refs on the schema which you registered when constructing your JsonValidator object (FIXME: make Javadoc accessible). This means that if you grab a schema over the Internet which contains $ref keywords in it, the ref will not be relative to the downloaded schema as you expect and as it really should be.

color and style format specifications

These format specifications aim to validate respectively a CSS 2.1 color and style. Unfortunately, the best candidate I have found for parsing CSS, jStyleParser, is not available on maven...

So, it is right now a mix of regexes and whatever information I could gather on CSS -- not much.

What the draft doesn't say explicitly, but which is implicit, and is implemented

(for some definition of "implicit")

properties and patternProperties

If a property of an object instance being validated matches exactly a field defined in properties, then this property will be validated against the corresponding schema, so far so good.

However, nothing says that this property should match only this schema. In fact, in this case, the implementation also goes through patternProperties to see if the property happens to match a regex in there too (and see below about regexes). If and only if the property matches neither of them is additionalProperties considered (provided that it is not false, of course).

As an example, consider this schema:

{
    "type": "object",
    "properties": {
        "p1": { "type": "string" }
    },
    "patternProperties": {
        "p": { "minLength": 10 },
        "1": { "format": "host-name" }
    }
}

Now, if the instance to validate contains a property named p1:

  • it will of course have to match the schema defined by the corresponding entry in properties;
  • but it also matches regexes p and 1 (again, see below), so it will have in fact to match all three schemas: the one defined in properties and the two schemas in patternProperties.

Discussions about some fine points of the draft

Regex support: ECMA 262, and the real definition of "matching"

The draft is quite clear that regexes should conform to ECMA 262. This rules out java.util.regex entirely. In fact, the only Java library able to process ECMA 262 regexes is really Rhino and its Javascript engine. This is what this API uses.

Also, even though the draft only implies it (and as the Javadoc points out in several places), please note that the definition of matching is the real one, not the "Java one": a regex can match anywhere in the input! So, remember this when writing your schemas -- if you want your regex to match the whole input, you have to anchor them! This is valid for the pattern keyword, but also for keys in patternProperties, so beware. A JSON Schema implementation which doesn't act this way simply does not obey the draft!

Hostname and email validation

These are two of the format specifications defined by the draft (resp. host-name and email). The fine points:

  • nothing in the RFC defining hostnames say they should be fully qualified;
  • nothing in the RFC defining mail addresses say they should have a domain component.

This implementation strictly obeys the RFCs. The draft doesn't force hostnames or emails to be fully qualified/have a domain part. As such, this implementation strictly obeys the RFCs, and "foobar" is a perfectly valid hostname -- and email as well.

Clone this wiki locally