Add custom constraints and fields in json schema definition

Question

Hello I trying to understand how use json schema to validate data across each software layer (db, model and presentatotion).

I've basically understand how to transform a record in jsonschema definition; for example considers:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema"
  , "id":"myId"
  , "type":"object"
  , "properties":{
        "code":{"type":"string","pattern":"[a-zA-Z0-9]{6}-[0-9]{4}"}
    ,   "firstAmount":{"$ref": "#/$defs/amount"}
    ,   "secondAmount":{"$ref": "#/$defs/amount"}
    ,   "inputDate":{"$ref": "#/$defs/dateTime"}
  }
  , "required":["code","inputDate"]
  ,"dependentRequired":{"firstAmount":["secondAmount"]}
  ,"additionalProperties":false
  ,"$defs":{
    "amount":{"type":"integer", "minimum":1, "maximum":9999999}
   , "dateTime":{"type":"string", "format":"date"}
  }

This schema evaluates:

{
        "code":         "a89dff-5467"
    ,   "firstAmount":  98520
    ,   "secondAmount": 45678
    ,   "inputDate":    "2025-05-15"
    
}

What I'm looking for is a way (possibly the right one) to:

• add a constraints, i.e.: secondAmount must be lesser than firstAmount
• add a custom error message for a constraint
• add a label for each field in schema definition (so the FE could show this text
• generally speaking, add instruction for model and presentation layer
• also validate customs constraints

If I understand correctly for first 4 points I'm talking about add a custom vocabulary, but how?

For last point there isn't a solution because I've to extend the validator I use (doh!), is it correct?

Any suggestions?

Answer 1

I'll take these one at a time.

add a constraints, i.e.: secondAmount must be lesser than firstAmount

This isn't supported out of the box with JSON Schema. There is no way to define the value in one location based on the value in another location.

That said, there is an extension vocabulary that will support this, but as far as I'm aware, my .Net implementation is the only one.

add a custom error message for a constraint

Custom error messages will be based on the implementation you're using, if it's even supported. There's not a way to define error messages within the schema itself.

add a label for each field in schema definition (so the FE could show this text

JSON Schema (in its current state) will ignore unknown keywords, and many implementations will return them as annotations.

The next version of JSON Schema will require that these annotative keywords start with x- if they're not defined in a vocabulary, so it might be a good idea to go ahead an prefix your custom keywords with that now so that it will be compatible moving forward.

generally speaking, add instruction for model and presentation layer

This will also fall under the category of a custom annotation keyword, which you can just add to the schema as you need.

also validate customs constraints

This will depend on the implementation you're using and how well they support custom assertion keywords. Some implementations support just defining the keyword and registering it, while others require the keyword to be included in a vocabulary.

For more information on vocabularies, please have a look at my docs which give an overview before diving into how my implementation does it.