Add README part 1

README.md

@@ -0,0 +1,83 @@
+# TerraSchema
+
+TerraSchema (or `terraschema`) is a CLI tool which scans Terraform configuration (`.tf`)
+files, parses a list of variables along with their type and validation rules, and converts
+them to a schema which complies with 
+[JSON Schema Draft-07](https://json-schema.org/draft-07/json-schema-release-notes).
+
+### Installation
+
+To install this application, do
+```
+$ go install github.com/HewlettPackard/terraschema@latest
+```
+or alternatively, download the correct binary for your PC from the [releases](https://github.com/HewlettPackard/terraschema/releases) tab.
+
+### Motivation
+
+JSON Schema files can be used to validate a `.tfvars.json` file without the need to run `terraform plan`. 
+Some applications can also use JSON schema to generate a web form to enter variables, such as 
+[react-jsonschema-form](https://github.com/rjsf-team/react-jsonschema-form). To validate a JSON file
+against a schema, [santhosh-tekuri/jsonschema](https://github.com/santhosh-tekuri/jsonschema) can be
+used, for example:
+
+```
+$ go install github.com/santhosh-tekuri/jsonschema/cmd/jv@latest
+$ jv schema.json input.tfvars.json
+```
+
+Once a valid `.tfvars.json` file has been created, it can then be used in terraform with
+```
+$ terraform plan -var-file="input.tfvars.json"
+$ terraform apply -var-file="input.tfvars.json"
+$ terraform destroy -var-file="input.tfvars.json"
+```
+(see [Terraform Input Variables](https://developer.hashicorp.com/terraform/language/values/variables#variable-definitions-tfvars-files)).
+
+In the majority of use-cases, any input file which validates against the JSON Schema 
+generated by this application will also be a valid input file to the terraform module itself.
+The main exceptions to this are certain classes of validation rules, which JSON Schema
+do not directly support (see Custom Validation Rules).
+
+# CLI Usage
+
+The default behaviour of TerraSchema is to scan the current directory for Terraform 
+configuration files, and create a file called `schema.json` at the same location. It 
+returns an error if no Terraform configuration files are present, or if no variables 
+are defined within those files. Variable are marked as `required` in the Schema only 
+if they don't have a default value set, and additional variables are permitted. 
+
+Note: an `input.tfvars.json` file with additional variables (ones which don't correspond
+to an existing variable in the Terraform configuration) will generate a warning when
+running Terraform.
+
+### Flags
+
+- `-h`, `--help`: Print help instructions.
+
+- `-i`, `--input`: The root directory of the terraform module. Note: only files contained
+  in the root folder will be scanned. This is consistent with the behaviour of terraform modules.
+
+- `-o`, `--output`: The output file for the schema file. Should be in the form `path/to/schema.json`.
+
+- `--allow-empty`: Allow an empty schema (`{}`) to be created if no `.tf` files or variables are found.
+
+- `--disallow-additional-properties`: Set additionalProperties to false in the root object and nested objects
+  (see [JSON Schema definition](https://json-schema.org/understanding-json-schema/reference/object#additionalproperties)).
+
+- `--overwrite`: Allow overwriting an existing file at the output location.
+
+- `--debug`: Print debug logs for variable retrieval and errors related to custom validation rules.
+
+- `--stdout`: Print schema to stdout and prevent all other logging unless an error occurs. Does not create a file.
+  Overrides `--debug` and `--output`.
+
+# Design
+
+### Parsing Terraform Configuration Files
+
+### Custom Validation Rules
+
+### Translating Types to JSON Schema
+
+### Nullable Variables