Object versioning and audit fields

Introduction

This guide explains how geoscience objects handle versioning and the audit fields that track when and who creates, modifies, and deletes objects.

Overview

Every geoscience object has audit fields that track its lifecycle:

• created_at/created_by: Initial creation information
• modified_at/modified_by: Latest modification (versioning) information
• deleted_at/deleted_by: Deletion (recycling) information
• version_id: A numeric identifier for each version (larger means newer)

Versioning behavior

Understanding objects and versions

• Object: The geoscience data content itself (schema, UUID, name, description, and scientific data)
• Versions: Individual revisions of that object's content

Every geoscience object maintains history through versioning. The object itself has a fixed UUID that never changes, while each modification creates a new version with its own timestamp-based identifier. You can track both the current state of an object and its previous states over time, through versions. Each time you complete an update to an object's content (using the update object endpoint), a new version is created.

Every update operation creates a new version, regardless of whether the content has changed.

Audit field behavior

created_at and created_by

These fields reflect the initial creation of the object:

• On the object level, these always show when the first version was created and by whom (e.g. seen on the List Geoscience Objects endpoint)
• On the version level, each version has its own created_at/created_by fields showing when that specific version was created and by whom (e.g. seen on the Listing Versions endpoint)
• The created_at/created_by values never change

modified_at and modified_by

These fields track the latest modification to the object:

• When a new version is created (via update)
• The object's modified_at/modified_by always match the created_at/created_by of the most recent version
• Updating object stages or other metadata properties does not affect these fields

Example after creating a second version:

{
    "object_id": "9fd1cb16-ac0b-40a6-b9ee-89a5d702bce0",
    "created_at": "2024-07-03T21:45:36Z",     // Unchanged
    "created_by": { /* Original creator */ }, // Unchanged
    "modified_at": "2024-07-04T15:30:22Z",    // Updated to match latest version
    "modified_by": {
        "id": "28e525d1-e9c9-5e20-ccef-g97f4d85e0de",
        "name": "Second User",
        "email": "modifier@example.com"
    },
    "version_id": "1720118622394801920",      // New version ID
    // ... other fields
    "versions": [ // List of versions
      {
        "version_id": "1720118622394801920",
        "created_at": "2024-07-04T15:30:22Z",
        "created_by": {
            "id": "28e525d1-e9c9-5e20-ccef-g97f4d85e0de",
            "name": "Second User",
            "email": "modifier@example.com"
        }
        // ...

      },
      {
        "version_id": "1720032216597690880",
        "created_at": "2024-07-03T21:45:36Z",
        "created_by": {
            "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
            "name": "Original User",
            "email": "original@example.com"
        }
        // ...
      }
    ]
}

deleted_at and deleted_by

These fields handle object recycling and restoration:

• When an object is recycled (soft deleted), these fields are set with the deletion timestamp and user
• When an object is restored from the recycle bin, these fields are cleared (set to null)
• Recycling and restoring don't create new versions

Version identification

Each object and version has a version identifier:

version_id

• An ever increasing number
• Used as the identifier for each version
• Used for referencing specific versions on the object

Operations that affect audit fields (on the object level)

Operation	created_*	modified_*	deleted_*	version_id
Initial object creation	Set	Set (same as created_*)	Remain null	Set from initial version
Update object content	Unchanged	Updated	Unchanged	New ID from second version
Update object stages	Unchanged	Unchanged	Unchanged	Unchanged
Recycle object	Unchanged	Unchanged	Set	Unchanged
Restore object	Unchanged	Unchanged	Cleared	Unchanged

Related guides

• Uploading geoscience object metadata
• Updating a geoscience object
• Listing latest object versions

Summary

1. Object audit fields track creation, modification, and deletion information throughout an object's lifecycle.
2. created_* fields never change after initial creation and reflect the original creator and timestamp.
3. modified_* fields update with each content version and always match the latest version's creation details.
4. deleted_* fields are set when recycling objects and cleared when restoring them.
5. Every content update creates a new version with a version_id, even if no changes are made.