Table-Definitions.md

+# Table Definitions
+
+Table definitions is a JSON file used by HOTMapper to set the table's primary key(s) and foreign key(s). It's also used
+to fill the data of an auxiliary that stores information about the table's source. This source table is
+automatically created when you make your first table using HOTMapper.
+
+This JSON file needs to have the same name of the table + '.json' (Eg.: table_name.json) and be stored in the 
+TABLE_DEFINITIONS_FOLDER defined in the settings.py file, by default the folder location is hotmapper/table_definitions.
+
+The table_definitions JSON has four attributes in the following format:
+
+~~~json
+{
+  "pairing_description": "A string with the description of what this table stores.",
+  "data_source": "A string with the source of the data.",
+  "pk": ["A list with the primary key columns."],
+  "foreign_keys": ["A list with the foreign key columns."]
+}
+~~~
+
+* "pairing_description": <"string">
+  * Represents a brief description of what the table stores.
+
+* "data_source": <"string">
+  * The table's source.
+
+* "pk": <"list of strings, where each string represents a column of the table"> (Eg.: ["id", "year"])
+  * The table's primary key, it's needed at least one.
+
+* "foreign_keys": <"list of strings, where each string represents a column of the table">
+  * Foreign keys of the table, can have zero or more.
+  
+The hotmapper comes with an example of table definitions in the folder hotmapper/table_definitions, named 
+example_table_definition.json shown bellow.
+
+~~~json
+{
+  "pairing_description": "Table with the graduation rates, which represent a percentage of students expected to graduate, used to learn the HOTMapper Tool",
+  "data_source": "Open data made by Sustainable Development Solutions Network",
+  "pk": ["cod_country", "year", "gender", "isced"],
+  "foreign_keys": []
+}
+~~~
\ No newline at end of file