JSON Schema Annotation

JSON Schema Annotation

Title and Description

JSON Schemas can be annotated using title and description keyword. They should be used as a self documenting tool. you can add description to your properties as well.

{  
	"title": "Document",  
	"description": "Document description",  
	"type": "object",  
	"properties": {...}  
}  

Deprecated

You can add a deprecated keyword to your definition and indicate that this should not be used and will be removed in the future

{  
	"type": "string",  
	"deprecated": true  
}  

ReadOnly

You can use readOnly keyword to indicate that this should not be modified. It is useful with APIs.

{  
	"type": "object",  
	"properties": {  
		"name": {  
			"type": "string",  
			"readOnly": true  
		}  
	}  
}  

WriteOnly

You can use writeOnly keyword to indicate that this can be set, but it will remain hidden.

{  
	"type": "object",  
	"properties": {  
		"name": {  
			"type": "string",  
			"writeOnly": true  
		}  
	}  
}  

Comments

You can add comments to your JSON Schema using $comment keyword and provide a value as a string. It adds more context to a schema.

{  
	"type": "string",  
	"$comment": "This is my comment"  
}  

Examples

You can add examples to your JSON schema. It is really helpful when you want to show valid values.

{  
	"type": "string",  
	"format": "date",  
	"examples": ["2024-12-03", "2023-02-28"]  
}