In the section Dates and times, the link for "RFC 3339, section 5.6." takes me to https://json-schema.org/draft/2019-09/json-schema-validation.html, but it should really be https://tools.ietf.org/html/rfc3339#section-5.6.

Hey Team!

Just wanted to let you know we're getting pretty close to finishing and releasing draft-6.
I don't know if you plan to continue maintaining this resource, but it's useful to me and many others.

Cheers

The guide contains examples with $schema: "http://json-schema.org/draft/2019-09/schema#" to refer to JSON-Schema 2019-09 whereas the spec uses $schema: "https://json-schema.org/draft/2019-09/schema".

Confirmed via json-schema-org/json-schema-spec#988.

It would be nice to note in the book that there is one very important distinction between JSON objects and Python dicts - JSON objects keep the order of keywords, while order of Python dicts' keys is undefined (simply put, it can be random order, different every time we try to print it out... depends on implementation).

Newbie could be surprised by Python's behavior. Also, note on existence of collections.OrderedDict could help.

Would there be any interest in having PHP code equivalents added?

I wouldn't mind adding those if there is interested in accepting such a PR...

Once support for Draft 7 is in Julian/jsonschema, work can start on this in earnest.

And conversely, why is it invalid when a enum is [].

This is causing an issue for us when we generate schema's dynamically and there is an option that is meant to be unpopulated/empty.

Thanks.

Hi, I would like to something like this:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "properties": {
      "type": "object",
      "enum": "metadata"
    },
    "required": {
      "type": "array",
      "items": {
        "metadata": "string"
      }
    }
  }
}

but this part is not working well:

"properties": {
      "type": "object",
      "enum": "metadata"
 },

Is possible to do this? or is estrictamente prohibido to use those built schema words like: "required", "enum", "properties" as a property inside "properties"?.
Thanks in advance for helping me to understand this part 😄

I found that id was never mentioned in this book. Actually I have difficulties in understanding that part in spec during implementation of a validator. Is there a plan for covering it?

By the way, this book is very useful for me to learn json schema in short time. Thank you.

The new learning section looks great! Super props to @retrosight!

One common question is around additional properties not defined in the properties schema still passing validation.
I think we've been pretty clear that key words ADD constraints, but I still expect this is sometimes missed.

I feel a small section at the end of the getting started section could address the use case for "additionalProperties": false and show the simplest of examples.

I think sometimes we (including myself) forget that reading RFCs is hard. =]

It would be nice to have a local table of contents on each page on the web site. Now, if you aren't sure which subsection you are looking for you have to scroll down the page looking out for headings, and it is very easy to miss headings that way. If there were a TOC (list (with sublists) with links) it would be much easier to see what is found on the page.

On the page
http://json-schema.org/understanding-json-schema/about.html
in the green box under the line "However, the second example passes:"
the "birthday" property has the value "22-02-1732".
This is supposed to match
"birthday": { "type": "string", "format": "date" },
which AFAICS requires an ISO8601 yyyy-mm-dd format.
The string also differs from that first used.

Is That possible to provide a link to Jekyll some branches of this repo ?
Something like pointing over a branche feature/draft-4 ? :

https://draft-4.json-schema.org/understanding-json-schema/

But maybe this issue should be more related to json-schema.org ?
In any case, I don't see any version tag or branches to do such a fix.

Thanks, great job for this doc anyway.

A subissue of #79.

Is it possible to validate ndjson file?

http://spacetelescope.github.io/understanding-json-schema/reference/numeric.html

Having an "exclusive minimum" (exclusiveMinimum is true) means that the minimum value is not a valid value.

The examples are correct, but the text has it the wrong way around.

Hey @mdboom, we we're discussing this repo in a meeting, and it came up that it might be more appropriate (given it's common external usage) to move this repo outside the spacetelescope organization. STScI has no plan to maintain it going forward. Do you want to take it? If not, any ideas of who would?

Same could be said for the https://github.com/spacetelescope/yaml-schema-standard repo.

The example of how to use $id with $ref is not how we would like people to do things.

https://json-schema.org/understanding-json-schema/structuring.html#using-id-with-ref

