Moshi

https://github.com/square/moshi
Admin
Moshi is a modern JSON library for Android, Java and Kotlin that makes it easy to parse JSON into...
Tokens:58,545
Snippets:410
Trust Score:-
License:Apache-2.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### JSON example with color as integer

Source: https://github.com/square/moshi/blob/master/README.md

Example JSON object with width, height, and color fields where color is an integer.

```json
{
  "width": 1024,
  "height": 768,
  "color": "#ff0000"
}
```

--------------------------------

### Moshi.adapter

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Documentation for the Moshi.adapter method overloads, including parameters, return values, and examples.

```APIDOC
## Moshi.adapter

### Description
Returns a JsonAdapter for the given type, creating it if necessary. Overloads accept Java Type, Class, KType, or reified type parameters, with optional qualifier annotations and a field name hint for error messages.

### Method
adapter

### Signature
```kotlin
@CheckReturnValue
public fun <T> adapter(type: Type): JsonAdapter<T?>

@CheckReturnValue
public fun <T> adapter(type: Class<T>): JsonAdapter<T?>

@CheckReturnValue
public fun <T> adapter(type: Type, annotationType: Class<out Annotation>): JsonAdapter<T?>

@CheckReturnValue
public fun <T> adapter(
  type: Type,
  vararg annotationTypes: Class<out Annotation>,
): JsonAdapter<T?>

@CheckReturnValue
public fun <T> adapter(type: Type, annotations: Set<Annotation>): JsonAdapter<T?>

@JvmOverloads
@CheckReturnValue
public inline fun <reified T> adapter(
  annotations: Set<Annotation> = emptySet(),
  fieldName: String? = null,
): JsonAdapter<T>

@JvmOverloads
@CheckReturnValue
public fun <T> adapter(
  ktype: KType,
  annotations: Set<Annotation> = emptySet(),
  fieldName: String? = null,
): JsonAdapter<T>

@CheckReturnValue
public fun <T> adapter(
  type: Type,
  annotations: Set<Annotation>,
  fieldName: String?,
): JsonAdapter<T?>
```

### Parameters
- `type` (Type / Class<T> / KType / reified T) - Required - The Java/Kotlin type to build an adapter for.
- `annotationType` / `annotationTypes` (Class<out Annotation> / vararg Class<out Annotation>) - Required - JsonQualifier-annotated annotations; the qualifier implementation is synthesized via `createJsonQualifierImplementation`.
- `annotations` (Set<Annotation>) - Optional, default `emptySet()` - Qualifier annotations already instantiated.
- `fieldName` (String?) - Optional, default `null` - Hint used only to improve error messages for nested structures.

### Return Value
- `Type`-based overloads return `JsonAdapter<T?>`; the reified and `KType` overloads return `JsonAdapter<T>` and additionally finalize nullability: a nullable `T` gets `nullSafe()`, a non-null `T` gets `nonNull()` unless it is already wrapped.
- When no factory produces an adapter, an `IllegalArgumentException` ("No JsonAdapter for …") is thrown; the message is enriched with the lookup stack of in-flight type lookups.
- Creating a qualifier implementation from a non-`@JsonQualifier` annotation throws `IllegalArgumentException`.

### Example
```kotlin
val moshi = Moshi.Builder().build()

val fromClass: JsonAdapter<Card>? = moshi.adapter(Card::class.java)
val fromType: JsonAdapter<List<Card>>? = moshi.adapter(
  Types.newParameterizedType(List::class.java, Card::class.java),
)
val reified: JsonAdapter<List<Card>> = moshi.adapter<List<Card>>()
val qualified: JsonAdapter<Int>? = moshi.adapter(Int::class.java, HexColor::class.java)
```

### Error Handling
```kotlin
try {
  moshi.adapter(java.time.Instant::class.java)
} catch (e: IllegalArgumentException) {
  // "No JsonAdapter for class java.time.Instant" (+ lookup stack)
}
```
```

--------------------------------

### JsonAdapter.Factory

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonadapter.md

Documentation for the JsonAdapter.Factory interface, including its create method signature, parameters, return value, and a Kotlin example.

```APIDOC
## JsonAdapter.Factory

### Description
A functional interface for creating JsonAdapter instances. Implementations receive the requested type, qualifier annotations, and the Moshi instance, and return a JsonAdapter or null if they cannot handle the request.

### Method
create

### Signature
`public fun create(type: Type, annotations: Set<Annotation>, moshi: Moshi): JsonAdapter<*>?`

### Parameters
- **type** (Type) - Required - The requested type (canonicalized, subtype wildcards removed).
- **annotations** (Set<Annotation>) - Required - JsonQualifier annotations applied to the requested type; empty if none.
- **moshi** (Moshi) - Required - The instance to compose further adapters with (`Moshi.adapter` or `Moshi.nextAdapter`).

### Returns
JsonAdapter<*>? - The created adapter or null when the factory cannot handle the request.

### Notes
Because it is a `fun interface`, it can be implemented with a Kotlin lambda.

### Example
```kotlin
val alwaysSerializeNulls = JsonAdapter.Factory { type, annotations, moshi ->
  val rawType = type.rawType
  if (!rawType.isAnnotationPresent(AlwaysSerializeNulls::class.java)) return@Factory null
  val delegate = moshi.nextAdapter(this, type, annotations)
  delegate.serializeNulls()
}
```
```

--------------------------------

### Moshi.adapter usage examples

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Shows how to obtain JsonAdapters using different overloads: from a Class, from a parameterized Type, using a reified type, and with a qualifier annotation.

```kotlin
val moshi = Moshi.Builder().build()

val fromClass: JsonAdapter<Card>? = moshi.adapter(Card::class.java)
val fromType: JsonAdapter<List<Card>>? = moshi.adapter(
  Types.newParameterizedType(List::class.java, Card::class.java),
)
val reified: JsonAdapter<List<Card>> = moshi.adapter<List<Card>>()
val qualified: JsonAdapter<Int>? = moshi.adapter(Int::class.java, HexColor::class.java)
```

--------------------------------

### Example JSON with compact card encoding

Source: https://github.com/square/moshi/blob/master/README.md

Example JSON output showing the compact card encoding produced by the custom adapter. Cards are represented as two-character strings like "6S", "4C", and "AH".

```json
{
  "hidden_card": "6S",
  "visible_cards": [
    "4C",
    "AH"
  ]
}
```

--------------------------------

### Example JSON for BlackjackHand

Source: https://github.com/square/moshi/blob/master/README.md

Example JSON that Moshi reads and writes using the BlackjackHand and Card model classes. Shows the structure with hidden_card and visible_cards.

```json
{
  "hidden_card": {
    "rank": "6",
    "suit": "SPADES"
  },
  "visible_cards": [
    {
      "rank": "4",
      "suit": "CLUBS"
    },
    {
      "rank": "A",
      "suit": "HEARTS"
    }
  ]
}
```

--------------------------------

### Gradle setup for moshi-kotlin-codegen

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi-kotlin-codegen.md

Adds the KSP plugin and the moshi-kotlin-codegen dependency to a Gradle build. Required for compile-time adapter generation.

```kotlin
plugins { id("com.google.devtools.ksp") version "2.3.4" /* or latest */ }
dependencies { ksp("com.squareup.moshi:moshi-kotlin-codegen:2.0.0-alpha.1") }
```

--------------------------------

### JsonAdapter.Factory lambda example

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonadapter.md

Example implementation of JsonAdapter.Factory using a Kotlin lambda. It checks for the AlwaysSerializeNulls annotation, delegates to the next adapter, and enables null serialization.

```kotlin
val alwaysSerializeNulls = JsonAdapter.Factory { type, annotations, moshi ->
  val rawType = type.rawType
  if (!rawType.isAnnotationPresent(AlwaysSerializeNulls::class.java)) return@Factory null
  val delegate = moshi.nextAdapter(this, type, annotations)
  delegate.serializeNulls()
}
```

--------------------------------

### Create EnumJsonAdapter with fallback

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi-adapters.md

Example of building a Moshi instance with an EnumJsonAdapter for CurrencyCode that uses USD as a fallback for unknown strings.

```kotlin
val moshi = Moshi.Builder()
  .add(CurrencyCode::class.java, EnumJsonAdapter.create(CurrencyCode::class.java)
    .withUnknownFallback(CurrencyCode.USD))
  .build()
```

--------------------------------

### Create parameterized type and get generated adapter name

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/types.md

Shows how to create a parameterized type for a List of Card objects and obtain a JsonAdapter for it. Also demonstrates using Types.generatedJsonAdapterName to get the generated adapter class name for a given class, with an example output comment.

```kotlin
val listOfCards: Type = Types.newParameterizedType(List::class.java, Card::class.java)
val adapter: JsonAdapter<List<Card>>? = moshi.adapter(listOfCards)

val lookupName = Types.generatedJsonAdapterName(BlackjackHand::class.java)
// e.g. "com.example.BlackjackHandJsonAdapter"
```

--------------------------------

### Using Rfc3339DateJsonAdapter with Moshi

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi-adapters.md

Example usage of Rfc3339DateJsonAdapter with Moshi. It adds the adapter for Date and parses an RFC 3339 formatted date string.

```kotlin
val moshi = Moshi.Builder()
  .add(Date::class.java, Rfc3339DateJsonAdapter())
  .build()
val date = moshi.adapter<Date>().fromJson("\"2015-09-26T18:23:50.250Z\"")
```

--------------------------------

### JSON input with separate date and time fields

Source: https://github.com/square/moshi/blob/master/README.md

Example JSON representing an event with title, begin_date, and begin_time fields. This is the input that will be parsed by Moshi.

```json
{
  "title": "Blackjack tournament",
  "begin_date": "20151010",
  "begin_time": "17:04"
}
```

--------------------------------

### Error: JsonDataException example

Source: https://github.com/square/moshi/blob/master/README.md

Example of a JsonDataException thrown by Moshi when the JSON value does not match the expected enum type. The error message includes the expected values and the path to the offending field.

```text
JsonDataException: Expected one of [CLUBS, DIAMONDS, HEARTS, SPADES] but was ANCHOR at path $.visible_cards[2].suit
  at com.squareup.moshi.JsonAdapters$11.fromJson(JsonAdapters.java:188)
  at com.squareup.moshi.JsonAdapters$11.fromJson(JsonAdapters.java:180)
  ...
```

--------------------------------

### Strict mode error handling

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi-adapters.md

Example of using the adapter in strict mode, where an unknown string throws a JsonDataException with a message listing the expected enum names.

```kotlin
// Strict mode error handling.
val adapter = moshi.adapter<Suit>(Suit::class.java)
try {
  adapter.fromJson("\"ANCHOR\"")
} catch (e: JsonDataException) {
  // "Expected one of [CLUBS, DIAMONDS, HEARTS, SPADES] but was ANCHOR at path $"
}
```

--------------------------------

### JSON: Example array of card objects

Source: https://github.com/square/moshi/blob/master/README.md

A JSON array containing two card objects with 'rank' and 'suit' fields. Used as input for parsing into a List<Card>.

```json
[
  {
    "rank": "4",
    "suit": "CLUBS"
  },
  {
    "rank": "A",
    "suit": "HEARTS"
  }
]
```

