diff --git a/source/reference/generic.rst b/source/reference/generic.rst index 62786280..19991cdd 100644 --- a/source/reference/generic.rst +++ b/source/reference/generic.rst @@ -12,46 +12,63 @@ for all JSON types. single: description single: default single: examples + single: readOnly + single: writeOnly .. _annotation: Annotations ----------- -JSON Schema includes a few keywords, ``title``, ``description``, ``default``, -``examples`` that aren't strictly used for validation, but are used to describe -parts of a schema. - -None of these "annotation" keywords are required, but they are encouraged for -good practice, and can make your schema "self-documenting". - -The ``title`` and ``description`` keywords must be strings. A "title" will -preferably be short, whereas a "description" will provide a more lengthy -explanation about the purpose of the data described by the schema. - -The ``default`` keyword specifies a default value for an item. JSON -processing tools may use this information to provide a default value -for a missing key/value pair, though many JSON schema validators -simply ignore the ``default`` keyword. It should validate against the -schema in which it resides, but that isn't required. - -|draft6| The ``examples`` keyword is a place to provide an array of examples -that validate against the schema. This isn't used for validation, but may help -with explaining the effect and purpose of the schema to a reader. Each entry -should validate against the schema in which is resides, but that isn't strictly -required. There is no need to duplicate the ``default`` value in the -``examples`` array, since ``default`` will be treated as another example. +JSON Schema includes a few keywords, that aren't strictly used for +validation, but are used to describe parts of a schema. None of these +"annotation" keywords are required, but they are encouraged for good +practice, and can make your schema "self-documenting". + +The ``title`` and ``description`` keywords must be strings. A "title" +will preferably be short, whereas a "description" will provide a more +lengthy explanation about the purpose of the data described by the +schema. + +The ``default`` keyword specifies a default value. This value is not +used to fill in missing values during the validation process. +Non-validation tools such as documentation generators or form +generators may use this value to give hints to users about how to use +a value. However, ``default`` is typically used to express that if a +value is missing, then the value is semantically the same as if the +value was present with the default value. The value of ``default`` +should validate against the schema in which it resides, but that isn't +required. + +|draft6| The ``examples`` keyword is a place to provide an array of +examples that validate against the schema. This isn't used for +validation, but may help with explaining the effect and purpose of the +schema to a reader. Each entry should validate against the schema in +which it resides, but that isn't strictly required. There is no need +to duplicate the ``default`` value in the ``examples`` array, since +``default`` will be treated as another example. + +|draft7| The boolean keywords ``readOnly`` and ``writeOnly`` are +typically used in an API context. ``readOnly`` indicates that a value +should not be modified. It could be used to indicate that a ``PUT`` +request that changes a value would result in a ``400 Bad Request`` +response. ``writeOnly`` indicates that a value may be set, but will +remain hidden. In could be used to indicate you can set a value with a +``PUT`` request, but it would not be included when retrieving that +record with a ``GET`` request. .. schema_example:: { - "title" : "Match anything", - "description" : "This is a schema that matches anything.", - "default" : "Default value", - "examples" : [ + "title": "Match anything", + "description": "This is a schema that matches anything.", + "default": "Default value", + "examples": [ "Anything", 4035 - ] + ], + "readOnly": true, + "writeOnly": false } .. index:: @@ -65,13 +82,13 @@ Comments |draft7| ``$comment`` -The ``$comment`` keyword is strictly intended for adding comments to the JSON -schema source. Its value must always be a string. Unlike the annotations -``title``, ``description`` and ``examples``, JSON schema implementations aren't -allowed to attach any meaning or behavior to it whatsoever, and may even strip -them at any time. Therefore, they are useful for leaving notes to future editors -of a JSON schema, (which is quite likely your future self), but should not be -used to communicate to users of the schema. +The ``$comment`` keyword is strictly intended for adding comments to +a schema. Its value must always be a string. Unlike the annotations +``title``, ``description``, and ``examples``, JSON schema +implementations aren't allowed to attach any meaning or behavior to it +whatsoever, and may even strip them at any time. Therefore, they are +useful for leaving notes to future editors of a JSON schema, but +should not be used to communicate to users of the schema. .. index:: single: enum @@ -91,7 +108,6 @@ The following is an example for validating street light colors: .. schema_example:: { - "type": "string", "enum": ["red", "amber", "green"] } -- @@ -117,22 +133,6 @@ different types. Let's extend the example to use ``null`` to indicate --X 0 -However, in most cases, the elements in the ``enum`` array should also -be valid against the enclosing schema: - -.. schema_example:: - - { - "type": "string", - "enum": ["red", "amber", "green", null] - } - -- - "red" - --X - // This is in the ``enum``, but it's invalid against ``{ "type": - // "string" }``, so it's ultimately invalid: - null - .. index:: single: const single: constant values @@ -146,7 +146,8 @@ Constant values The ``const`` keyword is used to restrict a value to a single value. -For example, if you only support shipping to the United States for export reasons: +For example, if you only support shipping to the United States for +export reasons: .. schema_example:: @@ -161,9 +162,3 @@ For example, if you only support shipping to the United States for export reason { "country": "United States of America" } --X { "country": "Canada" } - -It should be noted that ``const`` is merely syntactic sugar for an ``enum`` with a single element, therefore the following are equivalent:: - - { "const": "United States of America" } - - { "enum": [ "United States of America" ] }