We should rework this to show the intended general use case, where you reference another file by it's $id, including relative URI resolutions.

It's possibly worth noting that you can use an $id in a subschema, but it's not advised because it makes things more complex.

Additionally, is the statement about no support for this true in terms of the python library?

@Julian ?

In the following schema,

{ "type": "array",
  "items": [
{ "type": "number" },
{ "type": "string" },
{ "type": "string",
  "enum": ["Street", "Avenue", "Boulevard"] },
{ "type": "string" } ] }

I'm trying to validate this: [1600, "Pennsylvania", "Avenue", "NW"]

Now, the documentation explains that it's okay to leave out items. What happens if I leave out the third item "Avenue". It would not validate the JSON because "NW" is not enumerated in the schema? This would especially get more interesting if the first item is enum . Like so:

{ "type":"array",
  "items": [
  { "type": "string",
  "enum": [ "Alice", "Bob", "Eve", "Mallory" ] },
  { "type": "string"} ]
}

Is there a way I can work around this problem?

It's the best source I found while working on some really complex schemas. Thanks! 👍

A subissue of #79.

GitHub now lets you enforce HTTPS for *.github.io domains:

https://github.com/blog/2186-https-for-github-pages

The site already works over HTTPS: https://spacetelescope.github.io/understanding-json-schema/index.html There's a font URL that needs to be updated to https://, but that is a trivial fix.

In https://json-schema.org/understanding-json-schema/reference/regular_expressions.html#regular-expressions it is mentioned that use of . is not recommended in regular expressions. It specifically mentions python in this context, but to my knowledge . has been supported in regular python re since a very long time (e.g. python 2.5 has this). What's the reason use of . is not recommended?

This site was very helpful in explaining JSON Schema, but one topic which didn't seem to be covered at all was JSON Hyper Schema. What exactly is that, and how is it different from the regular JSON Schema? From what I've read so far, I'm guessing it has something to do with links between schema documents?

schema.rst includes this sentence:

The $schema keyword is used to declare that a JSON fragment is actually a piece of JSON Schema.

This is incorrect; JSON Schema doesn't place any restrictions on JSON documents, so it's perfectly valid for a non-schema JSON document to include a $schema key. (The meaning of that key would be specific to the writers/readers of that particular document.)

Conversely, it's also not the case that a piece of JSON Schema will have a $schema key; its presence in root schemas is only a SHOULD, and it MUST NOT appear in sub-schemas (which are, of course, JSON fragments that are actually pieces of JSON Schema).

(#50 is related to this, but given the age of that issue I was asked to open a new one. I was also asked to note that this should be a post-draft-8 discussion.)

I think the reference page should be more prominently linked (it is way more usable then the original specs).

This one: http://spacetelescope.github.io/understanding-json-schema/reference/index.html

Also this 5 bullets link menu could be on top of every reference child page I think, because you'd usually navigate this intensively when building a schema.

I'd send a PR but I'm not setup to get hacking to run the Makefile (Windows)

Michael Zub wrote:

Thank you for great "Understanding JSON Schema" site and book. It is very helpful and easy to understand and should be recommended to everyone working with JSON Schema.

As a reader I have a minor remark on "additionalItems" keyword description. On page 26 you have wrote:

"The additionalItems keyword controls whether it’s valid to have additional items in the array beyond what is defined in the schema. Here, we’ll reuse the example schema above, but set additionalItems to false, which has the effect of disallowing extra items in the array."

According to this one can assume that "additionalItems" can be only boolean flag, but there is a case when "additionalItems" can be schema that describes additional array items (very similar as "additionalProperties" works).
As example, schema {"items":[{}],"additionalItems":{"type":"integer"}} won't validate next JSON: [null,2,3,"foo"]. If this data is put into the validator (for example http://json-schema-validator.herokuapp.com/index.jsp) the error will be "instance type (string) does not match any allowed primitive type (allowed: ["integer"])".

The example from above is taken from JSON Schema Test Suite - https://github.com/json-schema/JSON-Schema-Test-Suite

I think it will be great if similar case is added to your book.

Regards,
Micheal Zub

Greetings,
For example, on page 12 of the PDF, it shows:
{ "type": ["number", "string"] }
and then lists a few examples.

    42
    "Life, the universe, and everything"
    ["Life", "the universe", "and everything"]

They are not distinguished as 'pass' or 'fail', but on the original page you can see that the third example is supposed to be bad.

Some form of distinguishing marks on the PDF would make it significantly more useful, as right now it is more confusing than helpful.

-- Morgan

The epub version currently puts a header and footer at the beginning and end of every chapter. There are probably other issues as well.

in the multiple countries example in
https://json-schema.org/understanding-json-schema/reference/conditionals.html

Hi there,

thanks for the great work--please keep it up :)

