# 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)