**Source URL:** https://general.veevavault.dev/vault-sdk/shared-code/udm.md

# User-Defined Models



A user-defined models (UDM) allows you to create reusable data access objects, or models, and annotate their getters and setters as user-defined properties. You can then use models with `JsonService` to translate data to and from JSON, or with `HttpService` to send and receive data using Vault API.

With UDMs, you can:

* Execute a VQL query against a remote Vault. First, use`HttpService` to query Vault API, then return the response body as a model, which deserializes the response JSON into fields defined by the model’s [user-defined properties](/vault-sdk/shared-code/udm/#About_User_Defined_Properties).

* Using `QueryService`, stream VQL query results that are mapped automatically to a UDM.

* Using `JsonService`, pass Vault data into a model which, based on its user-defined properties annotations, serializes the data into a JSON string which can be used as input for a REST API or stored in a Long Text field in an object record.

* Using `JsonService`, deserialize a JSON string to a UDM.

## Creating User-Defined Models {#creating-user-defined-models}

A user-defined model (UDM) is an interface that uses the `@UserDefinedModelInfo` annotation and extends the `UserDefinedModel` interface. For example, the following is an example of a UDM that represents three fields on a single document: `id`, `name__v`, and `product__v`.

```
@UserDefinedModelInfo(include = UserDefinedPropertyInclude.NON_NULL)
public interface BasicDocModel extends UserDefinedModel {

   @UserDefinedProperty()
   BigDecimal getId();
   void setId(BigDecimal id);

   @UserDefinedProperty(name = "name__v", aliases = {"name", "name__c"})
   String getName();
   void setName(String name);

   @UserDefinedProperty(name = "product__v", include = UserDefinedPropertyInclude.ALWAYS)
   ProductModel getProduct();
   void setProduct(ProductModel product);

}

```

A UDM can extend another UDM. For example, a `PresentationDocModel` might extend the `BasicDocModel`.

# About User-Defined Properties {#About_User_Defined_Properties}

The `@UserDefinedProperty` annotation can only be used on an interface with the `@UserDefinedModelInfo` annotation. All `@UserDefinedProperty` annotations must have a defined getter method with no parameters and a valid return type. Setter methods must have one parameter of a valid type. See the [Javadoc](https://repo.veevavault.com/) for valid types for getters and setters.
The `name` parameter is the JSON field name that will be serialized from and deserialized to this property. If the JSON field name is not always the same, you can define one or more aliases to be deserialized to this property.
If the JSON field name value exactly matches the getter and setter name pattern, the `name` parameter can be omitted as shown for `getId()` and `setId()` below.

You can set one or more default values using the `defaultValue` or `defaultValues` parameter. You can only set default values for properties whose type is BigDecimal, Boolean, String, or a collection of Strings.

```
@UserDefinedProperty(name = "pageoffset", aliases = {"offset"})
BigDecimal getPageOffset();

@UserDefinedProperty(defaultValue = "New Document")
String getName();

@UserDefinedProperty
BigDecimal getId();
void setId(BigDecimal id);

```

## About UserDefinedPropertyInclude {#about-userdefinedpropertyinclude}

The `UserDefinedPropertyInclude` enum specifies how `JsonService` should serialize values and is set by the `include` parameter of a user-defined model or property. If no value is set for a user-defined property, serialization defaults to the behavior of the user-defined model it belongs to. During deserialization, `JsonService` ignores any fields that are not defined in the user-defined model. Learn more in the [Javadoc](https://repo.veevavault.com/).

```
@UserDefinedModelInfo(include = UserDefinedPropertyInclude.ALWAYS)
public interface MyModel extends UserDefinedModel {

@UserDefinedProperty(include = UserDefinedPropertyInclude.NON_NULL)
String getData();
}

```

## Using User-Defined Models {#using-user-defined-models}

Use `UserDefinedModelService` to create a new, empty model instance in a trigger or action. You can then use `JsonService` to serialize and deserialize data. You can also use `HttpService` to create an HTTP request that accepts one or more user-defined models (UDMs) as the request body, or returns a UDM as the response body.

```
UserDefinedModelService modelService = ServiceLocator.locate(UserDefinedModelService.class);
BasicDocModel docModel = modelService.newUserDefinedModel(BasicDocModel.class);

JsonService jsonService = ServiceLocator.locate(JsonService.class);
String newJSON = jsonService.convertToString(docModel);

```

Once deployed, UDMs are visible in the Vault UI from **Admin** > **Configuration** > **User-Defined Models**.



---

**Previous:** [User-Defined Classes](/vault-sdk/shared-code/udc)  
**Next:** [User-Defined Services](/vault-sdk/shared-code/uds)