Use deterministic default timestamp and add --current-timestamp option for JSON generation

[gjavakhadze]

Description

Makes JSON payload timestamp generation deterministic by default:

• Default behavior: When no exampleValue is defined in the model, date and time properties are generated using a fixed default timestamp (start of the Unix epoch: 1970-01-01T00:00:00.000Z). This
  ensures stable output across runs for automated tests and golden files.
• Opt-in dynamic timestamp: Adds a --current-timestamp flag (CLI, Maven plugin, and API config) to generate dynamic timestamps using LocalDateTime.now().
• Model priority: An exampleValue defined in the Aspect Model always takes precedence over generated default values.

Default deterministic generation:

samm aspect AspectModel.ttl to json

Opt-in current timestamp:

samm aspect AspectModel.ttl to json --current-timestamp

Fixes #813

Type of change

• New feature (non-breaking change which adds functionality)

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works

[sekikn]

Thanks a lot for addressing this @gjavakhadze! LGTM.
Since this PR covers the --timestamp option, I'll submit a separate PR for the --random-timestamp option after this one is merged (ref. #813 (comment)).

[e-filchenko-bosh]

Thanks for the implementation. I think we should slightly reconsider the intended behavior for this issue.

From my perspective, there are two main scenarios we should support:

1. Default deterministic generation
   When running samm aspect AspectModel.ttl to json without any extra option, timestamp values without an exampleValue should be generated from a fixed default value.
   This makes the generated JSON stable across runs, which is important for tests, golden files, and avoiding unnecessary changes in generated files/changelogs when the Aspect Model structure did not actually change.

2. Explicit random/current timestamp generation
   If a user wants the previous behavior, we can provide an opt-in flag such as --random-timestamp (or --current-timestamp).
   This flag would make timestamp generation use the current time, but it should be disabled by default.

With that model, the default behavior solves #813 directly, while users who need more dynamic sample data can still opt in explicitly.

I’m also not sure we need a generic --timestamp option for this issue. Accepting and parsing arbitrary XML Schema dateTime values adds extra complexity and edge cases. For example, depending on the conversion path, fractional seconds or timezone information can be lost when converting through types like LocalDateTime. Unless we have a clear use case for user-provided custom timestamps, I would prefer to keep the API smaller:

• fixed timestamp by default
• optional --random-timestamp for current/random timestamp behavior
• exampleValue in the model still takes precedence over generated values

[gjavakhadze]

@sekikn Thanks for your involvement and contribution in this project, my initial solution was kind of influenced from your referenced comment.

---

@e-filchenko-bosh Thanks for your great insights,

1. Default deterministic generation

When running samm aspect AspectModel.ttl to json without any extra option, timestamp values without an exampleValue should be generated from a fixed default value.

Totaly agree here, will do the required changes for this. Do you have an idea what can we set for default timestamp value when exampleValue is not provided? Basicaly it can be a any past dateTime or even first epoch timestamp value.

2. Explicit random/current timestamp generation

If a user wants the previous behavior, we can provide an opt-in flag such as --random-timestamp (or --current-timestamp).

Previous behavior was current timestamp always, never random, so current-timestamp opt-in param seems to be a better self explanatory name, but using current-timestamp without custom value we are losing flexibility to inject any valid dateTime value. My motivation was user to be able to inject any dateTime they want. I don't have any strong argument beyond flexibility for this change, but if it seems to adding extra complexity for this feature, we can avoid it for sure.

[e-filchenko-bosh]

Thanks for the clarification.

For the default timestamp value, I do not have a strong preference. The important part is that it is fixed and stable across runs. It could be today’s date, the Unix epoch, or something visually simple like 2026-01-01T00:00:00.000Z. From my perspective, any valid full dateTime value is fine as long as we document it and keep it unchanged afterwards.

Regarding the custom --timestamp option: I understand the motivation, and the flexibility is logically useful. I just cannot think of a strong concrete use case where users would need to regenerate the whole example payload with one specific custom dateTime injected globally. Since the parameter applies to the entire generated document and not to a particular timestamp property, the fixed default value seems sufficient for the issue.

We can keep --timestamp if we want that flexibility, but then I think it should be treated as part of the public API and tested more strictly. For example, we should cover values with fractional seconds and non-UTC offsets, such as:
2025-06-15T10:30:00.123+02:00

Currently this kind of value can easily lose information if it is parsed and converted through LocalDateTime, because LocalDateTime does not carry timezone/offset information. So if we keep --timestamp, the generator should either preserve the provided XML Schema dateTime value exactly, or clearly document and test the intended normalization behavior.

My preference would still be to keep the API smaller for this issue:
• fixed deterministic timestamp by default
• optional --current-timestamp to restore the previous behavior
• model exampleValue continues to take precedence

[sekikn]

@e-filchenko-bosh @gjavakhadze
Thank you for the valuable discussion and suggestions! I mostly agree with the conclusion, but I'd like to clarify one thing.

2. Explicit random/current timestamp generation
   If a user wants the previous behavior, we can provide an opt-in flag such as --random-timestamp (or --current-timestamp).

Does this mean that we regard the current timestamp as a random value? If so, I'd like to distinguish between "non-deterministic" and "random" values here, because the current timestamp is non-deterministic but highly biased.
I sometimes generate random payloads for invalid-input or boundary-value testing in a short time, so I'd like to have --random-timestamp in addition to --current-timestamp to cover a wider range than just recent timestamps.

I'm proposing another PR that adds a new option to give random values precedence over example values, so another option would be to include this "random" (not just "non-deterministic") behavior in that PR.

[e-filchenko-bosh]

Thanks @sekikn, that distinction makes sense to me.

I agree that current timestamp should not be called random. It restores the previous non-deterministic behavior, but it is not really random and is heavily biased towards “now”. So --current-timestamp is the better name for this PR.

I also checked #1035, and my understanding is that it currently adds --ignore-example-value, so the generator stops using model exampleValues and falls back to the existing generated values. For several scalar types this already means random values, but timestamp generation itself is not made truly random there. It still relies on the existing timestamp fallback behavior.

So I think #1035 is probably the right place to introduce truly random timestamp generation, but it would need an explicit implementation for timestamp/date/time types, e.g. generating values from a defined range.

For #1038 I would keep the scope limited to:

• fixed deterministic timestamp by default
• --current-timestamp for the previous non-deterministic “now” behavior
• model exampleValue continues to take precedence

Then truly random timestamp behavior can be handled separately in #1035 or a follow-up PR.

[e-filchenko-bosh]

LGTM!

[atextor]

LGTM!