Repository navigation
Description
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: falseThe 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 saysinteger/Int64. Correct.getter expires_at : Time?→ the document saysstring/date-time. Wrong.
Probable cause
I found this by reading the source. I did not compile a fix.
- active-model declares a non-nilable
attributewithgetter!(model.cr#L1137), so the instance variable isTime?. A field declaredTime?is also a nilable union. JSON::Schema#json_schemacollects theJSON::Fieldnamed args for each instance variable and passes them tointrospect. For a union,introspecttakes theanyOfbranch, which callsintrospectfor each member withnilinstead of{{args}}(json-schema v2.1.1json-schema.cr#L95-L103). Thetypeandformathints are lost, andTimebecomesstring/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_atControlSystem.signage_last_seenEdge.last_seen(also inEdge::KeyResponse)History.created_atModule.error_timestampShortener.valid_from,Shortener.valid_untilTrigger::Conditions::TimeDependent.timeUserresponses: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