Provides a URL "Friendly" string encoding of data.
This encoding aims to strike a balance between:
- Safety, convenience and brevity when used on the URL
- JSON equivalence
To that end, this encoding:
- Guarantees that equivalent data is also string equivalent.
- Does not use any URL reserved chars in the core syntax.
- Does not require quoting of string primitives.
In order to achieve this, the encoding has a few constraints:
- All map keys must be sorted in alpha-numeric order for serialization.
- Extraneous whitespace is not allowed.
- Primitives must be represented in "canonical form". For example there may be no leading or
trailing zeros on numeric types.
This encoding also has a few limitations:
- Serialized data must be URL encoded before being used in URLs, but only to escape chars that
might appear in string literals.
- It is lossy: All primitives types are downgraded to plain strings, but can be "fixed-up",
this is explained in detail below.
- An array containing a single empty string ([""] in JSON), has the special representation of
List(~) in this format. This is to prevent an ambiguity between an empty list and a list
containing a single empty string.
Pegasus provides "Fix-up" to convert plain strings used in this format
back to their correct primitive types. It is recommended that fix-up be run on all
data deserialized from this format, e.g.:
val validationResult =
ValidateDataAgainstSchema.validate(
dataMap,
schema,
new ValidationOptions(
RequiredMode.FIXUP_ABSENT_WITH_DEFAULT,
CoercionMode.STRING_TO_PRIMITIVE))
if (validationResult.isValid) {
// The data map is now fixed up, if it has been marked as ReadOnly,// use validationResult.getFixed to get the fixed-up copy, otherwise dataMap// will be fixed up in-place.
}
Provides a URL "Friendly" string encoding of data.
This encoding aims to strike a balance between:
- Safety, convenience and brevity when used on the URL - JSON equivalence
To that end, this encoding:
- Guarantees that equivalent data is also string equivalent. - Does not use any URL reserved chars in the core syntax. - Does not require quoting of string primitives.
In order to achieve this, the encoding has a few constraints:
- All map keys must be sorted in alpha-numeric order for serialization. - Extraneous whitespace is not allowed. - Primitives must be represented in "canonical form". For example there may be no leading or trailing zeros on numeric types.
This encoding also has a few limitations:
- Serialized data must be URL encoded before being used in URLs, but only to escape chars that might appear in string literals. - It is lossy: All primitives types are downgraded to plain strings, but can be "fixed-up", this is explained in detail below. - An array containing a single empty string (
[""]
in JSON), has the special representation ofList(~)
in this format. This is to prevent an ambiguity between an empty list and a list containing a single empty string.JSON Encoding | Inline String Encoding ----------------------------------|---------------------------------------
{ "a": "one", "b": "two"}
|(a~one,b~two)
[1, 2, 3]
|List(1,2,3)
{ "ids": [1,2], "score": 3.14 }
|(ids~List(1,2),score~3.14)
Escaping:
When used in strings the reserved chars
(),~!
must be escaped by prefixing them with!
.JSON Encoding | Inline String Encoding -------------------------------------|---------------------------------------
{ "string": "~An (odd) string !" }
|(string~!~An !(odd!) string !!)
Fix up:
Pegasus provides "Fix-up" to convert plain strings used in this format back to their correct primitive types. It is recommended that fix-up be run on all data deserialized from this format, e.g.: