Add schema description and JSON schema files

README.md

@@ -0,0 +1,76 @@
+# Time Files
+
+Time Files is both a specification and a reference implementation for tracking
+project time.
+
+## Schema
+
+All data is stored in JSON files using `.json` as file extension. Each entity
+uses its own folder with each instance in a dedicated file. For some entities
+sub-folders are used.
+
+Files and folders are structured as follows:
+
+    projects
+        <projectA-uuid>.json
+        <projectB-uuid>.json
+    activities
+        <projectA-uuid>/
+            <activityX-uuid>.json
+            <activityY-uuid>.json
+        <projectB-uuid>/
+            <activityM-uuid>.json
+            <activityN-uuid>.json
+    times/
+        <year>/
+            <month>/
+                <day>/
+                    <time1-uuid>.json
+                    <time2-uuid>.json
+                    <time3-uuid>.json
+        timer.json
+
+Project files are stored in a “projects” folder using the UUID as file name and
+the following content:
+
+```json
+{
+    "id": "UUID of the project",
+    "title": "Human-readable title"
+}
+```
+
+Activity files are stored in an “activities” folder with the UUID of the project
+they belong to as sub-folder. They have the following content:
+
+```json
+{
+    "id": "UUID of the activity",
+    "title": "Human-readable title"
+}
+```
+
+Time files are stored in a “times” folder with sub-folders for the year, the
+month and the day. If a time entry spans across multiple days, it has to be
+split. They have the following content:
+
+```json
+{
+    "id": "UUID of the time entry",
+    "project": "UUID of the project (optional)",
+    "activity": "UUID of the activity (optional)",
+    "start": "Start time in ISO format",
+    "end": "End time in ISO format (optional)"
+}
+```
+
+Additionally, the file “timer.json” is stored in the “times” folder containing
+the currently active time tracking. End `end` property is empty in that case.
+Both `project` and `activity` can be empty as well to allow both to be set after
+starting time tracking.
+
+The file schemata are available as JSON schema:
+
+* [project](./schema/project.json)
+* [activity](./schema/activity.json)
+* [time](./schema/time.json)