I was wondering whether you've thought about providing an option to allow null values for other types. I'm thinking about something like this (pseudo code):

{
  "type": "number",
  "minimum": 0,
  "nullAllowed": true
}

This would then validate true against the following examples, whereas currently the second example would fail:

• { "foo": 13 }
• { "foo": null }

Thanks,
Mario

I didn't find information on the document. So I don't know whether it is exists.

Current usage for "required" command:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "required": [
        "name"
    ],
    "properties": {
        "name": {
            "type": "string"
        }
    }
}

When I want to remove the property "name", I should always remember removing "name" from "required" array.
It will be helpful if I can define "required" in the definition of properties. For example:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "isRequired": true
        }
    }
}

Please let me know if there are reasons we can not do like this.

The following line is in numeric.rst:

The integer type is used for integral numbers.

While that sounds good, there isn't really any such thing as an integral number. When applied to numbers, the term "integral" generally refers to the area under the curve of a graphed function.

To be correct (although redundant), the line should read, "The integer type is used for integers".

EDIT: Wait, never mind. Definition 5 of integral from dictionary.reference.com:

Arithmetic. pertaining to or being an integer; not fractional.

Open this link in chrome and you'll get a "this connection is not secure" warning:
https://json-schema.org/understanding-json-schema/

i found https://stackoverflow.com/a/38781027/2602592 extremely helpful as a reference for understanding the different approaches to schemas depending on field values.

it covers dependencies, anyOf (Implication) and if-then-else

Would be a wonderful addition, though in the answer spans till v7.

Hi there!

I'm reading the online book(thanks you guys for this!), and found a small bug in Generic Keywords page.
Navigation menu shows null as prev page, maybe this is an error in sphynx? I dont have any experience with sphynx-doc, so im still taking a look to see if I can fix this...
Maybe someone with more knowledgement in this subject can help fixing this (must be a easy task, I think).

ref image:

Tyler Desjardins mentions that we should consider moving emails from help[at]stsci.edu to point to the web portal where possible and appropriate. For HST (or any non-JWST), it is https://hsthelp.stsci.edu . For JWST, it is https://jwsthelp.stsci.edu . Please update info in setup.py, setup.cfg, documentation, etc as appropriate.

Please close this issue if it is irrelevant to your repository. This is an automated issue. If this is opened in error, please let pllim know!

xref spacetelescope/hstcal#317

The octopus on the front page and the accept/reject icons in the text are not retina-display compliant. That should probably be fixed.

Hello, firstly thanks for writing this guide, very useful! My issue relates to the use of the $schema keyword/property, as I understand it, this is a string pointing to the schema for the document in question. Hence why schema documents point to "http://json-schema.org/draft-04/schema". In your guide you say that:

The $schema keyword is used to declare that a JSON fragment is actually a piece of JSON Schema

This is not my understanding; it doesn't declare that the containing fragment is a schema, but that it conforms to the particular schema which is given by the value of the $schema property. So JSON schemas should point to the above location because that schema defines how schemas should be laid out. Whereas JSON documents conforming to a schema you've created should set the $schema property to point to the schema that they have created. I've been a bit confused about this so I am happy to be corrected!

Thanks again

Mark

It can't hurt to add a chapter listing and describing how to actually use some JSON Schema implementations. While I don't think it should serve as a full replacement for those projects' own documentation it can't hurt to point to the best libraries available for a given language and some basic examples of how to use them.

I'll assign myself this since it's my idea.

This stackoverflow discussion highlights the failings of allOf

http://stackoverflow.com/questions/22689900/json-schema-allof-with-additionalproperties

