ED03 - Diary Format: JSON Artefacts, Temporal Signature, V7GUID, Sidecars

Problem

An entrepreneur wants to keep their diary in Git - but what exactly does an entry look like technically? Today's practice knows no binding answer:

• Free-text notes in Markdown, Word or paper - not machine-readable, not schema-validated, not traceable
• Excel rows with date, activity, hours - not versioned, not cryptographically anchored, not auditable
• Payroll-software exports as PDF - not machine-evaluable (§ 147 Abs. 6 AO), not retrogradely/progressively traceable
• No unique identity - every entry has a file name, but the file name can change; the identity of the entry is not stable
• No temporal anchoring - the date is a string in the document, but who recorded what when? The recording time is not cryptographically linked to the identity

Core Statement

A GitCover diary entry is a JSON artefact with:

1. JSON-Schema-First - the schema exists before the entry; the entry is validated against the schema (Pre-Commit hook)
2. V7GUID (Class Identifier) - classifies the document/action based on the .gitcover registry (what/which type); serves storage organisation and DB query (e.g. EF Core in a Vertical App)
3. uuidV7 (Object ID) - is already alone the unique identity (DocID) of the entry, RFC 9562 §5.7, generated from a predefined timestamp (not now()) via GitCover helper (UuidV7Gen), rest filled with randomness
4. Composite Key V7GUID:uuidV7 - the GCPN Sidecar Composite Key, serves storage organisation and query; the recording time is in the uuidV7 (48-bit timestamp), no separate datetime/date field
5. Sidecar obligation - every document receives a .v7g.md sidecar with its own uuidV7 (classification act) and the uuidV7 of the document
6. Retrograde/progressive traceability - resolvable from the booking record → document → diary entry → uuidV7 and back

Compliance by Design: The format is not after the fact - it is structural. Schema, V7GUID (Class), uuidV7 (Object) and sidecar are mandatory fields, without which an entry is not admitted to the repo.

No redundant datetime/date: The recording time is anchored in the uuidV7 itself (48-bit timestamp, RFC 9562 §5.7). A separate string representation in JSON schemas or JSON data is redundant and is not kept in the facts. String representation for DTO/HTMX transfer is the harness's responsibility, not the facts layer.

The JSON Schema (Schema-First)

The schema exists before the entry - it is stored in .gitcover/schemas/diary-entry-1.0.schema.json and is versioned. An entry without a schema reference ($schema) is rejected by the Pre-Commit hook.

Schema diary-entry-1.0.schema.json (simplified)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gitcover.org/schemas/diary-entry-1.0.schema.json",
  "title": "GitCover Diary Entry v1.0",
  "type": "object",
  "required": [
    "$schema", "V7GUID", "uuidV7",
    "author", "role", "tenant", "sphere", "source"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "const": "https://gitcover.org/schemas/diary-entry-1.0.schema.json"
    },
    "V7GUID": {
      "type": "string",
      "description": "Class Identifier - klassifiziert das Dokument/die Action aus .gitcover Registry (was/welcher Typ)"
    },
    "uuidV7": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "Object ID - RFC 9562 §5.7 UUIDv7, generiert aus vorgegebener Zeitmarke (nicht now()), 48-Bit-Zeitstempel in der GUID verankert"
    },
    "author": { "type": "string", "description": "Akteur-Platzhalter, z. B. E1" },
    "role": {
      "type": "string",
      "enum": ["GF", "Buchhalter", "Lohnverantwortlicher", "F&E-Leiter", "Administrator"]
    },
    "tenant": { "type": "string", "description": "Tenant-Platzhalter, z. B. ORG-1" },
    "sphere": {
      "type": "string",
      "enum": ["ideell", "vermögensverwaltend", "zweckbetrieblich", "wirtschaftlich", "n/a"]
    },
    "source": {
      "type": "string",
      "enum": ["E1", "StB", "Notar", "Bank", "DRV", "FA", "BA", "VBG", "KK", "auto"]
    },
    "source_sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "SHA-256 des referenzierten Belegs (eindeutige Beleg-ID)"
    },
    "tags": { "type": "array", "items": { "type": "string" } }
  }
}

Important - no datetime/date field: The recording time is in the uuidV7 (48-bit timestamp, RFC 9562 §5.7). A separate string representation is redundant and is not kept in the facts. The uuidV7 alone is the unique DocID; the Composite Key V7GUID:uuidV7 serves storage organisation and DB query.

V7GUID - Structure and 48-bit Timestamp

Core principle: The 48-bit timestamp component (bits 0-47) is authoritative for the recording time. It is anchored in the uuidV7 itself and cannot be changed afterwards without invalidating the GUID. A separate datetime field does not exist - the time is in the uuidV7. String representation for DTO/HTMX is the harness's responsibility.

GitCover Extension: Hierarchy and Process IDs in Bits 66-127

The GitCover V7GUID specification (work/OSS/TOP/.gitcover/specs/v7guid/) extends the 62-bit random component (bits 66-127) with a 6-level hierarchy and process IDs - this is the patent-protected extension (DPMA Az. 10 2025 003 091.6):

Note: This extension is not mandatory for the diary series - it becomes relevant in ED02 (Tenant/Sphere/Role) and later articles (Harness). Here the RFC 9562 basis with 48-bit timestamp suffices.

Helper Routines: Creating V7GUID from Foreign Keys

The GitCover OSS tool UuidV7Gen (work/OSS/TOP/tools/UuidV7Gen/) provides two central operations:

