JSON Schema: Define and Validate Data

What is JSON Schema?

A JSON Schema is itself a JSON document that describes constraints for another JSON value, called the instance. For example, a schema can require a user object to contain a string name and an integer age. Validation checks whether the instance satisfies those declared rules. It does not prove that a value is true in the real world or enforce rules that were not written into the schema.

Core schema keywords

• $schema identifies the schema vocabulary or draft used. This example uses Draft 2020-12.
• type sets the expected JSON type: object, array, string, number, integer, boolean, or null.
• properties defines rules for named object properties.
• required lists property names that must be present. A property is not required merely because it appears in properties.
• items describes the expected value or schema for each array item.
• additionalProperties can allow, forbid, or describe properties not listed under properties.

A complete schema and matching data

This schema describes an object with a required name and an optional active flag. It also describes a required array of tag strings and a nested profile object. Setting additionalProperties to false rejects undeclared keys at each object level where it appears.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "active": { "type": "boolean" },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "profile": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "timezone": { "type": "string" }
      },
      "required": ["city"],
      "additionalProperties": false
    }
  },
  "required": ["name", "tags", "profile"],
  "additionalProperties": false
}

This instance satisfies the schema: all required properties are present, their values have the expected types, the tag items are strings, and the profile contains a required city.

{
  "name": "Ari Chen",
  "active": true,
  "tags": ["editor", "member"],
  "profile": {
    "city": "Portland",
    "timezone": "America/Los_Angeles"
  }
}

For example, changing "active": true to "active": "yes" violates the declared boolean type. Removing name violates the root required list. Adding an undeclared property is rejected because additional properties are disabled.

Arrays and nested objects

Use items to define array elements. An object schema inside items describes every object in that array. Use another properties block inside a property schema to validate nested objects. If values may be null, explicitly include null in the accepted type (for example "type": ["string", "null"] in the supported draft) or use the appropriate schema composition.

Common schema mistakes

• Assuming properties are required: list mandatory names in required.
• Using the wrong numeric type: JSON Schema distinguishes integer from number; use the one your data allows.
• Forgetting array item rules: without an items schema, the schema may not constrain each element as intended.
• Closing only the root object: additionalProperties applies where it is declared; nested objects need their own rule if they should also be closed.
• Confusing syntax with schema validity: an instance must first be parseable JSON, then it must pass the schema rules.
• Overconstraining from one sample: a generated schema can infer a shape from observed values, but it cannot know every valid future case or business rule.

How schema validation works

1. Write or generate a schema describing the shape you expect.
2. Parse the data as JSON. Invalid syntax must be corrected before schema validation.
3. Run a validator against the instance and schema.
4. Review each validation error and decide whether the data is wrong or the schema is too restrictive.

RomitJSON's JSON Schema Validator checks a JSON document against a supplied schema using Draft 2020-12 support. The JSON Schema Generator can infer a starting schema from sample JSON; review and adapt the result to reflect your actual requirements.

Key takeaways

• A schema describes rules; the instance is the data being checked.
• properties defines property rules, while required separately specifies presence.
• items describes array contents, and nested schemas describe nested objects.
• Validation only checks rules that the schema expresses.