[Traits](https://oods-foundry.com/traits) / Timestampable

# Timestampable

Captures creation and update timestamps with configurable audit metadata for lifecycle tracking.

Generated from @oods/foundry 0.10.1

- Group

  lifecycle

- Maturity

  stable

- Contexts

  detail, list

## Fields it adds

| Field | Type | Required | Description |
| - | - | - | - |
| `created_at` | `datetime` | yes | Timestamp recording when the entity was first created. |
| `updated_at` | `datetime` | no | Timestamp for the most recent modification, when available. |
| `last_event` | `string` | yes | Lifecycle event associated with the most recent timestamp mutation. |
| `last_event_at` | `datetime` | no | Timestamp for the lifecycle event captured in last_event. |

## What it shows in each context

- [detail](https://oods-foundry.com/contexts/detail)

  `AuditTimeline`

- [list](https://oods-foundry.com/contexts/list)

  `RelativeTimestamp`

## Parameters

- `recordedEvents` `string[]`, required

  Canonical lifecycle events captured in the audit timeline.

- `timezone` `string`

  Default timezone context applied when rendering timestamps.

- `allowNullUpdatedAt` `boolean`

  Whether updated_at may be omitted when no mutations have occurred.

## Objects that use it

- [Article](https://oods-foundry.com/objects/article)
- [Invoice](https://oods-foundry.com/objects/invoice)
- [Media](https://oods-foundry.com/objects/media)
- [Organization](https://oods-foundry.com/objects/organization)
- [Product](https://oods-foundry.com/objects/product)
- [Relationship](https://oods-foundry.com/objects/relationship)
- [Subscription](https://oods-foundry.com/objects/subscription)
- [Transaction](https://oods-foundry.com/objects/transaction)
- [Usage](https://oods-foundry.com/objects/usage)
- [User](https://oods-foundry.com/objects/user)

## The trait file

`traits/lifecycle/Timestampable.trait.yaml`

```
trait:
  name: Timestampable
  version: 1.0.0
  description: |
    Captures creation and update timestamps with configurable audit metadata for lifecycle tracking.
  category: lifecycle
  tags:
    - timestamp
    - audit
    - lifecycle
    - metadata

parameters:
  - name: recordedEvents
    type: string[]
    required: true
    description: Canonical lifecycle events captured in the audit timeline.
    default:
      - created
      - updated
      - deleted
  - name: timezone
    type: string
    required: false
    description: Default timezone context applied when rendering timestamps.
    default: UTC
    validation:
      enum:
        - UTC
        - LOCAL
        - OFFSET
  - name: allowNullUpdatedAt
    type: boolean
    required: false
    description: Whether updated_at may be omitted when no mutations have occurred.
    default: true

schema:
  created_at:
    type: datetime
    required: true
    description: Timestamp recording when the entity was first created.
  updated_at:
    type: datetime
    required: false
    description: Timestamp for the most recent modification, when available.
  last_event:
    type: string
    required: true
    description: Lifecycle event associated with the most recent timestamp mutation.
    validation:
      enumFromParameter: recordedEvents
  last_event_at:
    type: datetime
    required: false
    description: Timestamp for the lifecycle event captured in last_event.

semantics:
  created_at:
    semantic_type: audit.created_at
    token_mapping: tokenMap(audit.created)
    ui_hints:
      component: TimelineTimestamp
      timezoneParameter: timezone
  updated_at:
    semantic_type: audit.updated_at
    token_mapping: tokenMap(audit.updated)
    ui_hints:
      component: TimelineTimestamp
      timezoneParameter: timezone
      allowNullParameter: allowNullUpdatedAt
  last_event:
    semantic_type: audit.event.type
    token_mapping: tokenMap(audit.event.*)
    ui_hints:
      component: AuditBadge
      parameterSource: recordedEvents
  last_event_at:
    semantic_type: audit.event.timestamp
    token_mapping: tokenMap(audit.event.timestamp)
    ui_hints:
      component: TimelineTimestamp
      timezoneParameter: timezone

view_extensions:
  detail:
    - component: AuditTimeline
      position: bottom
      props:
        createdField: created_at
        updatedField: updated_at
        eventField: last_event
        eventTimestampField: last_event_at
        eventOptionsParameter: recordedEvents
  list:
    - component: RelativeTimestamp
      props:
        field: updated_at
        fallbackField: created_at
        timezoneParameter: timezone

tokens:
  audit.created.badge.text: "var(--text-subtle)"
  audit.updated.badge.text: "var(--text-subtle)"
  audit.event.badge.bg: "var(--surface-muted)"

dependencies: []

metadata:
  created: "2025-10-16"
  owners:
    - lifecycle@oods.systems
    - platform@oods.systems
  maturity: stable
  accessibility:
    keyboard: "n/a"
    screenreader: "Announces creation and last update information with lifecycle context."
  regionsUsed:
    - detail
    - list
  examples:
    - User
    - Organization
    - Transaction
  references:
    - "Trait Engine Spec v0.1 §2"
```