coderkun/timefiles
1
0
Fork 0
Code Issues Pull requests Releases Activity

Add schema description and JSON schema files

Browse source
This commit is contained in:
Olli 2025-08-28 14:36:47 +02:00
commit 529efb3668
4 changed files with 156 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

76
README.md Normal file
View file

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

22
schema/activity.json Normal file
View file

@ -0,0 +1,22 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://www.suruatoel.xyz/codes/protime/activity.json",
"title": "Activity",
"description": "An activity entry",
"type": "object",
"properties": {
"id": {
"description": "",
"type": "string",
"format": "uuid"
},
"title": {
"description": "",
"type": "string"
}
},
"required": [
"id",
"title"
]
}

22
schema/project.json Normal file
View file

@ -0,0 +1,22 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://www.suruatoel.xyz/codes/protime/project.json",
"title": "Project",
"description": "A project entry",
"type": "object",
"properties": {
"id": {
"description": "",
"type": "string",
"format": "uuid"
},
"title": {
"description": "",
"type": "string"
}
},
"required": [
"id",
"title"
]
}

36
schema/time.json Normal file
View file

@ -0,0 +1,36 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://www.suruatoel.xyz/codes/protime/time.json",
"title": "Time",
"description": "A time entry",
"type": "object",
"properties": {
"id": {
"description": "",
"type": "string",
"format": "uuid"
},
"project": {
"description": "",
"type": "string"
},
"activity": {
"description": "",
"type": "string"
},
"start": {
"description": "",
"type": "string",
"format": "date-time"
},
"end": {
"description": "",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"start"
]
}