// Shared timestamp-parser messages used by any surface that ingests time-series data
// and needs to describe how raw timestamp values should be interpreted. Colocated with
// other shared time types in this package so downstream services can depend on a single
// file without pulling in procedure- or registry-specific schemas.

syntax = "proto3";

// Ignore buf linting rule that adds version suffix for shared types
// buf:lint:ignore PACKAGE_VERSION_SUFFIX
package nominal.types.time;

import "buf/validate/validate.proto";
import "google/protobuf/timestamp.proto";
import "nominal/protos/gen/v1/alias.proto";

option java_multiple_files = true;
option java_package = "io.nominal.types.time";

// Selects between relative-offset and absolute-timestamp parsing strategies.
message TimestampType {
  oneof option {
    option (buf.validate.oneof) = {required: true};
    RelativeTimestamp relative = 1;
    AbsoluteTimestamp absolute = 2;
  }
}

// Relative timestamp parser: interprets each row's timestamp as an offset from a fixed origin.
message RelativeTimestamp {
  // Unit in which relative offsets are expressed. Aliases the Conjure TimeUnit alias.
  string time_unit = 1 [(nominal.gen.v1.alias) = {java_name: "io.nominal.api.TimeUnit"}];
  // Starting timestamp to use when indexing the file.
  google.protobuf.Timestamp offset = 2;
}

// Absolute timestamp parser variants.
message AbsoluteTimestamp {
  oneof option {
    option (buf.validate.oneof) = {required: true};
    Iso8601Timestamp iso8601 = 1;
    EpochTimestamp epoch_of_time_unit = 2;
    CustomTimestamp custom_format = 3;
  }
}

// Absolute timestamps serialized in ISO-8601 form. No additional parser configuration is needed.
message Iso8601Timestamp {}

// Absolute timestamps expressed as an integer count of some time unit since the Unix epoch.
message EpochTimestamp {
  // Unit in which epoch values are expressed (e.g. SECONDS, MILLISECONDS).
  string time_unit = 1 [(nominal.gen.v1.alias) = {java_name: "io.nominal.api.TimeUnit"}];
}

// Absolute timestamps parsed with a user-supplied format string.
message CustomTimestamp {
  // The format string should be in the format of the `DateTimeFormatter` class in Java.
  string format = 1;
  // Default year is accepted as an optional field for cases like IRIG time format.
  // Will be overridden by year in time format.
  optional int32 default_year = 2;
  // Default day of year is accepted as an optional field for cases like IRIG time format.
  // Will be overridden by day of year in time format.
  optional int32 default_day_of_year = 3 [
    (buf.validate.field).int32.gte = 1,
    (buf.validate.field).int32.lte = 366
  ];
}
