Rest-API Date-Time objects are epoch not strings

[jansenm]

Current Behavior

According to the documentation all dates (as far as i can see) are documented as:

      "ManagedUser" : {
        "required" : [ "lastPasswordChange", "username" ],
        "type" : "object",
        "properties" : {
          ...,
          "lastPasswordChange" : {
            "type" : "string",
            "format" : "date-time"
          },

So supposedly they are string with a datetime format. Unfortunately this:

~# curl -X "GET" "${DEPENDENCY_TRACK_URL}/api/v1/team"  -H "X-Api-Key: ${DEPENDENCY_TRACK_API_KEY}" | jq .[].managedUsers
[
  {
    "username": "admin",
    **"lastPasswordChange": 1760094591720,**
    "fullname": "Administrator",
    "email": "admin@localhost",
    "suspended": false,
    "forcePasswordChange": false,
    "nonExpiryPassword": true
  }
]
[]
[]

does not look like a string. Its apparently epoch in milliseconds. This breaks a lot of bindings out there that assume you can take the openapi.json file at face value.

Steps to Reproduce

See above

Expected Behavior

The openapi.json file documents the correct format that the api returns.

Dependency-Track Version

v4.13.5

Dependency-Track Distribution

Container Image

Database Server

PostgreSQL

Database Server Version

No response

Browser

Google Chrome

Checklist

• I have read and understand the contributing guidelines
• I have checked the existing issues for whether this defect was already reported

[nscuro]

The use of epoch timestamps by the API is intended, we just need to make sure API docs reflect this correctly.

[nscuro]

@mreiche That is captured in #2590

Let's try to not mix things otherwise it becomes impossible to track.

[naveendhaterwal]

Hi, @jansenm @nscuro @davidkarlsen could you please assign this issue to me?
This is my first time participating in GSoC, and I’m eager to learn and contribute. I have experience with MERN, Next.js, TypeScript, Rust, and Tailwind CSS.
I’d really appreciate the opportunity to work on this issue.
Thank you!

[montj2]

Hi @nscuro , I did some digging and the API correctly returns epoch timestamps because of the global Jackson WRITE_DATES_AS_TIMESTAMPS setting, but Swagger introspects the Alpine ManagedUser entity’s java.util.Date fields and generates string / date-time schemas. Since we can’t modify the Alpine source with @Schema annotations, I see two ways forward: (A) introduce a ManagedUserResponse DTO with explicit annotations, or (B) use a Jackson/Swagger mixin or local ModelConverter to override the schema to int64. A is cleaner long-term but larger in scope; B keeps it small and focused on documentation. Given the size/S and good first issue labels, do you have a preference?

[siddharthkarn2212]

Thanks for the clarification earlier.

I plan to address this by adjusting the OpenAPI schema to document date-time fields as epoch milliseconds (int64), without changing API behavior.

I’ll start with a small, docs-focused change and mark the PR as draft for feedback.

[nscuro]

Fixed structurally for v5: DependencyTrack/hyades-apiserver#2116