guardrail-dev / guardrail-dev/guardrail

can't use `$ref` in `x-www-form-urlencoded`

Open
#1,766 2 comments 1 reaction 0 assignees View on GitHub
Dominant language
Scala
Stars
541
Forks
138
PR merge metrics
No merged PRs in 30d

Description

This works:
```json
{
"paths": {
"/api/v1/oauth/token/introspect": {
"post": {
"deprecated": false,
"description": "Token introspection for Daml Hub access tokens, as per [rfc7662#section-2](https://datatracker.ietf.org/doc/html/rfc7662#section-2)\n",
"operationId": "introspectAccessToken",
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"token": {
"description": "access token to introspect",
"type": "string"
}
},
"required": [
"token"
]
}
}
}
}
}
}
}
}
```

But if the inlined schema is moved to a dedicated schema, guardrail code-generation fails:
```json
{
"components": {
"schemas": {
"TokenIntrospectionRequest": {
"properties": {
"token": {
"description": "access token to introspect",
"type": "string"
}
},
"required": [
"token"
],
"type": "object"
}
}
},
"paths": {
"/api/v1/oauth/token/introspect": {
"post": {
"deprecated": false,
"description": "Token introspection for Daml Hub access tokens, as per [rfc7662#section-2](https://datatracker.ietf.org/doc/html/rfc7662#section-2)\n",
"operationId": "introspectAccessToken",
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/TokenIntrospectionRequest"
}
}
}
}
}
}
}
}
```
```
Unable to generate decoder for application/x-www-form-urlencoded (.paths./api/v1/oauth/token/introspect.operations.POST.consumes[0])
Error:No decoders available (.paths./api/v1/oauth/token/introspect.operations.POST.consumes)
```

The [spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object) says:
> Alternatively, any time a Schema Object can be used, a [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject) can be used in its place.

Contributor guide

Open the contributing guide

Research direction

Reproduce the failure with the two OpenAPI examples in the issue, comparing the inline schema with the `$ref` schema for application/x-www-form-urlencoded. Start at Guardrail's form-urlencoded decoder generation and reference resolution, then add regression coverage showing that the referenced schema generates successfully. Done means both schema forms produce a decoder.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, scala
Domain
api, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.