--------------------------------

### JsonReader.path

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonreader.md

Property to get the current JSON path.

```APIDOC
## JsonReader.path

### Description
Property that returns the JsonPath of the current location in the JSON document, e.g., $.visible_cards[2].suit.

### Property
- **path** (String, val) - Java accessor: getPath()
```

--------------------------------

### JsonWriter.path

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonwriter.md

Property to get the current JSON path.

```APIDOC
## JsonWriter.path

### Description
Returns the `JsonPath` of the current location in the JSON document.

### Property
- **Type**: `String` (val)
- **Java accessor**: `getPath()`
```

--------------------------------

### Deprecated Moshi extension functions (hidden)

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/types.md

Deprecated extension functions on Moshi and Moshi.Builder that are hidden (DeprecationLevel.HIDDEN). Use the corresponding Moshi member functions instead. The adapter(ktype) extension applies nullability finalization: nullable types get nullSafe(), non-null types get nonNull() unless already wrapped.

```kotlin
@Deprecated("Use the Moshi instance version instead", level = DeprecationLevel.HIDDEN)
public inline fun <reified T> Moshi.adapter(): JsonAdapter<T> = adapter(typeOf<T>())

@Deprecated("Use the Moshi instance version instead", level = DeprecationLevel.HIDDEN)
public inline fun <reified T> Moshi.Builder.addAdapter(adapter: JsonAdapter<T>): Moshi.Builder =
  add(typeOf<T>(), adapter)

@Deprecated("Use the Moshi instance version instead", level = DeprecationLevel.HIDDEN)
public fun <T> Moshi.adapter(ktype: KType): JsonAdapter<T>
```

--------------------------------

### JSON example with field name containing a space

Source: https://github.com/square/moshi/blob/master/README.md

Example JSON object with a field name containing a space ('lucky number') that requires @Json annotation for mapping.

```json
{
  "username": "jesse",
  "lucky number": 32
}
```

--------------------------------

### Use @FromJson and @ToJson with a custom qualifier

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/annotations.md

Shows a complete example of using @FromJson and @ToJson with a custom @JsonQualifier (HexColor) to convert between an Int color and a hex string. The Player class demonstrates @Json(name = "lucky number") for field renaming.

```kotlin
@JsonClass(generateAdapter = true)
data class Player(
  val username: String,
  @Json(name = "lucky number") val luckyNumber: Int,
)

@Retention(RUNTIME)
@JsonQualifier
annotation class HexColor

class Rectangle(
  val width: Int,
  val height: Int,
  @HexColor val color: Int,
)

class ColorAdapter {
  @ToJson fun toJson(@HexColor rgb: Int): String = "#%06x".format(rgb)
  @FromJson @HexColor fun fromJson(rgb: String): Int = rgb.substring(1).toInt(16)
}
```

--------------------------------

### Java class with no-arguments constructor using field initializer

Source: https://github.com/square/moshi/blob/master/README.md

When a class has a no-arguments constructor, Moshi calls it and uses the field's initialized value (here, total = -1). This example shows a private no-arguments constructor alongside a public constructor that takes arguments.

```java
public final class BlackjackHand {
  private int total = -1;
  ...

  private BlackjackHand() {
  }

  public BlackjackHand(Card hidden_card, List<Card> visible_cards) {
    ...
  }
}
```

--------------------------------

### Java: Car class annotated with @AlwaysSerializeNulls

Source: https://github.com/square/moshi/blob/master/README.md

Example Java class using the custom @AlwaysSerializeNulls annotation to indicate that null fields should be serialized.

```java
@AlwaysSerializeNulls
static class Car {
  String make;
  String model;
  String color;
}
```

--------------------------------

### Kotlin: Car class annotated with @AlwaysSerializeNulls

Source: https://github.com/square/moshi/blob/master/README.md

Example Kotlin class using the custom @AlwaysSerializeNulls annotation to indicate that null properties should be serialized.

```kotlin
@AlwaysSerializeNulls
class Car(
  val make: String?,
  val model: String?,
  val color: String?
)
```

--------------------------------

### JSON output showing color not encoded properly

Source: https://github.com/square/moshi/blob/master/README.md

Example JSON output showing that encoding the Rectangle class as-is produces a color value that is not in hex format.

```json
{
  "width": 1024,
  "height": 768,
  "color": 16711680
}
```

--------------------------------

### Kotlin: Using nullSafe() to handle null JSON values

Source: https://github.com/square/moshi/blob/master/README.md

Kotlin version of the nullSafe() example. Demonstrates the same behavior: without nullSafe(), parsing null throws JsonDataException; with nullSafe(), it returns null.

```kotlin
val dateJson = "\"2018-11-26T11:04:19.342668Z\""
val nullDateJson = "null"

// Hypothetical IsoDateDapter, doesn't support null by default
val adapter: JsonAdapter<Date> = IsoDateDapter()

val date = adapter.fromJson(dateJson)
println(date) // Mon Nov 26 12:04:19 CET 2018

val nullDate = adapter.fromJson(nullDateJson)
// Exception, com.squareup.moshi.JsonDataException: Expected a string but was NULL at path $

val nullDate = adapter.nullSafe().fromJson(nullDateJson)
println(nullDate) // null
```

--------------------------------

### Serialize Object to JSON with Moshi (Java)

Source: https://github.com/square/moshi/blob/master/README.md

Serializes a BlackjackHand object to a JSON string using Moshi's JsonAdapter. The example constructs a BlackjackHand with a hidden card and visible cards.

