Map DateTime to google.protobuf.Timestamp and document temporal string formats

[jwils]

Why

Mapping DateTime to string loses the type safety proto offers — a string can be malformed in ways a google.protobuf.Timestamp cannot, and proto consumers get language-native timestamp types. For the remaining string-typed temporal scalars, the proto type is much wider than the ElasticGraph type, so the expected format deserves documentation at the point of use (per review discussion).

What

• Map DateTime to google.protobuf.Timestamp, importing google/protobuf/timestamp.proto automatically. A Timestamp is a UTC instant, so a publisher's original UTC offset is not preserved; t.protobuf type: "string" remains available as an override.
• t.protobuf gains two options usable by any scalar:
  • import: maps a scalar to an externally defined proto type, emitting the needed import statement
  • comment: documents the expected format on each generated field
• The built-in string-typed temporal scalars (Date, LocalTime, TimeZone) use comment: to document their formats (e.g. // ISO 8601 date, e.g. "2024-11-25"). Values are still validated at ingestion time, exactly as with JSON ingestion.
• Format comments compose with the existing source name: comments and propagate to the innermost nested-list wrapper field.

Risk Assessment

Low — only affects the unreleased elasticgraph-proto_ingestion extension from #1080.

References

• Stacked on Pin protobuf field and enum value numbers in a sidecar artifact #1304 (→ Generate a protobuf schema artifact from ElasticGraph schemas #1080)
• Addresses Generate a protobuf schema artifact from ElasticGraph schemas #1080 (comment) and Generate a protobuf schema artifact from ElasticGraph schemas #1080 (comment)

Update — 2026-07-10

Nested-list wrapper comment propagation was removed after #1080 changed to reject lists of lists. Format comments continue to apply to supported scalar and single-list fields.