How to specify / reference version of JSON Schema?

Question

I'm trying to define a coding standard for a project and I want to specify use of JSON Schema version 4.

However, from the offical JSON Schema website , if you follow the links for the Specifications, takes you to the github page , then into the Version 4 Draft at the IETF . This document explicitly states that it is an Internet-Draft document and says:

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

Since there don't seem to be any versions of the JSON Schema that are anything other than Internet-Draft status, how should I reference this?

Edit: This is in a written project document, not within a JSON file itself. I currently have text like this:

Python Standards and Style
- All Python Source Files MUST be written in Python 3.x, specifically targeting Python 3.5.1 as the default Python 3 installation with Ubuntu 16.04 LTS.
- All Python Source Files MUST conform to the PEP 8 standard [footnote: https://www.python.org/dev/peps/pep-0008/ ].
- All Python Source Files MUST pass a flake8 [footnote: https://pypi.python.org/pypi/flake8/3.2.1 ] check before each delivery. The checker MUST be set up to be ultra-pedantic and it MUST be considered a unit test failure if the checker needs to change anything on the checked in Source Files.
- All Python Source Files SHOULD use Docstrings conforming to the PEP 257 standard [footnote: https://www.python.org/dev/peps/pep-0257/ ].
JSON Standards and Style
- All JSON Source Files MUST be written in JSON Schema version 4 [footnote: https://tools.ietf.org/html/draft-zyp-json-schema-04 ].
- All JSON Source Files MUST conform to the Google JSON Style Guide 0.9 [footnote: https://google.github.io/styleguide/jsoncstyleguide.xml ]
- All JSON Source Files MUST pass a jsonschema [footnote: https://python-jsonschema.readthedocs.io/en ] check before each delivery. The checker MUST be set up to be ultra-pedantic and it MUST be considered a unit test failure if the checker needs to change anything on the checked in Source Files.
TOML Standards and Style
- All TOML Source Files MUST adhere to v0.4.0 of the TOML standard [footnote: https://github.com/toml-lang/toml ].
- All TOML Source Files MUST be loadable with the pytoml parser v0.1.11 [footnote: https://github.com/bryant/pytoml ], without error.
- All TOML Source Files SHOULD be aligned at the left margin – ie do not indent sub-sections.

To me, the italicised footnote to the JSON Schema reference would count as citing an Internet-Draft document, which is explicitly stated as not appropriate in the excerpt I gave above.

Answer 1

Since there don't seem to be any versions of the JSON Schema that are anything other than Internet-Draft status, how should I reference this?

You do this:

{
    "$schema":"http://json-schema.org/draft-04/schema#",
    ... // the rest of your schema
}

Just because a standard is in draft format doesn't make it any less a standard.

Now, you also have the option of authoring the schema without a $schema declaration and it will still be perfectly valid. If you do this and use the proper JSON schema draft v4 definition then this will be usable by all parsers supporting draft v4. However, the convention is to use the $schema declaration.

• All JSON Source Files MUST be written in JSON Schema version 4

You don't want all JSON files to be schema-based - that's ludicrous. However, any schema files you do need you will have no choice from a documentation perspective other than to reference a version of the standard. And that version should be draft 4 even though it's a draft.

The alternative is to completely remove any reference to JSON Schema altogether, which is probably the route I would take.