Skip to content

OpenAPI doc leaves out read-only fields and types some strings as object #470

Closed

Description

@MrYuion

Note

🤖 Claude Opus 5.5 responding on behalf of MrYuion

OPENAPI_DOC.yml leaves out the read-only fields that the API sends, and it gives some string fields the type object. A client generated from the document drops the missing fields and cannot type the strings. I compared the replies of 123 GET endpoints on a local stack with the document at f30710c, then checked each field in the source.

Read-only fields are missing

JSON::Schema#json_schema skips each instance variable with ignore or ignore_deserialize (json-schema json-schema.cr#L15). A request body must not have these fields. The document uses the same schema for the response, though, and the API sends them.

Schema Missing fields Source
AssetType asset_count asset_type.cr#L44-L45
Booking (staff-api) email_digest, booked_by_id, booked_by_email_digest, created, current_state, linked_event, linked_bookings, linked_parent_booking booking.cr#L91-L117
Guest (staff-api) checked_in, visit_expected, booking, event, event_metadata guest.cr#L23-L29

OpenAPI 3.1 has readOnly: true for this case. If json-schema keeps these fields with readOnly, the document can describe both directions with one schema.

User.AdminMetadataResponse and User.PublicMetadataResponse do not have associated_metadata either. define_to_json adds it with methods: (user.cr#L308-L317). subsystem_access comes from the same methods: list and is in the document. The difference may be that associated_metadata has no return type.

String fields have the type object

introspect gives { type: "object" } for a type it does not know (json-schema.cr#L189-L196). The API sends these fields as strings:

Field Crystal type Sample
Zone.timezone, ControlSystem.timezone Time::Location, Time::Location::Converter (zone.cr#L48) "Australia/Melbourne"
items of ApiKey.scopes, ApiKeys::Response.scopes, UserJWT.scope UserJWT::Scope (api_key.cr#L16) "public"
Driver.json_schema JSON::Any, JSON::Any::StringConverter (driver.cr#L25) "{}"
Cluster::NodeStatus.uri URI (cluster.cr#L79) "http://core:3000"

After #469 the field hints reach the schema, so type: "string" on each of these fields may be enough.

The JSON::Any fields also get object, but they can hold any JSON value. Metadata::Interface.details holds arrays in the seed data, for example. An empty schema ({}) means any value.

Other differences

  • The API sends the number of an enum that has Enum::ValueConverter, but the document lists the names: Broker.auth_type (2), Driver.role and Module.role (99), Settings.encryption_level (0).
  • The {id} path parameter of /api/engine/v2/oauth_apps/{id} is a string, but DoorkeeperApplication.id is an integer.

PlaceOS/ts-client#36 gets generator patches for these fields. Each patch stops the generator when the document changes the field, so a fix here shows there.

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