> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Java configuration

> Configure your Java SDK generator with custom client names, package prefixes, builder patterns, and Maven publishing options for Fern.

You can customize the behavior of the Java SDK generator in `generators.yml`:

**`generators.yml`**

```yaml {7-9} title="generators.yml"
groups:
  java-sdk:
    generators:
      - name: fern-java-sdk
        version: 4.23.0
        config:
          client-class-name: YourApiClient
```

**`auto-generate-idempotency-key`** `boolean | object` — default: false

Overrides the API-wide [`api.settings.auto-generate-idempotency-key`](/learn/sdks/reference/generators-yml#settings) for this SDK. Set `true` to attach an [idempotency-key header](/learn/sdks/deep-dives/idempotency#auto-generate-idempotency-keys) to eligible requests (`POST` and `PUT` by default) unless the caller provides one, or `false` to opt this SDK out when auto-generation is enabled API-wide. Pass an object to customize `header-name` and `methods`.

---

**`base-api-exception-class-name`** `string`

Customizes the name of the base API exception class that all API-specific exceptions will extend. This allows you to define a custom base exception class name for better integration with your existing error handling patterns.

---

**`base-exception-class-name`** `string`

Specifies the name of the base exception class that all generated exceptions will inherit from. This provides a common parent class for all SDK exceptions, enabling consistent exception handling patterns.

---

**`client-class-name`** `string` — default: \<Organization>ApiClient

The provided string will be used as the client class name.

---

**`collapse-optional-nullable`** `boolean` — default: false

When enabled, generates `OptionalNullable<T>` types for merge patch request fields to distinguish between three states: absent (field not provided), null (field explicitly set to null), and present (field has a non-null value). This enables proper handling of JSON Merge Patch semantics where omitting a field, setting it to null, and providing a value have different meanings.

---

**`custom-dependencies`** `List<string>`

> **Enterprise feature**
>
> This feature is available only for the [Enterprise plan](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).

Example:

```yaml
custom-dependencies:
- "implementation com.foo:bar:0.0.0"
- "testImplementation com.foo:bar:0.0.0"
- "api com.foo:bar:0.0.0"
```

---

**`custom-interceptors`** `boolean` — default: false

When enabled, the generated client builder exposes an `addInterceptor(Interceptor)` method for registering [custom OkHttp interceptors](/learn/sdks/generators/java/custom-code#adding-custom-interceptors). Interceptors are applied to the `OkHttpClient` when the client is built, which covers HTTP-level customizations such as request signing and public key client validation.

---

**`disable-required-property-builder-checks`** `boolean` — default: false

When enabled, disables validation checks in builder patterns for required properties. This removes compile-time checks that ensure all required fields are set before building an object, providing more flexibility but less safety.

---

**`enable-extensible-builders`** `boolean` — default: false

When enabled, generates extensible builder classes that support customization through inheritance. This allows you to [add custom code](/learn/sdks/generators/java/custom-code#adding-custom-client-configuration) to extend the generated builders with additional functionality.

---

**`enable-forward-compatible-enums`** `boolean` — default: false

When enabled, generates enum classes that can handle unknown values gracefully. This allows the SDK to process new enum values that may be added to the API without breaking existing client code, improving forward compatibility.

---

**`enable-inline-types`** `boolean` — default: false

When enabled, generates inline types for nested schemas instead of creating separate classes. This results in cleaner type definitions where nested objects are defined within their parent types, reducing the number of generated files.

---

**`enable-public-constructors`** `boolean` — default: false

When enabled, generates public constructors for model types.

---

**`enable-wire-tests`** `boolean` — default: false

When enabled, generates [mock server (wire) tests](/learn/sdks/deep-dives/testing#mock-server-tests) to verify that the SDK sends and receives HTTP requests as expected.

---

**`generate-unknown-as-json-node`** `boolean` — default: false

When enabled, generates unknown or untyped properties as structured JSON objects instead of raw Object types. This provides better type safety and easier manipulation of dynamic JSON content while maintaining flexibility for unknown data structures.

---

**`inline-file-properties`** `boolean` — default: false

Controls whether file upload properties are generated as inline request properties instead of separate method parameters. When enabled, file fields become part of the request object rather than being passed as individual function arguments.

---

**`inline-path-parameters`** `boolean` — default: false

When enabled, path parameters are included as properties in the request object instead of being passed as separate method parameters. This creates a more unified request structure where all parameters are grouped together.

---

**`json-include`** `'non-empty' | 'non-absent'` — default: non-absent

Controls Jackson's JSON serialization behavior for optional fields. Use 'non-empty' to exclude null and empty values, or 'non-absent' to only exclude null values while preserving empty collections and strings.

---

**`maxRetries`** `number`

The default number of retries for failed requests. When not set, the generated SDK uses its own built-in default. SDK users can still override this per-request via request options, and can tune the [backoff schedule between retries](/learn/sdks/deep-dives/retries-with-backoff#customizing-the-backoff-schedule) at client instantiation.

---

**`offset-semantics`** `'item-index' | 'page-index'`

Controls how the offset parameter is interpreted for [auto-paginated](/learn/sdks/deep-dives/auto-pagination) endpoints.

* `item-index`: The offset counts individual items (e.g., offset 20 skips the first 20 items).
* `page-index`: The offset counts pages (e.g., offset 3 skips to page 3).

---

**`omit-fern-headers`** `boolean` — default: false

When enabled, the generated SDK omits the `X-Fern-Language`, `X-Fern-SDK-Name`, `X-Fern-SDK-Version`, and `User-Agent` headers from HTTP requests. To keep the headers but have the reported version track the published artifact rather than the generation-time version, use [`runtime-version`](#runtime-version).

---

**`includePlatformHeaders`** `boolean` — default: false

When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `com.fern.sdk/0.0.1 (linux; x86_64) Java/17.0.13`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. A configured [`user-agent`](#user-agent) template supplies the leading product token. If `omit-fern-headers` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.

---

**`allowUserAgentAppInfo`** `boolean` — default: false

When enabled, the generated client builder exposes `appInfo(String name, String version, String comment)`, which appends a `{name}/{version} ({comment})` [product token](https://www.rfc-editor.org/rfc/rfc9110#name-user-agent) to the `User-Agent` header so an application built on the SDK can identify itself to the API. The application passes a required name plus an optional version and comment; `null` drops that part of the token. An explicit `User-Agent` header takes precedence, and [`omit-fern-headers`](#omit-fern-headers) suppresses the header entirely.

```java
.appInfo("partner-app", "3.1.0", "+https://partner.example")
// User-Agent: com.fern.sdk/0.0.1 (linux; x86_64) Java/17.0.13 partner-app/3.1.0 (+https://partner.example)
```

---

**`package-layout`** `'nested' | 'flat'` — default: nested

Determines the organization of generated Java packages. Choose 'nested' for a hierarchical package structure that mirrors your API organization, or 'flat' for a simpler structure with fewer nested packages.

---

**`package-prefix`** `string`

By default, the generated SDK will use the package prefix `com.{orgName}.api`, where `{orgName}` is your Fern organization name (defined in `fern.config.json`).
To override this, you can specify the `package-prefix` field in your `generators.yml` configuration.

```
config: 
  package-prefix: my.new.package
```

---

**`publish-to`** `'central' | 'ossrh'`

Publish target for Maven packages. Use `central` for Maven Central Portal or `ossrh` for legacy Nexus Repository.

---

**`respect-optional-request-body`** `boolean` — default: false

Lets callers omit the request body on endpoints with an optional request body. A call that omits it sends no body and no `Content-Type` header, instead of an empty JSON object (`{}`). Enable this when your API treats a missing body differently from an empty one.

Each affected endpoint gains an overload without the body parameter, rather than an `Optional<T>` parameter:

```java
waterPlant(String plantId);
waterPlant(String plantId, WaterRequest request);
```

Only applies to request bodies declared as a single named type. Required bodies and inlined request properties are unaffected.

---

**`runtime-version`** `boolean` — default: false

When enabled, the generated SDK resolves the version it reports in the `X-Fern-SDK-Version` header and the [`User-Agent`](#user-agent) version segment at runtime from the jar manifest, instead of the version baked in at generation time. The generated `build.gradle` records the project version in the manifest, and the generation-time version is used as a fallback when the manifest attribute is absent. Enable this when external release tooling determines the published version after generation, so the reported version always matches the published artifact. If [`omit-fern-headers`](#omit-fern-headers) is enabled, the SDK reports no version at all and this option has no effect.

---

**`use-local-date-for-dates`** `boolean` — default: false

When enabled, generates `java.time.LocalDate` instead of `String` for Fern date types. This provides better type safety and enables compile-time validation for date values, while maintaining the same string wire format for API communication.

---

**`user-agent`** `string` — default: \{packageName}/\{version}

Sets a custom `User-Agent` header template for requests sent by the generated SDK. The template is resolved at generation time and supports the following placeholders:

* `{packageName}`: The published package name.
* `{version}`: The SDK version.
* `{language}`: The generation language (for example, `java`).
* `{generatorVersion}`: The Fern generator version.
* `{organization}`: The organization name from `fern.config.json`.
* `{apiName}`: The API name from your API definition.

**`generators.yml`**

```yaml title="generators.yml"
groups:
  java-sdk:
    generators:
      - name: fern-java-sdk
        version: 4.23.0
        config:
          user-agent: "{organization}-{apiName}/{version} ({language})"
```

With this configuration, an organization named `plantstore` with an API named `plants` generates an SDK that sends `User-Agent: plantstore-plants/0.1.0 (java)`.

With [`includePlatformHeaders`](#includeplatformheaders) enabled, the resolved value leads the structured header: a template of `plantstore-plants/{version}` sends `User-Agent: plantstore-plants/0.1.0 (linux; x86_64) Java/17.0.13`. A value that doesn't end in a version, such as `plantstore/sdk-java`, is used as-is. The [`allowUserAgentAppInfo`](#allowuseragentappinfo) token is appended after either form.

---

**`wrapped-aliases`** `boolean` — default: false

When enabled, generates wrapper types for each alias to increase type-safety.
For example, if you have an alias `ResourceId: string` then if this is true, the
generator will generate a `ResourceId.java` file. If false, it will just treat it
as `java.util.String`.

---

## Publishing metadata configuration options

If you want to customize how your publishing metadata looks in your
`build.gradle` file, update the `metadata` field in `generators.yml`.

```yml {4-9}
    generators:
      - name: fern-java-sdk
        version: 2.7.0
        metadata:
          author: "AuthorName"
          email: "example@email.com"
          package-description: "Your site description here"
          reference-url: "https://example.com"
          license: "MIT"

```

**`author`** `string`

Specifies the author name that will appear in the generated package metadata and build configuration files.

---

**`email`** `string`

Sets the contact email address for the package author that will be included in the generated package metadata.

---

**`license`** `'MIT' | 'Apache-2.0' | { custom: 'Custom License Name' }`

Defines the software license for the generated SDK. Choose from standard licenses like 'MIT' or 'Apache-2.0', or specify a custom license name.

---

**`package-description`** `string`

Provides a description of the SDK package that will appear in package metadata and documentation. This helps users understand what the SDK is for and its purpose.

---

**`reference-url`** `string`

Sets the reference URL (typically the API documentation or project website) that will be included in the package metadata for users to find additional information.

---

> Configure your Java SDK generator with custom client names, package prefixes, builder patterns, and Maven publishing options for Fern.