1 files changed, 176 insertions, 0 deletions
diff --git a/doc/11-FileFormats.md b/doc/11-FileFormats.md
new file mode 100644
index 0000000..5147ceb
--- /dev/null
+++ b/doc/11-FileFormats.md
@@ -0,0 +1,176 @@
+<a id="FileFormats"></a> Supported File Formats
+===============================================
+
+Depending on the installed libraries the Import Source currently supports
+multiple file formats. In case you're missing any of the following formats
+in your Director frontend please re-read our [Installation instructions](02-Installation.md).
+
+
+CSV (Comma Separated Value)
+---------------------------
+
+[CSV](https://en.wikipedia.org/wiki/Comma-separated_values) is a not so well
+defined data format, therefore the Import Source has to make some assumptions
+and ask for optional settings.
+
+Basically, the rules to follow are:
+
+* a header line is required
+* each row has to have as many columns as the header line
+* defining a value enclosure is mandatory, but you do not have to use it in your
+  CSV files. So while your import source might be asking for `"hostname";"ip"`,
+  it would also accept `hostname;ip` in your source files
+* a field delimiter is required, this is mostly comma (`,`) or semicolon (`;`).
+  You could also opt for other separators to fit your very custom file format
+  containing tabular data
+
+### Sample CSV file
+
+```csv
+"host","address","location"
+"csv1.example.com","127.0.0.1","HQ"
+"csv2.example.com","127.0.0.2","HQ"
+"csv3.example.com","127.0.0.3","HQ"
+```
+
+### More complex but perfectly valid CSV sample
+
+```csv
+"hostname","ip address","location"
+csv1,"127.0.0.2","H\"ome"
+"csv2",127.0.0.2,"asdf"
+"csv3","127.0.0.3","Nott"", at Home"
+```
+
+
+JSON - JavaScript Object Notation
+---------------------------------
+
+[JSON](https://en.wikipedia.org/wiki/JSON) is a pretty simple standarized format
+with good support among most scripting and programming languages. Nothing special
+to say here, as it is easy to validate.
+
+### Simple JSON example
+
+This example shows an array of objects:
+
+```json
+[{"host": "json1", "address": "127.0.0.1"},{"host": "json2", "address": "127.0.0.2"}]
+```
+
+This is the easiest machine-readable form of a JSON import file.
+
+
+### Pretty-formatted extended JSON example
+
+Single-line JSON files are not very human-friendly, so you'll often meet pretty-
+printed JSON. Such files also make also prefectly valid import candidates:
+
+```json
+{
+  "json1.example.com": {
+    "host": "json1.example.com",
+    "address": "127.0.0.1",
+    "location": "HQ",
+    "groups": [ "Linux Servers" ]
+  },
+  "json2.example.com": {
+    "host": "json2.example.com",
+    "address": "127.0.0.2",
+    "location": "HQ",
+    "groups": [ "Windows Servers", "Lab" ]
+  }
+}
+```
+
+Microsoft Excel
+---------------
+
+XSLX, the Microsoft Excel 2007+ format is supported since v1.1.0.
+
+
+XML - Extensible Markup Language
+--------------------------------
+
+When working with [XML](https://en.wikipedia.org/wiki/XML) please try to ship
+simple files as shown in the following example. We'd love to add more features
+like better attribute support or [XPath](https://en.wikipedia.org/wiki/XPATH)-
+based filters. In case you need such, please let us know and ship some exmple
+data, helping us to better understand your requirements!
+
+### Simple XML example
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?> 
+<hosts>
+  <host>
+    <name>xml1</name>
+    <address>127.0.0.1</address>
+  </host>
+  <host>
+    <name>xml2</name>
+    <address>127.0.0.2</address>
+  </host>
+</hosts>
+```
+
+
+YAML (Ain't Markup Language)
+----------------------------
+
+[YAML](https://en.wikipedia.org/wiki/YAML) is all but simple and well defined,
+it allows you to write the same data in various ways. In case you opt for it
+you might have your reasons and should already be familiar with how to generate
+such files.
+
+### Simple YAML example
+
+So, let's start with a simple example:
+
+```yaml
+---
+- host: "yaml1.example.com"
+  address: "127.0.0.1"
+  location: "HQ"
+- host: "yaml2.example.com"
+  address: "127.0.0.2"
+  location: "HQ"
+- host: "yaml3.example.com"
+  address: "127.0.0.3"
+  location: "HQ"
+```
+
+### Advanced YAML example
+
+People who think that NoSQL solves all there data problems tend to believe that
+YAML solve all their config problems. So, YAML is pretty hip and widely used
+among tools in hyped niches such as configuration management. I'll pick [Puppet](https://puppet.com/)
+as an example, but this might work in a similar way for many other tools.
+
+Instead of a single YAML file I have to deal with a directory full of files in
+this case. Our [Import Source documentation](03-ImportSource.md) already shows
+how to configure such, here you can see part of such a file:
+
+```yaml
+--- !ruby/object:Puppet::Node::Facts
+  name: foreman.localdomain
+  values: 
+    architecture: x86_64
+    timezone: CEST
+    kernel: Linux
+    system_uptime: "{\x22seconds\x22=>5415, \x22hours\x22=>1, \x22days\x22=>0, \x22uptime\x22=>\x221:30 hours\x22}"
+    domain: localdomain
+    virtual: kvm
+    is_virtual: "true"
+    hardwaremodel: x86_64
+    operatingsystem: CentOS
+    facterversion: "2.4.6"
+    filesystems: xfs
+    fqdn: foreman.localdomain
+    hardwareisa: x86_64
+    hostname: foreman
+```
+
+If this looks foreign to you don't worry, most similar constructs are handled in
+a smooth way by the underlying YAML parser.
+