From 4cb5626d9ee66de7d11619d12e3342dfa30c5bf0 Mon Sep 17 00:00:00 2001 From: Aaron Lehmann Date: Mon, 24 Aug 2015 16:27:40 -0700 Subject: [PATCH] Update JSON spec to point out escaping of <, >, & ...and add blurb about not relying on canonicalization to ensure identical output. Signed-off-by: Aaron Lehmann --- docs/spec/json.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/spec/json.md b/docs/spec/json.md index a7b1807f3..a8916dccc 100644 --- a/docs/spec/json.md +++ b/docs/spec/json.md @@ -17,6 +17,10 @@ To provide consistent content hashing of JSON objects throughout Docker Distribution APIs, the specification defines a canonical JSON format. Adopting such a canonicalization also aids in caching JSON responses. +Note that protocols should not be designed to depend on identical JSON being +generated across different versions or clients. The canonicalization rules are +merely useful for caching and consistency. + ## Rules Compliant JSON should conform to the following rules: @@ -28,6 +32,8 @@ Compliant JSON should conform to the following rules: keys shall always appear in lexically sorted order. 4. All whitespace between tokens should be removed. 5. No "trailing commas" are allowed in object or array definitions. +6. The angle brackets "<" and ">" are escaped to "\u003c" and "\u003e". + Ampersand "&" is escaped to "\u0026". ## Examples