URI templates

URI templates help us dynamically reuse schemas based on the values of current data being validated.

For simplicity, we can say that an URI template contains placeholders that will be replaced by values to get an URI reference that will be used further. Here is an example:

{
    "$ref": "http://example.com/{folder}/{file}.json",
    "$vars": {
        "folder": "user",
        "file": "schema"
    }
}

Above, we have two placeholders {folder} and {file}, which will be replaced with the corresponding values from the $vars keyword ({folder} => "user", {file} => "schema"), resulting the final URI http://example.com/user/schema.json.

More details about the structure of uri templates can be found here.

Expansion examples

Path

{
  "$ref": "{/var1,var2}",
  "$vars": {
    "var1": "a",
    "var2": "b"
  }
}

Resulted $ref is /a/b.

Query string

{
  "$ref": "{?var1,var2}",
  "$vars": {
    "var1": "a",
    "var2": "b"
  }
}

Resulted $ref is ?var1=a&var2=b.

{
  "$ref": "?x=1&y=2{&var1,var2}",
  "$vars": {
    "var1": "a",
    "var2": "b"
  }
}

Resulted $ref is ?x=1&y=2&var1=a&var2=b.

Fragment

{
  "$ref": "{#var1}",
  "$vars": {
    "var1": "test"
  }
}

Resulted $ref is #test.

Modifier examples

Substrings

{
  "$ref": "{var:3}",
  "$vars": {
    "var": "test"
  }
}

Resulted $ref is tes.

Compositions

{
  "$ref": "{?address*}",
  "$vars": {
    "address": {
      "city": "Some city",
      "street": "Some street",
      "number": 5
    }
  }
}

Resulted $ref is ?city=Some%20city&street=Some%20street&number=5.