Internal definitions

There are cases when you want to reuse validations that are specific only to that schema document. For example, we have a custom email validator, and a custom username validator, and we want to apply those validators multiple times. Outside the schema document these validators aren’t useful. This can be easily achieved using $ref keyword and the definitions keyword.

{
  "type": "object",
  "properties": {
    "username": {"$ref": "#/definitions/custom-username"},
    "aliases": {
      "type": "array",
      "items": {"$ref": "#/definitions/custom-username"}
    },
    "primary_email": {"$ref": "#/definitions/custom-email"},
    "other_emails": {
      "type": "array",
      "items": {"$ref": "#/definitions/custom-email"}
    }
  },
  
  "definitions": {
    "custom-username": {
      "type": "string",
      "minLength":3
    },
    "custom-email": {
      "type": "string",
      "format": "email",
      "pattern": "\\.com$"
    }
  }
}

{"username": "opis", "primary_email": "opis@example.com"} - valid

{"aliases": ["opis json schema", "opis the lib"]} - valid

{"other_emails": ["opis@example.com", "opis.lib@example.com"]} - valid

{"username": "ab", "primary_email": "opis@example.test"} - invalid

{"aliases": ["opis", "ab"]} - invalid

{"other_email": ["opis@example.test"]} - invalid

Ok, let’s see what happens there. The confusing thing is the value of the $ref keyword, which is something like this #/definitions/something. That’s an URI fragment (starts with #), and the rest of the string after the # represents a json pointer. Json pointers are covered in the next chapter, but we still explain the behaviour in a few words, using our example.

Consider this json pointer /definitions/custom-email. Because the pointer starts with / (slash) we now that we begin at the root of the schema document. Every substring delimited by a / slash, will be used as property name (key) to descend. In our case we have two substrings: definitions and custom-email.

Descending into definitions gives us

{
  "custom-username": {
    "type": "string",
    "minLength":3
  },
  "custom-email": {
    "type": "string",
    "format": "email",
    "pattern": "\\.com$"
  }
}

And from here, descending into custom-email gives us

{
  "type": "string",
  "format": "email",
  "pattern": "\\.com$"
}

Now, this is the value given by our json pointer.

definitions

This keyword does not directly validate data, but it contains a map of validation schemas. The value of this keyword can be anything. This keyword is not required.

Examples

Definition referencing other definition

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "personal_data": {
      "$ref": "#/definitions/personal"
    }
  },
   
  "definitions": {
    "email": {
      "type": "string",
      "format": "email"    
    },
    "personal": {
      "type": "object",
      "properties": {
        "mail": {
          "$ref": "#/definitions/email"
        }
      }
    }
  }
}

{"name": "John", "personal_data": {"mail": "john@example.com"}} - valid

{"name": "John", "personal_data": {"mail": "invalid-email"}} - invalid

{"name": "John", "personal_data": "john@example.com"} - invalid

Recursive validation

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "best_friend": {
      "$ref": "#/definitions/friend"
    }
  },
  
  "definitions": {
    "friend": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "friends": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/friend"
          }
        }
      }
    }
  }
}

Valid examples

{
  "name": "John",
  "best_friend": {
    "name": "The dog"
  }
}
{
  "name": "John",
  "best_friend": {
    "name": "The dog",
    "friends": [
      {
        "name": "The neighbor's dog",
        "friends": [
          {
            "name": "Underdog"
          },
          {
            "name": "Scooby-Doo"
          }
        ]
      }
    ]
  }
}

Invalid examples

{
  "name": "John",
  "best_friend": "The dog"
}
{
  "name": "John",
  "best_friend": {
    "name": "The dog",
    "friends": ["Underdog", "Scooby-Doo"]
  }
}