# AppFunctionSerializable

Artifact: [androidx.appfunctions:appfunctions](https://developer.android.com/jetpack/androidx/releases/appfunctions) [View Source](https://cs.android.com/search?q=file:androidx/appfunctions/AppFunctionSerializable.kt+class:androidx.appfunctions.AppFunctionSerializable) Added in [1.0.0-rc01](https://developer.android.com/jetpack/androidx/releases/appfunctions#1.0.0-rc01)

*** ** * ** ***


```
@Retention(value = AnnotationRetention.BINARY)
@Target(allowedTargets = [AnnotationTarget.CLASS])
public annotation AppFunctionSerializable
```

<br />

*** ** * ** ***

Annotates a class to indicate that it can be serialized and transferred between processes using AppFunction.

When a class is annotated with `@AppFunctionSerializable` and is used as a parameter or return type (directly or as a nested entity) in an AppFunction, the shape of the entity defined within its primary constructor will be exposed to the caller as part of an `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionMetadata`. This information allows the caller to construct the structured input to call an AppFunction or understand what properties are provided in the structured output.

**Constraints for Classes Annotated with `@AppFunctionSerializable`:**

- **Primary Constructor Parameters:** Only properties declared in the primary constructor that expose a getter method are eligible for inclusion in the AppFunctionMetadata. Critically, it is a **requirement** to place properties with a getter in primary constructor. Attempting to include constructor parameters that are not declared as properties (and thus don't have a getter) will result in a compiler error.

- **Supported Property Types:** The properties in the primary constructor must be of one of the following types:

  - `Int`

  - `Long`

  - `Float`

  - `Double`

  - `Boolean`

  - `String`

  - `IntArray`

  - `LongArray`

  - `FloatArray`

  - `DoubleArray`

  - `BooleanArray`

  - `List<String>`

  - Another class annotated with `@AppFunctionSerializable` (enabling nested structures) or a list of a class annotated with `@AppFunctionSerializable`

  - Supported proxy types: `https://developer.android.com/reference/android/net/Uri.html`, `https://developer.android.com/reference/java/time/LocalDate.html`, `https://developer.android.com/reference/java/time/LocalTime.html`, `https://developer.android.com/reference/java/time/LocalDateTime.html`, `https://developer.android.com/reference/java/time/Instant.html`, `https://developer.android.com/reference/java/time/ZoneId.html`, or a `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` of these types

  - Any implementation of `https://developer.android.com/reference/android/os/Parcelable.html` type. For `Parcelable` types not defined by the Android platform (e.g., custom classes shared between agents and apps), forward and backward compatibility is **not guaranteed** by AppFunctions library. Implementers are responsible for managing any compatibility and versioning concerns.

- **Public Primary Constructor:** The primary constructor of the annotated class must have public visibility to allow instantiation.

**IMPORTANT:** When the default value is set in the constructor parameter, the field would be exposed to the caller as optional in the `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionObjectTypeMetadata`. However, the default value is ignored when the value is missing from the function calling request. Instead, the specified rule is always used:

- For non-nullable primitive types, the JVM default for that type is used (e.g., `0` for `Int`).

- For non-nullable collection types, an empty collection is provided.

- For nullable types, the value will be `null`.

- Any other types are not allowed to be optional.

**Example:**

```
/** The location. */
@AppFunctionSerializable(isDescribedByKDoc = true)
class Location(val latitude: Double, val longitude: Double)

/** The place. */
@AppFunctionSerializable(isDescribedByKDoc = true)
class Place(
    val name: String,
    val location: Location, // Nested AppFunctionSerializable
    // Nullable String is allowed, if missing, will be null. The default value will not be used
    // when the value is missing
    val notes: String? = "default"
)

/** The search place result. */
@AppFunctionSerializable(isDescribedByKDoc = true)
class SearchPlaceResult(
    val places: List<Place> // If missing, will be an empty list
)

/** The attachment. */
@AppFunctionSerializable(isDescribedByKDoc = true)
class Attachment(
  uri: String // Putting constructor parameter without getter will result in compiler error
)
```

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionObjectTypeMetadata` |   |

## Summary

| ### Public methods |
|---|---|
| `final boolean` | `https://developer.android.com/reference/androidx/appfunctions/AppFunctionSerializable#isDescribedByKDoc()()` Whether to use the serializable's KDoc as the type's description to the agent. |

## Public methods

### isDescribedByKDoc

Added in [1.0.0-rc01](https://developer.android.com/jetpack/androidx/releases/appfunctions#1.0.0-rc01)

```
public final boolean isDescribedByKDoc()
```

Whether to use the serializable's KDoc as the type's description to the agent.

If set to `true`, the serializable's KDoc will be set as the type's `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionDataTypeMetadata#description()`. The class's properties' KDoc will also be set as their corresponding descriptions. The caller will use the descriptions to interpret when and how to use the class and its properties.