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

Problem

An entrepreneur wants to keep their diary in Git - but what exactly does an entry look like technically? Current practice offers 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 audit-proof
• Payroll software exports as PDF - not machine-evaluable (§ 147 Abs. 6 AO), not retrogradely/progressively traceable
• No unique identity - each 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 stored as a string in the document, but who actually recorded what, and when? The recording time is not cryptographically linked to the identity

Key Message

A GitCover diary entry is a JSON artifact 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 according to the .gitcover registry (what/which type); serves for filing organization and DB queries (e.g., EF Core in the Vertical App)
3. uuidV7 (Object ID) - is already in itself the unique identity (DocID) of the entry, RFC 9562 §5.7, generated from a preset timestamp (or now()) via the GitCover helper (UuidV7Gen), remainder filled with randomness
4. Composite key V7GUID:uuidV7 - the GCPN sidecar composite key, serves for filing organization and queries; the recording time is embedded in the uuidV7 (48-bit timestamp), no separate datetime/date field
5. Sidecar requirement - every voucher receives a .v7g.md sidecar with its own uuidV7 (classification act) and the uuidV7 of the document
6. Retrograde/progressive traceability - resolvable from booking entry → voucher → diary entry → uuidV7 and back

Compliance by Design: The format is not retrofitted - it is structural. Schema, V7GUID (Class), uuidV7 (Object), and sidecar are mandatory fields without which an entry is not accepted into 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 maintained 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 embedded in the uuidV7 (48-bit timestamp, RFC 9562 §5.7). A separate string representation is redundant and is not maintained in the facts. The uuidV7 alone is the unique DocID; the composite key V7GUID:uuidV7 serves for filing organization and DB queries.

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 retroactively without invalidating the GUID. A separate datetime field does not exist - the time is embedded 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 strictly required for the diary series - it becomes relevant in ED02 (tenant/sphere/role) and later articles (Harness). Here, the RFC 9562 basis with the 48-bit timestamp suffices.

Helper Routines: Creating V7GUIDs 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 such as 260815_0900_Lohnabrechnung.pdf) - with a preset timestamp, not now():

1. Parse the foreign key - 260815_0900 → 2026-08-15T09:00:00Z
2. Compute the 48-bit timestamp - Unix milliseconds since epoch
3. Generate the uuidV7 - Guid.CreateVersion7() with an explicit timestamp, remainder filled 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: Timely recording (GoBD Rz. 146) is cryptographically documented by the 48-bit timestamp in the uuidV7 - not merely asserted. The timestamp is part of the identity and cannot be changed retroactively.

Sidecar Structure (.v7g.md)

Every voucher 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 the .gitcover registry: what/which type)
• uuidV7 (field 2) - Object ID of the sidecar itself, generated with a preset timestamp (when was the classification made?), 48-bit timestamp anchored in the GUID
• v7g_taxonomy[].v7guid - Object ID of the classified document (which document is being classified?)

This way, not only is the document uniquely identified, but also the classification act itself - including the point in time (in uuidV7), who performed the classification, and in what role. No separate datetime field - the time is embedded 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: The time recording is the basis for FZul hour records (ED18). The separation of R&D vs. administration is done via the role field (F&E-Leiter vs. GF) and the tags (["fzul", "forschung"] vs. ["verwaltung"]).

What Goes into the Git Repo - and What Does Not

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

Risk Leverage

Harness Requirements (Preview)

Derivable from ED03:

The complete requirements list is 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/ (helpers gen/decode)
• GoBD (BMF letter, Rz. 146 - traceability, Rz. 147 - auditability)
• AO (§ 147 Abs. 2 - "machine-evaluable", § 147 Abs. 6 - data access)
• AFJD/agents/ (anonymized) - SSoT concept with JSON artifacts, 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.