Skip to content

[Ruby] Stabilize Kiota Ruby generator for production use (Open Payments SDK) #7956

Closed

Description

Is your feature request related to a problem? Please describe the problem.

Summary

Kiota's Ruby target (generation, abstractions: preview; JSON serialization,
auth: done; HTTP: preview) is close to usable but marked "not actively worked
on internally" per the Ruby tracking project. I'd like to take it from preview
to stable, motivated by generating a production Ruby SDK for the Open Payments
API (openpayments.dev, JSON only ,so FORM/MULTIPART/TEXT serialization gaps
#2077/#3032/#1049 aren't blockers for this use case).

This aligns with the Interledger Foundation's SDK Grant program, which lists
Ruby as a high-priority open track :
interledger/Grants wiki: SDK-grant-program

Client library/SDK language

Ruby

Describe the solution you'd like

Proposed approach

  • Generate a Ruby client from the Open Payments OpenAPI document using the
    current preview generator; catalog every failure/bug encountered
  • Fix generator bugs blocking correct compilation/runtime behavior
  • Validate the generated client end-to-end against Open Payments' public
    test environment (auth.interledger-test.dev)
  • Bring generation + abstractions + HTTP from preview to stable, matching
    the bar set by Go/Python/PHP

Questions for maintainers

  1. Is there a known list of blocking issues for Ruby preview→stable, beyond
    the three serialization gaps already tracked?
  2. Any existing branch or WIP I should be aware of before starting?
  3. Open to reviewing a draft PR built against a working Ruby SDK for Open Payments?

Additional context

No response

Activity

  1. moved this to Needs Triage 🔍 in Kiotaon Jul 19, 2026
  2. wiebren commented on Sep 4, 2026

    @wiebren
    Contributor

    Some stabilization input from a real-world attempt. We generated a Ruby client from our
    production OpenAPI 3.1 document (kiota 1.34.1, microsoft_kiota_abstractions /
    microsoft_kiota_faraday / microsoft_kiota_serialization_json 0.20.0) and ran it
    through the same 29-case contract suite we use to compare generated clients across
    languages. Every case needed a shim before it passed; here is the itemized list, ordered
    by where it blocks.

    Blocks require:

    1. Model require order. models/models.rb requires a subclass file before its base
      (process_error.rb before srs_error.rb), so loading the client raises NameError.
      We had to predefine the base class before requiring the client.

    Blocks the first call:

    1. Enum collections deserialize through the enum as if it were a model. Generated
      models call create_from_discriminator_value on an enum — which is generated as a
      plain Hash of members — so any response carrying an enum array raises.
    2. Int64 is nobody's constant. Fields with format: int64 deserialize through a
      bare Int64 that no gem defines.
    3. A path segment with an escaped suffix generates a builder referencing an undefined
      local.
      Our /domains/{domainName}!quote path produces a with_domain_name_quote
      method that uses domainName where the parameter has a different name — NameError
      on first use.

    Blocks whole categories of operations:

    1. Typed errors are dead code. The request builders key the error mapping with the
      string "400" while FaradayRequestAdapter looks it up with the integer status, so
      the mapping never matches and every error surfaces generic. Re-keyed, the
      discriminated error types work.
    2. A void operation cannot be called at all. An operation whose 2xx declares no
      response schema generates send_async(request_info, nil, error_mapping), and the
      adapter rejects it: 'factory cannot be null'
      (microsoft_kiota_faraday-0.20.0/.../faraday_request_adapter.rb:49) — before any
      request goes out.

    Corrupts requests that do go out:

    1. The serializer writes every declared scalar whether set or not — null for
      unset optionals, and an unset enum even as "". On partial-update endpoints where
      "absent" and "empty" mean different things (ours documents "to remove an optional
      field specify it as empty"), this is not noise: an update the caller never asked for
      goes on the wire. Only nil collections stay off the wire.

    One latent extra, same family as the Dart fix in #8151: an inline property type and a
    component schema that snake-case to the same file name silently clobber each other
    (Process.error references a Process_error class that is never emitted); Ruby's lazy
    constant resolution keeps it dormant until the first response that carries the field.

    Everything reproduces with kiota generate -l ruby against our document and one call
    per item; happy to boil any of these down to a minimal spec snippet, or split them into
    separate issues if that works better for tracking.

  3. andreaTP commented on Oct 6, 2026

    @andreaTP
    Contributor

    Thanks TheRustFanatic (@mahmudsudo) for opening this and Wiebren Braakman (@wiebren) for the detailed report, it shaped most of the work below. I think this can now be closed, here is a summary of what changed and what is still open.

    There is a small demo at https://github.com/andreaTP/kiota-ruby-op-poc. It generates the three Open Payments clients and sends a payment through them (grants, quote, interactive approval, outgoing payment) against a local stand-in that checks the GNAP tokens and Ed25519 signatures. The README also covers running it on the Interledger test network.

    What blocked Open Payments

    From Wiebren Braakman (@wiebren)'s report

    1. Model require order: models are autoloaded, so load order no longer matters (fix(ruby): autoload models so a client loads in any order, and generate idiomatic Ruby #8301).
    2. Enum collections read as models: fix(ruby): dispatch every response shape to the right request adapter #8256, feat: serialize scalar request bodies and enum collections kiota-ruby#158.
    3. Undefined Int64: fix(ruby): dispatch every response shape to the right request adapter #8256.
    4. Builder for a path with an escaped suffix: fix(ruby): resolve the request builder for a path with an escaped suffix #8255.
    5. Typed errors never matched: fix: match the error mapping by string status code kiota-ruby#153.
    6. Void operations rejected: fix(ruby): dispatch every response shape to the right request adapter #8256, feat: add the collection, primitive and no-content send methods kiota-ruby#155.
    7. Unset scalars written as null or "": fix!: leave unset scalars off the wire kiota-ruby#154.
    8. Inline type clobbered by a component of the same name: fix: keep a component's class when an inline property schema takes its name #8193 (core, all languages), thanks om singhal (@Om-singhaI).

    Other fixes along the way

    The runtime gems now live in one repository (microsoft/kiota-ruby#112) and are at 0.24.0, requiring Ruby 3.3+. Ruby CI generates and lints 19 descriptions, including GitHub, Stripe, Notion and Meraki, and runs mock-server tests for errors, inheritance, query parameters, discriminators, enums and default values.

    Still open, tracked separately

    Thanks Vincent Biret (@baywet) for all the help and reviews. If anything here looks wrong or incomplete, I'm happy to follow up.

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

    Type

    No type

    Projects

    • Status
      Done ✔️

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions