Merge pull request #1115 from dwelle/master

Added clarifying docs around `optional` behavior (fixes #1111).

API.md

@@ -612,6 +612,8 @@ Converts the type into an [`alternatives`](#alternatives) type where the conditi
     - `then` - the alternative schema type if the condition is true. Required if `otherwise` is missing.
     - `otherwise` - the alternative schema type if the condition is false. Required if `then` is missing.
 
+Note: by default, the `is` condition schema allows for `undefined` values. Use `.required()` to override.
+
 ```js
 const schema = {
     a: Joi.any().valid('x').when('b', { is: 5, then: Joi.valid('y'), otherwise: Joi.valid('z') }),

README.md

@@ -107,7 +107,20 @@ const schema = Joi.object().keys({
 
 When validating a schema:
 
-* Keys are optional by default.
+* Values (or keys in case of objects) are optional by default.
+
+    ```javascript
+    Joi.validate(undefined, Joi.string()); // validates fine
+    ```
+
+    To disallow this behavior, you can either set the schema as `required()`, or set `presence` to `"required"` when passing `options`:
+
+    ```javascript
+    Joi.validate(undefined, Joi.string().required());
+    // or
+    Joi.validate(undefined, Joi.string(), /* options */ { presence: "required" });
+    ```
+
 * Strings are utf-8 encoded by default.
 * Rules are defined in an additive fashion and evaluated in order after whitelist and blacklist checks.