github.com/mika/distribution@v2.2.2-0.20160108133430-a75790e3d8e0+incompatible/docs/spec/json.md (about)

     1  <!--[metadata]>
     2  +++
     3  draft=true
     4  title = "Docker Distribution JSON Canonicalization"
     5  description = "Explains registry JSON objects"
     6  keywords = ["registry, service, images, repository,  json"]
     7  [menu.main]
     8  parent="smn_registry_ref"
     9  +++
    10  <![end-metadata]-->
    11  
    12  
    13  
    14  # Docker Distribution JSON Canonicalization
    15  
    16  To provide consistent content hashing of JSON objects throughout Docker
    17  Distribution APIs, the specification defines a canonical JSON format. Adopting
    18  such a canonicalization also aids in caching JSON responses.
    19  
    20  Note that protocols should not be designed to depend on identical JSON being
    21  generated across different versions or clients. The canonicalization rules are
    22  merely useful for caching and consistency.
    23  
    24  ## Rules
    25  
    26  Compliant JSON should conform to the following rules:
    27  
    28  1. All generated JSON should comply with [RFC
    29     7159](http://www.ietf.org/rfc/rfc7159.txt).
    30  2. Resulting "JSON text" shall always be encoded in UTF-8.
    31  3. Unless a canonical key order is defined for a particular schema, object
    32     keys shall always appear in lexically sorted order.
    33  4. All whitespace between tokens should be removed.
    34  5. No "trailing commas" are allowed in object or array definitions.
    35  6. The angle brackets "<" and ">" are escaped to "\u003c" and "\u003e".
    36     Ampersand "&" is escaped to "\u0026".
    37  
    38  ## Examples
    39  
    40  The following is a simple example of a canonicalized JSON string:
    41  
    42  ```json
    43  {"asdf":1,"qwer":[],"zxcv":[{},true,1000000000,"tyui"]}
    44  ```
    45  
    46  ## Reference
    47  
    48  ### Other Canonicalizations
    49  
    50  The OLPC project specifies [Canonical
    51  JSON](http://wiki.laptop.org/go/Canonical_JSON). While this is used in
    52  [TUF](http://theupdateframework.com/), which may be used with other
    53  distribution-related protocols, this alternative format has been proposed in
    54  case the original source changes. Specifications complying with either this
    55  specification or an alternative should explicitly call out the
    56  canonicalization format. Except for key ordering, this specification is mostly
    57  compatible.
    58  
    59  ### Go
    60  
    61  In Go, the [`encoding/json`](http://golang.org/pkg/encoding/json/) library
    62  will emit canonical JSON by default. Simply using `json.Marshal` will suffice
    63  in most cases:
    64  
    65  ```go
    66  incoming := map[string]interface{}{
    67      "asdf": 1,
    68      "qwer": []interface{}{},
    69      "zxcv": []interface{}{
    70          map[string]interface{}{},
    71          true,
    72          int(1e9),
    73          "tyui",
    74      },
    75  }
    76  
    77  canonical, err := json.Marshal(incoming)
    78  if err != nil {
    79    // ... handle error
    80  }
    81  ```
    82  
    83  To apply canonical JSON format spacing to an existing serialized JSON buffer, one
    84  can use
    85  [`json.Indent`](http://golang.org/src/encoding/json/indent.go?s=1918:1989#L65)
    86  with the following arguments:
    87  
    88  ```go
    89  incoming := getBytes()
    90  var canonical bytes.Buffer
    91  if err := json.Indent(&canonical, incoming, "", ""); err != nil {
    92  	// ... handle error
    93  }
    94  ```