{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/respect/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"x-allowReserved extension","description":"OpenAPI-generated documentation tool with 24k+ stars on Github - make APIs your company's superpower.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"x-allowreserved-extension","__idx":0},"children":["x-allowReserved extension"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Respect supports the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-allowReserved"]}," extension on step parameters in Arazzo descriptions."," ","Use it when a step passes a query parameter whose value must keep RFC 3986 reserved characters unencoded in the request URL."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-use-it","__idx":1},"children":["When to use it"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-allowReserved"]}," when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A query parameter value contains reserved characters: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[": / ? # [ ] @ ! $ & ' ( ) * + , ; ="]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You need the query string value sent \"as-is\"."," ","For example, the value is a full URL or a value that already uses reserved characters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-allowReserved"]},", Respect encodes reseved characters (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%3A"]},")."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This matches the OpenAPI 3.x ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://spec.openapis.org/oas/v3.0.3#parameter-object"},"children":["Parameter.allowReserved"]}," behavior."," ","When a step uses an OpenAPI operation, Respect also honors ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowReserved"]}," from the operation's parameters."," ","For step parameters you define in the Arazzo description, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-allowReserved"]}," extension."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":2},"children":["Configuration"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"25%","data-label":"Field name"},"children":["Field name "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"25%","data-label":"Type"},"children":["Type "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["x-allowReserved"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," to leave RFC 3986 reserved characters in the parameter value unencoded in the request URL."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":3},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"workflows:\n  - workflowId: example\n    steps:\n      - stepId: get-with-filter\n        operationId: my-api.getSearch\n        parameters:\n          - in: query\n            name: filter\n            value: \"https://example.com/path/to;x,y(z)a*b.c[1]@v\"\n            x-allowReserved: true\n        successCriteria:\n          - condition: $statusCode == 200\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-allowReserved: true"]},", the query string is sent as:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?filter=https://example.com/path/to;x,y(z)a*b.c[1]@v"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reserved characters in the value are left unencoded."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":4},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/respect/commands"},"children":["Respect commands"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["OpenAPI 3 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://spec.openapis.org/oas/v3.0.3#parameter-object"},"children":["Parameter object"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowReserved"]},")"]}]}]},"headings":[{"value":"x-allowReserved extension","id":"x-allowreserved-extension","depth":1},{"value":"When to use it","id":"when-to-use-it","depth":2},{"value":"Configuration","id":"configuration","depth":2},{"value":"Example","id":"example","depth":2},{"value":"Resources","id":"resources","depth":2}],"frontmatter":{"seo":{"title":"x-allowReserved extension"}},"lastModified":"2026-03-18T14:43:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/respect/extensions/x-allow-reserved","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}