```java
BlackjackHand blackjackHand = new BlackjackHand(
    new Card('6', SPADES),
    Arrays.asList(new Card('4', CLUBS), new Card('A', HEARTS)));

Moshi moshi = new Moshi.Builder().build();
JsonAdapter<BlackjackHand> jsonAdapter = moshi.adapter(BlackjackHand.class);

String json = jsonAdapter.toJson(blackjackHand);
System.out.println(json);
```

--------------------------------

### Java: Using nullSafe() to handle null JSON values

Source: https://github.com/square/moshi/blob/master/README.md

Shows how to use the nullSafe() adapter method to avoid JsonDataException when parsing null JSON. The example uses a hypothetical IsoDateDapter that doesn't support null by default. Without nullSafe(), parsing null throws JsonDataException; with nullSafe(), it returns null.

```java
String dateJson = "\"2018-11-26T11:04:19.342668Z\"";
String nullDateJson = "null";

// Hypothetical IsoDateDapter, doesn't support null by default
JsonAdapter<Date> adapter = new IsoDateDapter();

Date date = adapter.fromJson(dateJson);
System.out.println(date); // Mon Nov 26 12:04:19 CET 2018

Date nullDate = adapter.fromJson(nullDateJson);
// Exception, com.squareup.moshi.JsonDataException: Expected a string but was NULL at path $

Date nullDate = adapter.nullSafe().fromJson(nullDateJson);
System.out.println(nullDate); // null
```

--------------------------------

### Moshi.nextAdapter

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Documentation for the Moshi.nextAdapter method, including parameters and return behavior.

```APIDOC
## Moshi.nextAdapter

### Description
Returns the adapter from the next factory after `skipPast` in the chain, or throws `IllegalArgumentException` if none can create it. This is the primary composition hook for `JsonAdapter.Factory.create` implementations.

### Method
nextAdapter

### Signature
```kotlin
@CheckReturnValue
public fun <T> nextAdapter(
  skipPast: JsonAdapter.Factory,
  type: Type,
  annotations: Set<Annotation>,
): JsonAdapter<T>
```

### Parameters
- `skipPast` (JsonAdapter.Factory) - Required - The factory to skip past in the chain.
- `type` (Type) - Required - The type to build an adapter for.
- `annotations` (Set<Annotation>) - Required - Qualifier annotations.

### Return Value
- Returns a `JsonAdapter<T>` from the next factory after `skipPast`.
- Throws `IllegalArgumentException` if no factory can create it ("No next JsonAdapter for …").
- Throws `IllegalArgumentException` if `skipPast` is not registered ("Unable to skip past unknown factory $skipPast").
```

--------------------------------

### Moshi.newBuilder

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Documentation for the Moshi.newBuilder method.

```APIDOC
## Moshi.newBuilder

### Description
Returns a new `Builder` pre-populated with all custom factories of this instance — `add`-registered ones first, then `addLast`-registered ones.

### Method
newBuilder

### Signature
```kotlin
@CheckReturnValue
public fun newBuilder(): Builder
```

### Return Value
- Returns a new `Builder` instance.
```

--------------------------------

### Using nullSafe, indent, and failOnUnknown

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonadapter.md

Shows how to wrap an adapter with nullSafe() to accept null, indent() for pretty printing, and failOnUnknown() for strict parsing.

```kotlin
val adapter: JsonAdapter<Date> = IsoDateAdapter() // rejects null
val nullDate = adapter.nullSafe().fromJson("null") // null, no exception
val pretty: JsonAdapter<List<Card>> = moshi.adapter<List<Card>>().indent("  ")
val strict = moshi.adapter<Player>().failOnUnknown()
```

--------------------------------

### Update versions, tag release, and prepare next version

Source: https://github.com/square/moshi/blob/master/releasing.md

Updates version references in gradle.properties and README files, commits and tags the release, then prepares the next development version and pushes everything. This triggers a GitHub Action workflow that creates a GitHub release and uploads artifacts to Maven Central.

```bash
sed -i "" \
  "s/VERSION_NAME=.*/VERSION_NAME=$RELEASE_VERSION/g" \
  gradle.properties
sed -i "" \
  "s/\"com.squareup.moshi:\([^\:]*\):[0-9.]*\"/\"com.squareup.moshi:\1:$RELEASE_VERSION\"/g" \
  `find . -name "README.md"`

git commit -am "Prepare version $RELEASE_VERSION."
git tag -am "Version $RELEASE_VERSION" $RELEASE_VERSION

sed -i "" \
  "s/VERSION_NAME=.*/VERSION_NAME=$NEXT_VERSION/g" \
  gradle.properties
git commit -am "Prepare next development version."
git push && git push --tags
```

--------------------------------

### beginFlatten()

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonwriter.md

Documentation for the beginFlatten() method of JsonWriter.

```APIDOC
## beginFlatten()

### Description
Cancels the begin/end pair of the immediately nested array/object, so a delegating adapter's structure merges into the current one. Returns an opaque token that must be passed to endFlatten().

### Method
Function

### Signature
`@CheckReturnValue public fun beginFlatten(): Int`

### Parameters
None.

### Return Value
- `Int` - an opaque token to be used with `endFlatten(token)`.

### Behavior
- Cancels the begin/end pair of the immediately nested array/object, so a delegating adapter's structure merges into the current one (`[1,[2,3,4],5]` → `[1,2,3,4,5]`; objects inside objects similarly).
- Returns an opaque token; `endFlatten(token)` must be called with the matching token.
- Do not call `name()` before writing a flattened object.

### Example
```kotlin
// Flatten a delegate adapter's list into the enclosing array.
fun writeNumbers(writer: JsonWriter) {
  writer.beginArray()
  val token = writer.beginFlatten()
  writer.value(1)
  integersAdapter.toJson(writer, listOf(2, 3, 4)) // writes [2,3,4]
  writer.value(5)
  writer.endFlatten(token)
  writer.endArray()
}
// Result: [1, 2, 3, 4, 5]
```
```