gen - generate uuidV7 (guid)

# Erzeugt eine neue uuidV7 mit vorgegebener Zeitmarke (nicht now())
# Zeitmarke z. B. aus Dateiname "260815_0900" → ISO 2026-08-15T09:00:00Z
uuidv7gen gen "2026-08-15T09:00:00Z" "Tagebucheintrag-260815"

# Ausgabe: Label;UUID;ISO-Zeitstempel
# Tagebucheintrag-260815;019f2c6f-0900-7000-8000-000000000000;2026-08-15T09:00:00.000Z

decode - extract timestamp from uuidV7

# Extrahiert den 48-Bit-Zeitstempel aus einer uuidV7
uuidv7gen decode 019f2c6f-0900-7000-8000-000000000000

# Ausgabe: ISO-8601-Zeitstempel
# 2026-08-15T09:00:00.000Z

Foreign Key → uuidV7

The helper routines allow creating a valid uuidV7 key from a foreign key (e.g. a timestamp in the file name like 260815_0900_Lohnabrechnung.pdf) - with a predefined timestamp, not now():

1. Parse foreign key - 260815_0900 → 2026-08-15T09:00:00Z
2. Compute 48-bit timestamp - Unix milliseconds since Epoch
3. Generate uuidV7 - Guid.CreateVersion7() with explicit timestamp, rest with randomness
4. Composite Key - V7GUID (Class from registry) : uuidV7 (Object with timestamp)
5. GoBD documentation - timely recording traceably anchored (no separate datetime field)

GoBD reference: The timely recording (GoBD Rz. 146) is cryptographically documented by the 48-bit timestamp in the uuidV7 - not merely claimed. The timestamp is part of the identity, not modifiable afterwards.

Sidecar Structure (.v7g.md)

Every document receives a sidecar with two uuidV7 references:

Sidecar Example

{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-1.0.schema.json",
  "V7GUID": "<V7GUID-Class-aus-Registry>",
  "uuidV7": "019f2c6f-0900-7001-8000-000000000001",
  "sha256": "ab94670c0dd8499c27ef2feddd1d9c5925977d55a52150a6fca0f6567d2e5e79",
  "title": "260815_Lohnabrechnung.pdf",
  "original_filename": "260815_Lohnabrechnung.pdf",
  "locations": [
    {
      "unc_path": "./ORG-1/sources/lohn/260815_Lohnabrechnung.pdf",
      "from": "260815",
      "to": null,
      "note": "Primärspeicherort"
    }
  ],
  "v7g_taxonomy": [
    {
      "v7guid": "019f2c6f-0900-7000-8000-000000000000",
      "taxonomy": "ORG-1/Lohn",
      "valid_from": "260815",
      "valid_to": null,
      "note": "Tenant: ORG-1, Category: Lohn, Sphäre: ideell"
    }
  ],
  "gcpn": {
    "prima_nota_ref": null,
    "journal_entry_ref": null
  },
  "obsolescence": {
    "status": "active",
    "superseded_by": null,
    "superseded_at": null
  }
}

Composite Key V7GUID:uuidV7:

• V7GUID (field 1) - Class Identifier of the sidecar (classification from .gitcover registry: what/which type)
• uuidV7 (field 2) - Object ID of the sidecar itself, generated with a predefined timestamp (when was it classified?), 48-bit timestamp anchored in the GUID
• v7g_taxonomy[].v7guid - Object ID of the classified document (which document is being classified?)

This makes not only the document uniquely identified, but also the classification act itself - including the point in time (in uuidV7), who classified and in which role. No separate datetime field - the time is in the uuidV7 values.

Retrograde and Progressive Traceability

GoBD reference: Retrograde traceability corresponds to GoBD Rz. 146 (traceability). Progressive traceability corresponds to GoBD Rz. 147 (auditability). Both are guaranteed by Design through uuidV7 + SHA-256 - not through manual cross-references.

Time Recording in the Diary

Every diary entry contains a time-recording table:

FZul reference: Time recording is the basis for FZul hour records (ED18). The R&D vs. administration separation is done via the role field (F&E-Leiter vs. GF) and the tags (["fzul", "forschung"] vs. ["verwaltung"]).

What Lands in the Git Repo - and What Does Not

Important: Only structured artefacts (JSON, sidecars, documents, schemas, dictionaries) are admitted to the Git repo. Private documents are never admitted to the repo unless they have been explicitly introduced and classified as artefacts. This is a data protection and compliance requirement (GDPR, GoBD).

Risk Leverage

Harness Requirements (Preview)

Derivable from ED03:

The full requirements list in Harness-Anforderungen.md.

Sources

• RFC 9562 §5.7 (UUIDv7) - 48-bit Unix-ms timestamp
• V7GUID specification - work/OSS/TOP/.gitcover/specs/v7guid/ (normative)
• DPMA Az. 10 2025 003 091.6 - V7GUID patent (main claim 2, claims 5-8)
• GitCover OSS tool UuidV7Gen - work/OSS/TOP/tools/UuidV7Gen/ (helper gen/decode)
• GoBD (BMF letter, Rz. 146 - traceability, Rz. 147 - auditability)
• AO (§ 147 Abs. 2 - "machine-evaluable", § 147 Abs. 6 - data access)
• AFJD/agents/ (anonymised) - SSoT concept with JSON artefacts, sidecars

Source Topology and CDN Reference Links

Note: This assignment of sources, mirror and community hub reflects the current state and may change. Please check the respective canonical source on gitcover.org for the current state.