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 knows no authoritative 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 traceable retrogradely/progressively
• No unique identity - every entry has a filename, but the filename can change; the identity of the entry is not stable
• No temporal anchoring - the date stands as a string in the document, but who actually recorded it, and when? The recording time is not cryptographically linked to the identity

Core statement

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 based on the .gitcover registry (what/which type); serves filing organization and DB query (e.g., EF Core in Vertical App)
3. uuidV7 (Object ID) - is already by itself the unique identity (DocID) of the entry, RFC 9562 §5.7, generated from a predetermined timestamp (or now()) via the GitCover helper (UuidV7Gen), remainder filled with randomness
4. Composite key V7GUID:uuidV7 - the GCPN sidecar composite key, serves filing organization and query; the recording time is embedded in the uuidV7 (48-bit timestamp), no separate datetime/date field
5. Mandatory sidecar - 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 level.

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 filing organization 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 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 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 filename such as 260815_0900_Lohnabrechnung.pdf) - with a predetermined timestamp, not now():

1. Parse the foreign key - 260815_0900 → 2026-08-15T09:00:00Z
2. Calculate the 48-bit timestamp - Unix milliseconds since epoch
3. Generate the uuidV7 - Guid.CreateVersion7() with 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 claimed. 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 predetermined 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 way, not only the document is 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 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: Time recording is the basis for the FZul hour records (ED28). 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 ends up in the Git repo - and what does not

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

Risk leverage

Harness requirement (preview)

Derivable from ED03:

The complete 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/ (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 mapping 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.