Skip to content

OpenAPI doc lists Unix-second timestamps as date-time strings #466

Closed

Description

@MrYuion

Note

🤖 Claude Opus 5.5 responding on behalf of MrYuion

OPENAPI_DOC.yml documents 84 fields in 40 schemas as type: string, format: date-time, but the API sends them as Unix seconds. Clients generated from the document parse these fields wrong. The cause seems to be in spider-gazelle/json-schema: it drops the type:/format: hints of a field whose instance variable is nilable.

Example

PlaceOS::Model::Timestamps declares (models base/timestamps.cr#L9):

attribute created_at : Time = -> { Time.utc }, converter: PlaceOS::Model::Timestamps::EpochConverter, type: "integer", format: "Int64", mass_assignment: false

The document says this for PlaceOS.Model.Zone.created_at (and every other model that uses Timestamps):

created_at:
  anyOf:
  - type: string
    format: date-time
  - type: "null"

PlaceOS::Api::ApiKeys::Response has both cases in one struct (api_keys.cr#L42-L49). Both fields have type: "integer", format: "Int64" on the JSON::Field:

  • getter created_at : Time → the document says integer / Int64. Correct.
  • getter expires_at : Time? → the document says string / date-time. Wrong.

Probable cause

I found this by reading the source. I did not compile a fix.

  1. active-model declares a non-nilable attribute with getter! (model.cr#L1137), so the instance variable is Time?. A field declared Time? is also a nilable union.
  2. JSON::Schema#json_schema collects the JSON::Field named args for each instance variable and passes them to introspect. For a union, introspect takes the anyOf branch, which calls introspect for each member with nil instead of {{args}} (json-schema v2.1.1 json-schema.cr#L95-L103). The type and format hints are lost, and Time becomes string / date-time.

A possible fix is to pass {{args}} to the members that are not Nil. The Nil member must not get the args, or type: "integer" replaces "null". After a json-schema release, update the shard here and regenerate OPENAPI_DOC.yml.

Affected fields

created_at / updated_at on each model that includes PlaceOS::Model::Timestamps (also through ModelWithAutoKey), and:

  • ApiKey.expires_at, ApiKeys::Response.expires_at
  • ControlSystem.signage_last_seen
  • Edge.last_seen (also in Edge::KeyResponse)
  • History.created_at
  • Module.error_timestamp
  • Shortener.valid_from, Shortener.valid_until
  • Trigger::Conditions::TimeDependent.time
  • User responses: created_at, last_login

The Time fields without a converter are RFC 3339 strings and are correct as they are. Examples: the models with PgORM::Timestamps (groups, signage templates, pending mails) and Upload.cache_modified.

Workaround in ts-client

PlaceOS/ts-client#36 patches the list above in its generator (EPOCH_FIELDS in v2/scripts/generate.ts). The patch can be removed when the document is correct. The generator stops if a patched field is no longer date-time, so the fix will show there.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions