Master JSON Schema
for OpenAPI

Why JSON Schema is the Secret to World-Class API Design

• What is JSON Schema and Why Learn It?
• JSON Schema's Role in OpenAPI and API Specifications
• Understanding OpenAPI as a Wrapper Around JSON Schema
• Best Practices: Organizing Schemas as Separate Files

Keywords, Vocabularies, Dialects, and Meta-Schemas

• Understanding JSON Schema Keywords: The Atomic Building Blocks
• JSON Schema Vocabularies: Grouping Related Keywords
• Dialects and Meta-Schemas: Encoding and Validating JSON Schema Versions
• Subschemas: The Recursive Tree Structure of JSON Schema

A Systematic Approach to Reading Any JSON Schema

• Two Ways of Using JSON Schema: Evaluation vs Static Analysis
• JSON vs YAML: Syntax Differences and Semantic Equivalence
• Step 1: Determining the Dialect
• Step 2: Identifying Vocabularies
• Step 3: Understanding Keywords and Checking Dependencies
• Step 4: Evaluating Keywords in Order
• Understanding JSON Schema as a Constraint-Driven Language

From Unicode Encoding to Regular Expressions and Format Validation

• Unicode Fundamentals: How Computers Represent Text
• Basic String Validation with type, const, and enum
• String Length Constraints: minLength and maxLength
• Pattern Matching with Regular Expressions and ECMA-262
• The format Keyword: Semantic Validation and Common Pitfalls

Integers, Floats, Precision, and Interoperability

• JSON Number Representation and Interoperability Challenges
• Basic Number Validation with type, const, and enum
• Numeric Range Constraints with multipleOf, minimum, maximum, exclusiveMinimum, and exclusiveMaximum
• Advanced Techniques: Working Around Precision Issues

Validation, Containment, and Tuple Patterns

• Array Basics: type, const, and enum
• Array Size Constraints: minItems and maxItems
• Uniqueness Validation with uniqueItems
• Containment Assertions: contains, minContains, and maxContains
• Homogeneous Arrays: The items Keyword
• Heterogeneous Arrays: The prefixItems Keyword and Tuple Validation

Properties, Patterns, and Advanced Composition Techniques

• Object Basics: type, const, and enum
• Defining Properties with the properties Keyword
• Pattern-Based Properties with patternProperties
• Controlling Additional Properties with additionalProperties
• Object Size Constraints: minProperties and maxProperties
• Requiring Properties with the required Keyword
• Property Name Validation with propertyNames
• Validating Additional Properties with additionalProperties
• Property Inter-Dependencies: dependentRequired and dependentSchemas

Unlocking Conditional Logic and Advanced Validation

• Multiple Type Validation with Array-Mode type
• Disjunction Logic with anyOf
• Exclusive Choice with oneOf
• Conjunction Logic with allOf
• Conditional Schemas with if, then, and else
• Negation with the not Keyword

Mastering Schema Composition and Bundling

• URI Fundamentals and RFC 3986
• Schema Resources and the $id Keyword
• Reusable Schemas with $defs
• Schema References with $ref and JSON Pointers
• Internal vs External References
• Position-Independent References with $anchor
• JSON Schema Bundling and De-referencing

Mastering unevaluatedProperties and unevaluatedItems

• Understanding Evaluation Traces and the Unevaluated Vocabulary
• Forbidding Unevaluated Object Properties with unevaluatedProperties
• Forbidding Unevaluated Array Items with unevaluatedItems

Extensible Schemas with $dynamicAnchor and $dynamicRef

• Understanding the Dynamic Scope
• Registering Fragments with $dynamicAnchor
• Runtime Lookups with $dynamicRef
• Schema Extension Patterns and Polymorphic Validation

Extracting Metadata from the Validation Process

• Introduction to JSON Schema Annotations
• The Meta-Data Vocabulary: Pure Annotation Keywords
• The default Keyword and Its Caveats
• The format Keyword as an Annotation
• Object Applicator Annotations: properties, patternProperties, additionalProperties, and unevaluatedProperties
• Array Applicator Annotations: prefixItems, items, contains, and unevaluatedItems
• Unknown Keywords as Ad-Hoc Annotations
• Annotation Collection Caveats and Practical Applications

The Content Vocabulary for Non-JSON Data

• The Content Vocabulary: Inspired by Email Standards
• Binary-to-Text Transformation with contentEncoding
• Declaring MIME Types with contentMediaType
• Describing Embedded Formats with contentSchema

From Data Modeling to Production OpenAPI Specifications

• Planning Your Problem Domain and Data Model
• Implementing Schemas Following Best Practices
• Testing and Quality Assurance for JSON Schemas
• Deploying Schemas to Registries
• Composing Schemas into OpenAPI Specifications