--------------------------------

### Composing via a delegating factory

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Shows how to compose behavior by registering a factory that delegates to the next adapter. The comment indicates the factory delegates to the next adapter.

```kotlin
// Composing via a factory that delegates to the next adapter.
val moshi = Moshi.Builder()
  .add(AlwaysSerializeNullsFactory())
  .build()
```

--------------------------------

### Lenient reading with failOnUnknown

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonreader.md

Enables lenient reading with failOnUnknown to throw on unknown tokens. Catches JsonDataException with example message.

```kotlin
// Lenient reading with error handling for unknown fields.
val reader = JsonReader.of(source)
reader.failOnUnknown = true
try {
  parseDocuments(reader) // skipValue()/skipName() now throw on unknown tokens
} catch (e: JsonDataException) {
  // e.g. "Cannot skip unexpected NAME at $.widget"
}
```

--------------------------------

### beginObject

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonreader.md

Consumes the beginning of an object token.

```APIDOC
## beginObject

### Description
Consumes the next token as the beginning of an object (`{`). Throws `JsonDataException` if the next token is not `BEGIN_OBJECT`.

### Method
beginObject

### Signature
`@Throws(IOException::class) public abstract fun beginObject()`

### Parameters
None

### Return Type
`Unit`

### Exceptions
- `IOException` - in practice `JsonEncodingException` for malformed syntax, `JsonDataException` for type mismatches.
- `JsonDataException` - if the next token is not `BEGIN_OBJECT`.

```

--------------------------------

### JsonReader.Options

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonreader.md

Documentation for the `JsonReader.Options` nested class, including its constructor, methods, and companion object factory.

```APIDOC
## `JsonReader.Options`

### Description
Pre-computes the encoded byte forms of the candidate strings (plus their double-quote suffixes) so that `selectName`/`selectString` can match directly against the input source. `Options.of` takes a vararg of strings; `strings()` returns a copy of them. Any `IOException` during pre-encoding is impossible and rethrown as `AssertionError`.

### Constructor
```kotlin
private constructor(
  internal val strings: Array<out String>,
  internal val doubleQuoteSuffix: OkioOptions,
)
```

### Methods

#### `strings`
```kotlin
public fun strings(): List<String>
```
Returns a copy of the candidate strings.

#### Companion Object

##### `of`
```kotlin
@CheckReturnValue
@JvmStatic
public fun of(vararg strings: String): Options
```
Creates an `Options` instance from the given strings.
```

--------------------------------

### build()

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Freezes the configuration into a Moshi instance. After calling build, the builder should not be modified.

```APIDOC
## build()

### Description
Freezes the configuration into a Moshi instance. After calling build, the builder should not be modified.

### Method
build

### Signature
```kotlin
@CheckReturnValue public fun build(): Moshi
```

### Parameters
None.

### Returns
- `Moshi` - The configured Moshi instance.

### Example
```kotlin
val moshi = Moshi.Builder()
  .add(CardAdapter())
  .add(CurrencyCode::class.java, EnumJsonAdapter.create(CurrencyCode::class.java))
  .addLast(KotlinJsonAdapterFactory())
  .build()
```
```

--------------------------------

### Registering adapters with add and addLast

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Shows how to register adapters with different precedence: add() for specific adapters and addLast() for a general factory with lowest precedence. The comment marks KotlinJsonAdapterFactory as the lowest precedence general factory.

```kotlin
val moshi = Moshi.Builder()
  .add(CardAdapter())                                  // @ToJson/@FromJson object
  .add(CurrencyCode::class.java, EnumJsonAdapter.create(CurrencyCode::class.java))
  .addLast(KotlinJsonAdapterFactory())                 // lowest precedence general factory
  .build()
```

--------------------------------

### Moshi.adapter error handling

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Demonstrates catching the IllegalArgumentException thrown when no factory can produce an adapter for a type, with the error message including the lookup stack.

```kotlin
// Error handling: missing adapter.
try {
  moshi.adapter(java.time.Instant::class.java)
} catch (e: IllegalArgumentException) {
  // "No JsonAdapter for class java.time.Instant" (+ lookup stack)
}
```

--------------------------------

### Ignore a field with @Json(ignore = true)

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/annotations.md

Demonstrates the @Json(ignore = true) annotation: the field is omitted during serialization and gets its default value during deserialization.

```kotlin
// @Json(ignore = true): omitted on write, default value on read.
class BlackjackHand(
  val hidden_card: Card,
  val visible_cards: List<Card>,
  @Json(ignore = true) var total: Int = 0,
)
```

--------------------------------

### Set release version environment variables

Source: https://github.com/square/moshi/blob/master/releasing.md

Sets the release and next development version environment variables used by subsequent commands.

```bash
export RELEASE_VERSION=X.Y.Z
export NEXT_VERSION=X.Y.Z-SNAPSHOT
```

--------------------------------

### EnumJsonAdapter companion create method

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi-adapters.md

The companion factory method to create an EnumJsonAdapter instance. It returns a strict adapter that throws on unknown strings.

```kotlin
public companion object {
  @JvmStatic
  public fun <T : Enum<T>> create(enumType: Class<T>): EnumJsonAdapter<T> {
    return EnumJsonAdapter(enumType, fallbackValue = null, useFallbackValue = false)
  }
}
```

--------------------------------

### KotlinJsonAdapterFactory

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi-kotlin.md

Documentation for the KotlinJsonAdapterFactory class, including its constructor, create method, and behavior.

```APIDOC
## KotlinJsonAdapterFactory

### Description
Creates a reflective JSON adapter for Kotlin classes, understanding non-nullable types, default parameter values, `@Json`, qualifiers, and inline (value) classes. It is enabled with the `addLast()` builder method so that user adapters take precedence.

### Constructor
- `KotlinJsonAdapterFactory()` - No-argument constructor.

### Method
- `create(type: Type, annotations: Set<Annotation>, moshi: Moshi): JsonAdapter<*>?` - Returns a `JsonAdapter` for the given type, or `null` if not applicable.

### Behavior
- Returns `null` when:
  - `annotations.isNotEmpty()`
  - The raw type is an interface or enum
  - The type has no `kotlin.Metadata` annotation
  - The type is a Java platform type
- Otherwise, attempts to load a generated adapter; if not found, falls back to the reflective adapter.
- Rejects with `IllegalArgumentException` for:
  - Local class or object expression
  - Anonymous class
  - Abstract class
  - Inner class
  - Object declaration
  - Companion object
  - Sealed class
  - Transient/ignored constructor parameter without default
  - Required constructor parameter without property
  - Constructor/property type mismatch
- Returns `null` when no primary constructor exists.

### Example
```kotlin
val moshi = Moshi.Builder()
  .addLast(KotlinJsonAdapterFactory())
  .build()
```
```

--------------------------------

### beginArray

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonreader.md

Consumes the beginning of an array token.

```APIDOC
## beginArray

### Description
Consumes the next token as the beginning of an array (`[`). Throws `JsonDataException` if the next token is not `BEGIN_ARRAY`.

### Method
beginArray

### Signature
`@Throws(IOException::class) public abstract fun beginArray()`

### Parameters
None

### Return Type
`Unit`

### Exceptions
- `IOException` - in practice `JsonEncodingException` for malformed syntax, `JsonDataException` for type mismatches.
- `JsonDataException` - if the next token is not `BEGIN_ARRAY`.

```

--------------------------------

### promoteValueToName()

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonwriter.md

Documentation for the promoteValueToName() method of JsonWriter.

```APIDOC
## promoteValueToName()

### Description
Promotes the next value to be written as a property name instead of a value, supporting map adapters. Only valid inside an object scope.

### Method
Function

### Signature
`@Throws(IOException::class) public fun promoteValueToName()`

### Parameters
None.

### Behavior
- The next value is written as a property name instead of a value (map adapter support): `{"a": "b"}` from two `value` calls.
- Only valid inside an object scope.

### Exceptions
- `IOException` - may be thrown during writing.

### Example
```kotlin
// Example usage (conceptual)
writer.beginObject()
writer.promoteValueToName()
writer.value("a")
writer.value("b")
writer.endObject()
// Result: {"a":"b"}
```
```

--------------------------------

### Kotlin: Register KotlinJsonAdapterFactory with addLast()

Source: https://github.com/square/moshi/blob/master/README.md

Use this to enable Moshi's Kotlin reflection adapter. Add it last so custom adapters take precedence. Requires the moshi-kotlin dependency.

```kotlin
val moshi = Moshi.Builder()
    .addLast(KotlinJsonAdapterFactory())
    .build()
```

--------------------------------

### Register EventJsonAdapter with Moshi (Java and Kotlin)

Source: https://github.com/square/moshi/blob/master/README.md

Shows how to register the custom adapter with a Moshi instance. The Java version uses `new EventJsonAdapter()`, while the Kotlin version uses `EventJsonAdapter()`.

```java
Moshi moshi = new Moshi.Builder()
    .add(new EventJsonAdapter())
    .build();
```

```kotlin
val moshi = Moshi.Builder()
    .add(EventJsonAdapter())
    .build()
```

--------------------------------

### Moshi.Builder method signatures

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Lists the public methods of Moshi.Builder. add() inserts at the front section; addLast() appends after all add() registrations, maintaining insertion order within each section. Built-in factories are always last. The table describes each overload's required parameters and matching behavior.

```kotlin
@CheckReturnValue
public inline fun <reified T> addAdapter(adapter: JsonAdapter<T>): Builder

public fun <T> add(type: KType, jsonAdapter: JsonAdapter<T>): Builder

public fun <T> add(type: Type, jsonAdapter: JsonAdapter<T>): Builder

public fun <T> add(
  type: Type,
  annotation: Class<out Annotation>,
  jsonAdapter: JsonAdapter<T>,
): Builder

public fun add(factory: JsonAdapter.Factory): Builder

public fun add(adapter: Any): Builder

@Suppress("unused")
public fun <T> addLast(type: Type, jsonAdapter: JsonAdapter<T>): Builder

@Suppress("unused")
public fun <T> addLast(
  type: Type,
  annotation: Class<out Annotation>,
  jsonAdapter: JsonAdapter<T>,
): Builder

public fun addLast(factory: JsonAdapter.Factory): Builder

@Suppress("unused")
public fun addLast(adapter: Any): Builder

@CheckReturnValue public fun build(): Moshi
```

--------------------------------

### indent(indent: String)

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonadapter.md

Returns a new adapter that indents JSON output with the given whitespace string.

```APIDOC
## indent(indent: String)

### Description
Returns a new adapter that repeats `indent` (whitespace only) per level when writing; empty string produces compact output.

### Method
indent

### Signature
`public fun indent(indent: String): JsonAdapter<T>`

### Parameters
- **indent** (String) - Required - The whitespace string to repeat per level when writing.

### Return Type
`JsonAdapter<T>`

### Behavior
Repeats `indent` (whitespace only) per level when writing; empty string produces compact output.
```

--------------------------------

### Using KotlinJsonAdapterFactory with Moshi

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi-kotlin.md

Builds a Moshi instance with the adapter and deserializes a BlackjackHand, honoring Kotlin defaults and nullability.

```kotlin
val moshi = Moshi.Builder()
  .addLast(KotlinJsonAdapterFactory())
  .build()

val jsonAdapter = moshi.adapter<BlackjackHand>()
val hand = jsonAdapter.fromJson(json) // Kotlin defaults and nullability are honored
```

--------------------------------

### promoteNameToValue

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonreader.md

Treats the next name as a string value.

```APIDOC
## promoteNameToValue

### Description
Treats the next name as a string value so two sequential `nextString()` calls read `"a"` then `"b"` in `{"a":"b"}` (used by map adapters).

### Method
promoteNameToValue

### Signature
`@Throws(IOException::class) public abstract fun promoteNameToValue()`

### Parameters
None

### Return Type
`Unit`

### Exceptions
- `IOException` - in practice `JsonEncodingException` for malformed syntax, `JsonDataException` for type mismatches.

```

--------------------------------

### add(adapter: Any)

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Registers an adapter object. The object's @ToJson and @FromJson methods are wrapped into a factory via AdapterMethodsFactory.

```APIDOC
## add(adapter: Any)

### Description
Registers an adapter object. The object's @ToJson and @FromJson methods are wrapped into a factory via AdapterMethodsFactory.

### Method
add

### Signature
```kotlin
public fun add(adapter: Any): Builder
```

### Parameters
- `adapter` (Any) - Required - The adapter object containing @ToJson/@FromJson methods.

### Returns
- `Builder` - This builder instance for chaining.

### Example
```kotlin
val builder = Moshi.Builder().add(CardAdapter())
```
```

--------------------------------

### lenient()

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonadapter.md

Returns a new adapter that enables lenient parsing and writing.

```APIDOC
## lenient()

### Description
Returns a new adapter that sets `reader.lenient`/`writer.isLenient` to `true` for the duration of the call, restoring afterwards.

### Method
lenient

### Signature
`public fun lenient(): JsonAdapter<T>`

### Parameters
None

### Return Type
`JsonAdapter<T>`

### Behavior
Sets `reader.lenient`/`writer.isLenient` to `true` for the duration of the call, restoring afterwards.
```

--------------------------------

### Moshi.nextAdapter declaration

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Returns the adapter from the next factory after skipPast in the chain, or throws IllegalArgumentException if none can create it. Fails with "Unable to skip past unknown factory $skipPast" if skipPast is not registered.

```kotlin
@CheckReturnValue
public fun <T> nextAdapter(
  skipPast: JsonAdapter.Factory,
  type: Type,
  annotations: Set<Annotation>,
): JsonAdapter<T>
```

--------------------------------

### add(factory: JsonAdapter.Factory)

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Registers a JsonAdapter.Factory. The factory is invoked for every type with no annotations of its own constraining it.

```APIDOC
## add(factory: JsonAdapter.Factory)

### Description
Registers a JsonAdapter.Factory. The factory is invoked for every type with no annotations of its own constraining it.

### Method
add

### Signature
```kotlin
public fun add(factory: JsonAdapter.Factory): Builder
```

### Parameters
- `factory` (JsonAdapter.Factory) - Required - The factory to register.

### Returns
- `Builder` - This builder instance for chaining.

### Example
```kotlin
val builder = Moshi.Builder().add(MyFactory())
```
```

--------------------------------

### Moshi.Builder with custom adapter and KotlinJsonAdapterFactory

Source: https://github.com/square/moshi/blob/master/_autodocs/configuration.md

Registers a custom adapter with highest precedence and adds KotlinJsonAdapterFactory as a reflective fallback with lowest custom precedence. The built-in adapter chain is appended after all user factories.

```kotlin
val moshi = Moshi.Builder()
  .add(CardAdapter())              // custom: highest precedence
  .addLast(KotlinJsonAdapterFactory()) // reflective fallback: lowest custom precedence
  .build()
```

--------------------------------

### JsonClassSymbolProcessorProvider implementation

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi-kotlin-codegen.md

Registers the KSP symbol processor provider via @AutoService so KSP discovers it automatically. No manual registration is needed.

```kotlin
@AutoService(SymbolProcessorProvider::class)
public class JsonClassSymbolProcessorProvider : SymbolProcessorProvider {
  override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
    return JsonClassSymbolProcessor(environment)
  }
}
```

--------------------------------

### add(type: KType, jsonAdapter: JsonAdapter<T>)

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Registers an adapter for an exact type specified by a KType. The adapter will be used when the target type matches exactly and no annotations are present.

```APIDOC
## add(type: KType, jsonAdapter: JsonAdapter<T>)

### Description
Registers an adapter for an exact type specified by a KType. The adapter will be used when the target type matches exactly and no annotations are present.

### Method
add

### Signature
```kotlin
public fun <T> add(type: KType, jsonAdapter: JsonAdapter<T>): Builder
```

### Parameters
- `type` (KType) - Required - The exact type for which the adapter is registered.
- `jsonAdapter` (JsonAdapter<T>) - Required - The adapter to use for the specified type.

### Returns
- `Builder` - This builder instance for chaining.

### Example
```kotlin
val builder = Moshi.Builder().add(typeOf<MyType>(), MyAdapter())
```
```

--------------------------------

### nullSafe()

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonadapter.md

Returns a new adapter that supports null values.

```APIDOC
## nullSafe()

### Description
Returns a new adapter that supports reading and writing `null`. If already a `NullSafeJsonAdapter`, returns itself.

### Method
nullSafe

### Signature
`public fun nullSafe(): JsonAdapter<T?>`

### Parameters
None

### Return Type
`JsonAdapter<T?>`

### Behavior
Supports reading/writing `null`. If already a `NullSafeJsonAdapter`, returns itself.
```

--------------------------------

### Register CardAdapter with Moshi.Builder (Java)

Source: https://github.com/square/moshi/blob/master/README.md

Registers the custom CardAdapter with a Moshi.Builder in Java. After this, Moshi will use the adapter for Card serialization and deserialization.

```java
Moshi moshi = new Moshi.Builder()
    .add(new CardAdapter())
    .build();
```

--------------------------------

### nextSource

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonreader.md

Returns the next value as raw UTF-8 bytes.

```APIDOC
## nextSource

### Description
Returns the next value as raw UTF-8 bytes (whitespace preserved, unvalidated). The source may not be used after any other `JsonReader` method; closing it does not close the reader.

### Method
nextSource

### Signature
`@Throws(IOException::class) public abstract fun nextSource(): BufferedSource`

### Parameters
None

### Return Type
`BufferedSource` - the raw UTF-8 bytes of the next value.

### Exceptions
- `IOException` - in practice `JsonEncodingException` for malformed syntax, `JsonDataException` for type mismatches.

```

--------------------------------

### Moshi.Builder class declaration

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Shows the internal state of Moshi.Builder: a mutable list of JsonAdapter.Factory and an offset used to separate add() from addLast() registrations. Registration order defines adapter precedence; the first factory that can create an adapter wins.

```kotlin
public class Builder {
  internal val factories = mutableListOf<JsonAdapter.Factory>()
  internal var lastOffset = 0
  ...
}
```

--------------------------------

### Parse JSON to Event using Moshi (Java and Kotlin)

Source: https://github.com/square/moshi/blob/master/README.md

Shows how to obtain a JsonAdapter for Event and parse JSON into an Event object. The Java version uses `Event.class`, while the Kotlin version uses `Event::class.java`.

```java
JsonAdapter<Event> jsonAdapter = moshi.adapter(Event.class);
Event event = jsonAdapter.fromJson(json);
```

```kotlin
val jsonAdapter = moshi.adapter<Event>()
val event = jsonAdapter.fromJson(json)
```

--------------------------------

### JsonWriter.of

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonwriter.md

Factory method to create a JsonWriter instance from an Okio BufferedSink.

```APIDOC
## JsonWriter.of

### Description
Creates a new `JsonWriter` that writes UTF-8 encoded JSON to the given Okio `BufferedSink`. The writer writes one token at a time and is not thread-safe.

### Method
Factory function

### Parameters
- **sink** (`BufferedSink`) - Required - Okio sink receiving UTF-8 encoded JSON.

### Returns
A new `JsonWriter` instance.

### Exceptions
- `IllegalStateException` - If a call would produce malformed JSON (e.g., "Nesting problem." or "JsonWriter is closed.").
```

--------------------------------

### addLast(adapter: Any)

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/moshi.md

Registers an adapter object, but appends it after all add() registrations. The object's @ToJson and @FromJson methods are wrapped into a factory via AdapterMethodsFactory.

```APIDOC
## addLast(adapter: Any)

### Description
Registers an adapter object, but appends it after all add() registrations. The object's @ToJson and @FromJson methods are wrapped into a factory via AdapterMethodsFactory.

### Method
addLast

### Signature
```kotlin
@Suppress("unused")
public fun addLast(adapter: Any): Builder
```

### Parameters
- `adapter` (Any) - Required - The adapter object containing @ToJson/@FromJson methods.

### Returns
- `Builder` - This builder instance for chaining.

### Example
```kotlin
val builder = Moshi.Builder().addLast(MyAdapter())
```
```

--------------------------------

### Register CardAdapter with Moshi.Builder (Kotlin)

Source: https://github.com/square/moshi/blob/master/README.md

Registers the custom CardAdapter with a Moshi.Builder in Kotlin. After this, Moshi will use the adapter for Card serialization and deserialization.

```kotlin
val moshi = Moshi.Builder()
    .add(CardAdapter())
    .build()
```

--------------------------------

### NullSafeJsonAdapter and NonNullJsonAdapter definitions

Source: https://github.com/square/moshi/blob/master/_autodocs/types.md

Public classes in the internal package, obtained via `JsonAdapter.nullSafe()` / `JsonAdapter.nonNull()`. NullSafe delegates null handling; NonNull throws `JsonDataException` on null read/write. Used by `Moshi.adapter(KType, ...)` nullability finalization and `PolymorphicJsonAdapterFactory.create`.

```kotlin
public class NullSafeJsonAdapter<T>(public val delegate: JsonAdapter<T>) : JsonAdapter<T?>() {
  // peek()==NULL -> nextNull(); otherwise delegates
  // null value -> writer.nullValue(); otherwise delegates
}
```

```kotlin
public class NonNullJsonAdapter<T>(public val delegate: JsonAdapter<T>) : JsonAdapter<T?>() {
  // null on read/write -> JsonDataException("Unexpected null at <path>")
}
```

--------------------------------

### selectName(options)

Source: https://github.com/square/moshi/blob/master/_autodocs/api-reference/jsonreader.md

Selects a name from a set of options, consuming it if found.

```APIDOC
## selectName(options)

### Description
If the next name is in `options`, consumes it and returns its index; otherwise returns `-1` without consuming. Uses optimized string matching built by `Options`.

### Method
selectName

### Signature
`@CheckReturnValue @Throws(IOException::class) public abstract fun selectName(options: Options): Int`

### Parameters
- `options` (Options) - Required - The set of names to match against.

### Return Type
`Int` - the index of the matched name, or `-1` if not found.

### Exceptions
- `IOException` - in practice `JsonEncodingException` for malformed syntax, `JsonDataException` for type mismatches.

```
Tokens:
Raw