Schemagic
DocsTools

JSON Schema Types

The type keyword defines what kind of data a field is allowed to contain. JSON Schema includes seven built-in types: five primitive types that hold a single value, and two composite types that group values together.

Primitive Types

string

Text — any sequence of characters: letters, digits, symbols, spaces. The most versatile type; use it for names, descriptions, addresses, codes, and any other free-form text. Supports formats for semantic validation.

ValueStatusNote
"hello"
valid
""
valid
empty string is still a string
"42"
valid
a number written as text is still a string
42
invalid
this is a number, not a string
KeywordDescription
minLengthMinimum number of characters the value must have (inclusive).
maxLengthMaximum number of characters the value may have (inclusive).
patternA regular expression the value must match.
formatA named semantic hint. Supported values: date, time, date-time, duration, email, idn-email, hostname, idn-hostname, uri, uri-reference, uri-template, iri, iri-reference, ipv4, ipv6, uuid, json-pointer, relative-json-pointer, regex.
ValueStatusNote
"Alice"
valid
"hi there"
valid
"A"
invalid
too short — minLength is 2
"hello123"
invalid
digits violate pattern "^[A-Za-z ]+$"
"AAAAAAAAAAA"
invalid
11 characters exceeds maxLength: 10

number

Any numeric value — whole or decimal. Covers integers, fractions, and scientific notation. Use when a fractional value may be needed: prices, distances, weights, ratings. For whole numbers only, prefer integer.

ValueStatusNote
42
valid
3.14
valid
-7
valid
0
valid
1.5e10
valid
scientific notation is accepted
"42"
invalid
a string containing digits is not a number
KeywordDescription
minimumThe value must be ≥ this number (inclusive lower bound).
maximumThe value must be ≤ this number (inclusive upper bound).
multipleOfThe value must be evenly divisible by this number. Useful for step sizes or currency precision.
ValueStatusNote
1
valid
100
valid
-1
invalid
below minimum: 0
1000
invalid
above maximum: 999.99
0.001
invalid
not a multiple of 0.01

integer

A whole number — no fractional part. Use when only round values make sense: counts, IDs, ages, page numbers, quantities. If fractions are possible, use number instead. Decimal notation like 1.0 is accepted as long as the fractional part is zero.

ValueStatusNote
0
valid
42
valid
-5
valid
1.0
valid
fractional part is zero — treated as an integer
3.14
invalid
non-zero fractional part
"42"
invalid
string, not a number
KeywordDescription
minimumThe value must be ≥ this number (inclusive lower bound).
maximumThe value must be ≤ this number (inclusive upper bound).
multipleOfThe value must be evenly divisible by this number. Useful for step sizes or currency precision.
ValueStatusNote
1
valid
100
valid
0
invalid
below minimum: 1
366
invalid
above maximum: 365
3.14
invalid
not an integer

boolean

A true/false value. Use for on/off switches, yes/no answers, active/inactive flags, or any field that has exactly two states. Note: JSON booleans are lowercase true and false, not strings or numbers.

ValueStatusNote
true
valid
false
valid
"true"
invalid
the word "true" as text is not a boolean
1
invalid
in JSON, 1 is not the same as true
0
invalid
null
invalid
null is the absence of a value, not false

null

The intentional absence of a value — "this field has no value." In JSON, null is its own distinct type, not zero, not an empty string, not false. Often combined with another type (e.g. string or null) using anyOf to mark a field as optionally empty.

ValueStatusNote
null
valid
""
invalid
an empty string is still a string, not null
0
invalid
zero is a number, not null
false
invalid
false is a boolean, not null
"null"
invalid
the word "null" as text is not null

Composite Types

array

An ordered list of values. Items appear in sequence and can be accessed by position (first, second, third…). Use for collections where order matters: tags, search results, cart items, a list of phone numbers. The optional itemskeyword constrains what type each element must be.

ValueStatusNote
[]
valid
empty list
["apple", "banana", "cherry"]
valid
[1, 2, 3]
invalid
numbers are not strings
"apple, banana"
invalid
comma-separated text is a string, not an array
KeywordDescription
minItemsMinimum number of items the array must contain.
maxItemsMaximum number of items the array may contain.
ValueStatusNote
["apple"]
valid
["a", "b", "c"]
valid
[]
invalid
below minItems: 1
["a","b","c","d","e","f"]
invalid
6 items exceeds maxItems: 5
[1, 2, 3]
invalid
items must be strings

object

A structured set of named fields (key-value pairs). Use for records, profiles, addresses, and settings — any entity with multiple attributes. The propertieskeyword defines the shape of the object, and requiredlists which fields must always be present.

ValueStatusNote
{}
invalid
missing required field 'name'
{"name": "Alice", "age": 30}
valid
{"name": "Bob"}
valid
optional fields can be omitted
{"name": "Alice", "extra": true}
valid
by default, additional properties are allowed
KeywordDescription
requiredA list of field names that must be present. Fields not in this list are optional.
minPropertiesThe object must have at least this many properties (inclusive).
maxPropertiesThe object must have no more than this many properties (inclusive).
additionalPropertiesWhen set to false, properties not listed in properties are rejected.
ValueStatusNote
{"name": "Alice"}
invalid
1 property is below minProperties: 2
{"name": "Alice", "age": 30}
valid
{}
invalid
missing required field 'name'
{"name": "Alice", "extra": true}
invalid
additionalProperties: false rejects unknown fields
{"name": "x", "age": 1, "email": "x@y.com", "phone": "555", "city": "NY", "country": "US"}
invalid
6 properties exceeds maxProperties: 5