Improve documentation on file types, fixes #44

README.rst

@@ -278,6 +278,103 @@ KMS and PGP master keys defined in the file.
 
 	sops -r example.yaml
 
+Important information on types
+------------------------------
+
+YAML and JSON type extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`sops` uses the file extension to decide which encryption method to use on the file
+content. `YAML` and `JSON` files are treated as trees of data, and key/values are
+extracted from the files to only encrypt the leaf values. The tree structure is also
+used to check the integrity of the file.
+
+Therefore, if a file is encrypted using a specific format, it need to be decrypted
+in the same format. The easiest way to achieve this is to conserve the original file
+extension after encrypting a file. For example::
+
+	$ sops -e -i myfile.json
+	
+	$ sops -d myfile.json
+
+If you want to change the extension of the file once encrypted, you need to provide
+sops with the `--input-type` flag upon decryption. For example::
+
+	$ sops -e myfile.json > myfile.json.enc
+	
+	$ sops -d --input-type json myfile.json.enc
+
+YAML anchors
+~~~~~~~~~~~~
+`sops` only supports a subset of `YAML`'s many types. Encrypting YAML files that
+contain strings, numbers and booleans will work fine, but files that contain anchors
+will not work, because the anchors redefine the structure of the file at load time.
+
+This file will not work in `sops`:
+
+.. code:: yaml
+
+	bill-to:  &id001
+	    street: |
+	        123 Tornado Alley
+	        Suite 16
+	    city:   East Centerville
+	    state:  KS
+
+	ship-to:  *id001
+
+`sops` uses the path to a value as additional data in the AEAD encryption, and thus
+dynamic paths generated by anchors break the authentication step.
+
+JSON and TEXT file types do not support anchors and thus have no such limitation.
+
+Top-level arrays
+~~~~~~~~~~~~~~~~
+`YAML` and `JSON` top-level arrays are not supported, because `sops` needs a top-level
+`sops` key to store its metadata.
+This file will not work in sops:
+
+.. code:: yaml
+
+	---
+	  - some
+	  - array
+	  - elements
+
+But this one will because because the `sops` key can be added at the same level as the
+`data` key.
+
+.. code:: yaml
+
+	data:
+	  - some
+	  - array
+	  - elements
+
+Similarly, with `JSON` arrays, this document will not work:
+
+.. code:: json
+
+	[
+	  "some",
+	  "array",
+	  "elements"
+	]
+
+
+But this one will work just fine:
+
+.. code:: json
+
+	{
+	  "data": [
+	    "some",
+	    "array",
+	    "elements"
+	  ]
+	}
+
+
 Examples
 --------
 
@@ -428,24 +525,8 @@ With this in place, calls to `git diff` will decrypt both previous and current
 versions of the target file prior to displaying the diff. And it even works with
 git client interfaces, because they call git diff under the hood!
 
-Implementation details
-----------------------
-
-YAML types limitations
-~~~~~~~~~~~~~~~~~~~~~~
-
-`sops` only supports a subset of `YAML`'s many types. Encrypting YAML files that
-contain strings, numbers and booleans will work fine.
-
-Files that contain anchors will not work, because the anchors redefine the
-structure of the file at load time. `sops` uses the path to a value as
-additional data in the AEAD encryption, and thus dynamic paths generated by
-anchors break the authentication step.
-
-JSON and TEXT file types have no such feature and do not suffer this limitation.
-
-Encryption method
-~~~~~~~~~~~~~~~~~
+Encryption Protocol
+-------------------
 
 When sops creates a file, it generates a random 256 bit data key and asks each
 KMS and PGP master key to encrypt the data key. The encrypted version of the data