guardrail Extensions

guardrail has a number of vendor extensions designed to enhance safety and provide more idiomatic generated code. The following table lists all vendor extensions, contexts where they are applicable, and a short description of how to use them effectively.

Extension Type Contexts Description
x-empty-is-null boolean clients/servers, definitions Instructs the JSON decoder to convert empty strings to null before decoding, causing empty strings to not satisfy the required directive, or being represented as None instead of Some("").
x-file-hash string servers, parameters, file During a streaming file upload, keep track of the file hash in one of the supported file hash types.
x-scala-package string clients/servers, paths A dot-separated package segment concatenated to the end of the supplied packageName when generating Scala code. This permits splitting up large specifications into smaller, domain-specific Handlers. See also x-jvm-package.
x-java-package string clients/servers, paths A dot-separated package segment concatenated to the end of the supplied packageName when generating Java code. This permits splitting up large specifications into smaller, domain-specific Handlers. See also x-jvm-package.
x-jvm-package string clients/servers, paths A dot-separated package segment concatenated to the end of the supplied packageName when generating JVM code. This permits splitting up large specifications into smaller, domain-specific Handlers. Note that x-scala-package and x-java-package take precedence over this property.
x-server-raw-response boolean servers, paths Exposes the underlying HTTP framework's response-building infrastructure. Type-safe `respond` wrappers are still generated and supplied, though this escape-hatch is intended to work around bugs in guardrail itself. This is not recommended for long-term use, as no guarantees around compile-time-safe protocol adherence can be made.
x-tracing-label string clients/servers, paths When tracing is enabled, override the provided function label with a custom string. This string will be supplied to your supplied trace function in your servers and your supplied traceBuilder in your clients.
x-scala-type string definitions, parameters Override the primitive types specified in the OpenAPI specification with a domain-specific type for generated Scala code. This requires the type to have either serializers/deserializers in the underlying JSON framework or HTTP framework. As this is an advanced feature, it may require use of custom imports provided via build tool plugins or at the CLI.
x-java-type string definitions, parameters Override the primitive types specified in the OpenAPI specification with a domain-specific type for generated Java code. This requires the type to have either serializers/deserializers in the underlying JSON framework or HTTP framework. As this is an advanced feature, it may require use of custom imports provided via build tool plugins or at the CLI.
x-jvm-type string definitions, parameters Override the primitive types specified in the OpenAPI specification with a domain-specific type for generated JVM (Scala and Java) code. This requires the type to have either serializers/deserializers in the underlying JSON framework or HTTP framework. As this is an advanced feature, it may require use of custom imports provided via build tool plugins or at the CLI.
x-scala-array-type, x-java-array-type string definitions, parameters Override the generated array type from `Vector` to some custom type. This requires the type to have either serializers/deserializers in the underlying JSON framework or HTTP framework. As this is an advanced feature, it may require use of custom imports provided via build tool plugins or at the CLI.
x-scala-map-type, x-java-map-type string definitions, parameters Override the generated map type from `Map` to some custom type. This requires the type to have either serializers/deserializers in the underlying JSON framework or HTTP framework. As this is an advanced feature, it may require use of custom imports provided via build tool plugins or at the CLI.
x-scala-class-prefix string clients/servers An arbitrary class name prefix that overrides the default class name when generating Scala code. See also x-jvm-class-prefix.
x-java-class-prefix string clients/servers An arbitrary class name prefix that overrides the default class name when generating Java code. See also x-jvm-class-prefix.
x-jvm-class-prefix string clients/servers An arbitrary class name prefix that overrides the default class name when generating JVM code. See also x-scala-class-prefix.

Prev: Generating clients