I think there should be some reference to this as this could be miss leading to someone who hasn't encountered this problem.

I loved this quick tutorial. I would add a way to let me go from one page to the next without having to go back to the main menu. That small change would make a huge difference

The truth table on the Applying subschemas conditionally section seems to be missing the rows corresponding to the cases when if is invalid. I believe the full table should be like this:

http://spacetelescope.github.io/understanding-json-schema/reference/object.html#pattern-properties

patternProperties only takes effect if additionalProperties is set to false.

This isn't quite right.

What actually happens is that if a property matches anything in patternProperties then additionalProperties does not apply to it. So I can have something like:

{
    "type": "object",
    "patternProperties": {
        "^[0-9]+$": {"type": "integer"}
    },
    "additionalProperties": {"type": "string"}
}

This says that any key made entirely of decimal digits must have an integer value. Anything else must be a string.

Valid: {"0123": 4567, "foo": "bar"}
Invalid: {"foo": 1234}

Your examples in the guide are still valid - if additionalProperties is false, then only properties from properties/patternProperties are allowed. However, this is not the only situation where patternProperties can be used.

On http://spacetelescope.github.io/understanding-json-schema/reference/numeric.html, it rejects 5.0 as an integer.

This is correct in Python, but JavaScript doesn't have separate floating-point and integer types. The standard makes allowances for languages like this to determine integer-hood based on numerical value only.

This should perhaps go in the "Language-specific info" section at the top?

Hello
Here is sample schema from tutorial :

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

"definitions": {
"address": {
"type": "object",
"properties": {
"street_address": { "type": "string" },
"city": { "type": "string" },
"state": { "type": "string" }
},
"required": ["street_address", "city", "state"]
}
},

"type": "object",

"properties": {
"billing_address": { "$ref": "#/definitions/address" },
"shipping_address": {
"allOf": [
{ "$ref": "#/definitions/address" },
{ "properties":
{ "type": { "enum": [ "residential", "business" ] } },
"required": ["type"]
}
]
}

}
}

Here is valid instance:
{
"shipping_address": {
"street_address": "1600 Pennsylvania Avenue NW",
"city": "Washington",
"state": "DC",
"type": "business"
}
}

I need to limit used fields for shipping_address as following :

"shipping_address": {
"allOf": [
{ "$ref": "#/definitions/address" },
{ "properties":
{ "type": { "enum": [ "residential", "business" ] } },
"required": ["type"]
}
],
"additionalProperties":false
}

While checking with validator , I got following error :

[ {
"level" : "error",
"schema" : {
"loadingURI" : "#",
"pointer" : "/properties/shipping_address"
},
"instance" : {
"pointer" : "/shipping_address"
},
"domain" : "validation",
"keyword" : "additionalProperties",
"message" : "additional properties are not allowed",
"unwanted" : [ "city", "state", "street_address", "type" ]
} ]

The question - how should I limit fields of shipping_address in the sample above ?
Thanks in advance

Right now, we have this note in the documentation:

Note: This book describes JSON Schema draft 7. Earlier versions of JSON Schema are not completely compatible with the format described here, but for the most part, those differences are noted in the text.

One day, "Understanding json schema" will have support for 2019-09 specification. Since a lot of people will be using older drafts that still need to have reference to older documentation, it would be nice to have a branch or a tag of this repository while in draft 7 for reference. If you don't want the overhead of doing this right now, please consider adding this right before adding docs about the new 2019-09 draft.

https://github.com/json-schema-org/understanding-json-schema/blob/master/LICENSE#L1

Does the Space Telescope Science Institute wish to retain copyright?

Say, one day, we want to collaborate on making this into a BOOK rather than just a web resource. It doesn't look like the licence prohibits such, but I'm also not sure what the copyright attribution affords.

See this screenshot:

The little checkbox, gear, etc. icons in the example boxes get cropped in particular in single-line boxes. which I find weirdly distracting (they don't bother me otherwise). I haven't tried this on any other browser yet so I don't know if it's a browser-specific issue.

This could be resolved by either increasing the inner padding on those boxes or making the icons a bit smaller (I think I would prefer the latter).