codecs

Type Members

1. class InlineStringCodec extends DataCodec

   

   Provides a URL "Friendly" string encoding of data.

   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.

   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.:

   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.
   }