required vs. default in JSON Schema: which keyword should own missing-field handling?

To ensure a field exists for downstream processing, use the required keyword. The default keyword should be treated as documentation or a hint for specific tools, as the JSON Schema specification does not mandate that validators inject these values into the validated data. The primary distinction between these two keywords is the difference between validation and annotation.

The Role of 'required'

The required keyword is a validation assertion. If a property listed in the required array is missing from the input, the validation fails. This is the only way to guarantee that your downstream code will receive the field based solely on the JSON Schema specification itself.

The Role of 'default'

Under the current JSON Schema meta-schemas (from draft-07 through 2020-12), the default keyword is technically metadata. It describes what the value should be if the field is absent, but the specification does not require a validator to modify the input data to insert that value. While some libraries (like Ajv in JavaScript) offer a configuration flag to "apply defaults," this is an implementation-specific behavior rather than a standard.

When to use which?

• Use required when: The field is critical for the application logic, and its absence should result in an error response or a rejected request.
• Use default when: You want to provide a hint to human readers, or you are using a specific tool that supports automatic population, but the application does not strictly need the field to function.
• Avoid combining them: Marking a field as both required and defaulted is often contradictory. If the field is required, the validator will fail the input before a default-injection mechanism could even process the object.

Summary of Recommendation

If your goal is completeness guarantees, rely on required. If your goal is to provide a fallback for documentation or specialized tools, use default, but ensure your code handles the case where the field might still be missing.