type, properties, required — The Three Workhorses

The shape declaration core

Three keywords carry most JSON Schema work: type declares the JSON type, properties declares the keys of an object, required lists which keys must be present.

Type values

The seven type values map to JSON's six plus a split: "string", "number", "integer", "boolean", "null", "object", "array". Note integer is a subtype of number — the validator checks the value has no fractional part.

Type unions

Pass an array to type for unions: "type": ["string", "null"] means 'string or null', a common shape for nullable fields.

required is opt-in

By default, all properties are optional. required is an array of property names that must be present. Omitting required means everything is optional — the schema validates an empty object as valid.

'required' lives next to 'properties', not inside it. A common bug is putting required: true inside each property — that's Draft-04 syntax, removed in Draft-06+. Modern JSON Schema uses an array at the object level: "required": ["name", "email"].

Code

Object with required + optional fields·json

{
  "type": "object",
  "properties": {
    "id":         { "type": "integer" },
    "name":       { "type": "string" },
    "email":      { "type": "string" },
    "created_at": { "type": "string" },
    "deleted_at": { "type": ["string", "null"] }
  },
  "required": ["id", "name", "email"]
}

Nested object types·json

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" }
      },
      "required": ["name", "email"]
    }
  },
  "required": ["user"]
}

Type union (nullable)·json

{
  "type": "object",
  "properties": {
    "middle_name": { "type": ["string", "null"] }
  }
}

Exercise

Take a small JSON document you've worked with recently (an API response, a config). Write a JSON Schema for it from scratch — declare types, list required fields. Run a validator (ajv or Python jsonschema). Now break the document one field at a time and watch the error messages tell you exactly what failed.

type, properties, required — The Three Workhorses

The shape declaration core

Type values

Type unions

required is opt-in

Code

External links

Exercise

Progress

Comments 0