guardrail-dev / guardrail-dev/guardrail
can't use `$ref` in `x-www-form-urlencoded`
- 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
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