A data schema describes the structure and constraints that valid data must satisfy without becoming the data itself. Keeping schema separate from representation lets generic data remain flexible while validation protects system boundaries and clarifies expectations inside the system. section 7.0 section 7.1
Consider a book-search request: title must be a string, while fields must be an array whose elements follow declared rules. A schema makes those expectations visible instead of leaving developers to infer them from scattered code. section 7.2
Listing 7.6 Schema of a search request
var searchBooksRequestSchema = {
"type": "object",
"properties": {
"title": {"type": "string"},
"fields": {
"type": "array",
"items": {
"enum": [
"publishers",
"number_of_pages",
"weight",
"physical_format",
"subjects",
"publish_date",
"physical_dimensions"
]
}
}
},
"required": ["title", "fields"]
};
A complete JSON Schema for the search request combines object structure, field types, allowed enumeration values, and required fields. section 7.2
A schema can make several kinds of expectations explicit:
- Declare object, array, string, number, integer, and boolean types. section 7.2 section 12.1
- Require fields, describe array elements, restrict values with enumerations, and reject additional properties. section 7.2 section 12.1
- Describe nested records, homogeneous maps, and tuples for complex data structures. section 12.1
- Specify function argument and return-value shapes, improving development-time errors without requiring class-based representations. section 12.0 section 12.7
Catching a misspelled field
A valid request uses {"title":"habit","fields":["title","weight","number_of_pages"]}. Replacing title with the misspelled key tilte causes validation to return false when title and fields are required. section 7.2
