You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Ruby] Stabilize Kiota Ruby generator for production use (Open Payments SDK) #7956
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
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:
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:
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.
Int64 is nobody's constant. Fields with format: int64 deserialize through a
bare Int64 that no gem defines.
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:
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.
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:
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.
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.
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.
Activity
wiebren commentedon Sep 4, 2026
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_json0.20.0) and ran itthrough 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:models/models.rbrequires a subclass file before its base(
process_error.rbbeforesrs_error.rb), so loading the client raisesNameError.We had to predefine the base class before requiring the client.
Blocks the first call:
models call
create_from_discriminator_valueon an enum — which is generated as aplain Hash of members — so any response carrying an enum array raises.
Int64is nobody's constant. Fields withformat: int64deserialize through abare
Int64that no gem defines.local. Our
/domains/{domainName}!quotepath produces awith_domain_name_quotemethod that uses
domainNamewhere the parameter has a different name —NameErroron first use.
Blocks whole categories of operations:
string
"400"whileFaradayRequestAdapterlooks it up with the integer status, sothe mapping never matches and every error surfaces generic. Re-keyed, the
discriminated error types work.
response schema generates
send_async(request_info, nil, error_mapping), and theadapter rejects it:
'factory cannot be null'(
microsoft_kiota_faraday-0.20.0/.../faraday_request_adapter.rb:49) — before anyrequest goes out.
Corrupts requests that do go out:
nullforunset 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.errorreferences aProcess_errorclass that is never emitted); Ruby's lazyconstant resolution keeps it dormant until the first response that carries the field.
Everything reproduces with
kiota generate -l rubyagainst our document and one callper 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.
andreaTP commentedon Oct 6, 2026
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
"IncomingPayment"instead of"incoming-payment", so grant requests were rejected (fix(ruby): enum wire values and unions without a discriminator #8314, fix: enum and composed type reading, expose error status and headers kiota-ruby#171).From Wiebren Braakman (@wiebren)'s report
Int64: fix(ruby): dispatch every response shape to the right request adapter #8256.nullor"": fix!: leave unset scalars off the wire kiota-ruby#154.Other fixes along the way
ApiErrorexposes the status code and headers (fix: enum and composed type reading, expose error status and headers kiota-ruby#171).attr_accessorproperties, noruby -wwarnings (Fix/ruby 4262 indentation #8037, fix(ruby): fix factory method syntax errors and RuboCop offenses #8052, fix(ruby): autoload models so a client loads in any order, and generate idiomatic Ruby #8301).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.
deps: Bump the nuget group with 19 updates (#139)