Main updates for Draft 7 #84

mdboom · 2018-11-13T21:43:09Z

This updates the document for what feel like the "core" parts of Draft 7. In the interest of not letting the details bog down the most important updates, I'm going to file separate issues and PRs for the remaining Draft 7 things.

Direct link to the Draft 7 release notes

mdboom · 2019-01-08T22:27:15Z

@Relequestual, @handrews : Any interest in reviewing this?

handrews · 2019-01-09T00:00:12Z

@mdboom I had somehow missed this! Will take a look soon.

handrews

Overall this looks great! Most of the comments are ideas that you don't necessarily need to incorporate. I never know how much detail to put into tutorials and references so I'll leave that call to you!

handrews · 2019-01-19T00:14:02Z

source/reference/conditionals.rst

+    }
+
+Unfortunately, this approach above doesn't scale to more than two countries. You
+can, however, wrap pairs of ``if`` and ``then`` inside an ``allOf`` to create


I can never figure out whether allOf, anyOf, or oneOf makes sense here. For mutually exclusive conditions, the effect is the same for all of them. For overlapping conditions, it makes a difference.

I don't think you need to change this, I'm just kind of musing on it.

Good point. In any case allOf/anyOf/oneOf are discussed in detail elsewhere -- this is just intended to show the combination of conditionals with the set notation operators. I think I'll not confuse this here now, but we can always revisit later.

handrews · 2019-01-19T00:17:23Z

source/reference/generic.rst

-practice, and can make your schema "self-documenting".
+|draft7| ``$comment``
+
+The ``title``, ``description``, and ``$comment`` keywords must be strings. A


I wouldn't put $comment with title and description.

$comment, like $defs, is a placeholder keyword. It reserves that keyword for a particular syntax, but doesn't do anything like an assertion or annotation does. $comment is specifically reserved for strings that you're not allowed to do anything with, and $defs is reserved as a place to put re-usable schemas.

title and description are annotations and actually attach their values to the instance during processing (assuming you are collecting annotations).

Is $defs a thing from a newer version of the standard? I still see definitions here and that's what I've used in this doc.

That makes sense about $comment -- I'll move it to its own section and be clearer about how explicitly limited its use is.

Oh, yeah, $defs replaces definitions in the next draft. Although you can keep using definitions, it just didn't fit the core keyword naming. Less seriously, I also can't type it accurately half the time- "definitoins" is what I write more often than not 😛

Anyway, ignore $defs for draft-07, pretend I wrote definitions

handrews · 2019-01-19T00:20:20Z

source/reference/non_json_data.rst

+really only two options useful for modern usage:
+
+- If the string contains a binary MIME type (``image/png``, for example), set
+  ``contentEncoding`` to ``base64`` and encode the contents using `Base64


It might be worth noting that we're adding RFC 4648 encodings to the set of legal values in the next draft, so you can use base64url explicitly. I'm not sure if that's confusing to add or not- maybe as a footnote?

I think since it's not in draft 7, I'll defer mentioning it to later updates. Since many users I've come across are stuck on earlier drafts for various "reasons", I've tried to be really specific about when certain features are and aren't available.

handrews · 2019-01-19T00:21:20Z

source/reference/non_json_data.rst

+  ``contentEncoding`` to ``base64`` and encode the contents using `Base64
+  <https://tools.ietf.org/html/rfc4648>`_.
+
+- If the string contains a text MIME type (usually indicated with the ``text/``


Not sure if it needs to be mentioned, but a text-based application media type such as application/xml would also not need an encoding (I guess unless there's some weird character set issue? I'm a little vague on that sort of thing).

Yeah, I'm a little vague, on that too, but I think it's worth clarifying -- not all text-based formats have the text/ prefix. I think the important distinction for this tutorial is probably -- if the content has the same encoding as the enclosing JSON document (which, in practice, is almost always utf-8) then leave contentEncoding unspecified. If it's some kind of binary data, the best choice, as of draft 7, is base64. I'll simplify/clarify this.

handrews · 2019-01-19T00:22:43Z

source/reference/string.rst


 Built-in formats
 ^^^^^^^^^^^^^^^^

 The following is the list of formats specified in the JSON Schema
 specification.

- ``"date-time"``: Date representation, as defined by `RFC 3339, section


We still reference RFC 3339, not ISO 8601

handrews · 2019-01-19T00:23:28Z

source/reference/string.rst

+Dates and times
+***************
+
+Dates and times are represented in `ISO8601 format


RFC 3339 is a simpler reference, and easier to get than a full ISO spec that you have to buy.

handrews · 2019-01-19T00:24:45Z

source/reference/string.rst

+
+Hostnames
+*********
+
 - ``"hostname"``: Internet host name, see `RFC 1034, section 3.1


Is it worth noting here that an international hostname that has been punycoded is valid under {"format": "hostname"}? (and also "idn-hostname" of course)

I only have a vague understanding of the specs involved. I'm struggling to describe the difference between hostname and idn-hostname in that case. Is the punycoded hostname limited to ascii letters/digits/hyphens like a "classic" hostname? (I see the spec says "punycode" is supported for hostname, but not "internationalized" like in your comment).

I suspect in practice this makes very little difference in terms of what implementations are doing. Any suggestions about how to word this?

Yes, punycode is an algorithm mapping full Unicode strings into the limited ASCII character set which is valid for hostnames in DNS. Note that I said "international", not "internationalized". I really should have just said "non-ascii" as that is not directly related to I18N or pertaining to multiple nations anyway.

This is a valid "format": "idn-hostname" which is not a valid "format": "hostname":

見.香港

This is the same hostname, punycoded so that it is a valid "format": "hostname", which, since all valid hostnames are valid idn-hostnames, is also a valid "format": "idn-hostname":

xn--nw2a.xn--j6w193g

If you paste either into chrome's address bar (and presumably other browsers), it will assume HTTP and take you to the same web site.

Thanks for the explanation. That makes sense now. I'll work on incorporating that into the language.

handrews · 2019-01-19T00:25:51Z

source/reference/string.rst

+  of JSON Pointer within JSON Schema in `structuring`. Note that this should be
+  used only when the entire string contains only JSON Pointer content, e.g.
+  ``/foo/bar``. JSON Pointer URI fragments, e.g. ``#/foo/bar/`` should us e
+  ``"uri"`` or ``"uri-reference"``.


#/foo/bar would definitely be "uri-reference", not "uri"

Indeed. Good catch.

mdboom added 9 commits November 9, 2018 17:40

Basic upgrading of the defaults to draft 7

1fa7006

Document new $comment keyword

5fc2a94

Better errors from invalidation

71e9fcd

Describe conditionals

e169b1d

Improve format index

1d52aa7

Rename metadata -> annotation

d9e95f2

Add section on Media / non-JSON-data

bb7eaae

Updates for new format types

715fb5a

Small clarification

29ec90f

mdboom requested review from embray and Relequestual November 13, 2018 21:43

mdboom and others added 5 commits November 13, 2018 16:45

Update version of jsonschema

fdaeb17

fixed "birthday" in from date to date-time

4c68a86

Update credits

10a54b8

Fix typos

92074e2

Disable LaTeX output for now

40ae42b

mdboom mentioned this pull request Nov 14, 2018

Reinstate link to "Understanding JSON Schema" json-schema-org/json-schema-org.github.io#233

Closed

Reinstate LaTeX

d386e5c

handrews reviewed Jan 19, 2019

View reviewed changes

mdboom added 6 commits January 22, 2019 09:31

Describe $comment separately from description and title

e14a693

Clarify text vs. binary document types

8606772

Be more specific about time format used.

043dc0b

Use url-reference rather than url for JSON schema fragment

f7c1090

Credit Henry Andrews

34693e2

Reinstate installation of PDF file

cb69070

mdboom merged commit dbd6b03 into json-schema-org:master Feb 5, 2019

Uh oh!

Main updates for Draft 7 #84

Main updates for Draft 7 #84

Uh oh!

Conversation

mdboom commented Nov 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mdboom commented Jan 8, 2019

Uh oh!

handrews commented Jan 9, 2019

Uh oh!

handrews left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mdboom commented Nov 13, 2018 •

edited

Loading