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.
|