Data Transfer Object (DTO)

DTO is any object of the class which extends oatpp::data::mapping::type::Object. It is a special object which can be Serialized and Deserialized with the help of oatpp::data::mapping::ObjectMapper.


DTO objects are generated withing DTO-code-gen section. DTO code generation section must begin with
#include OATPP_CODEGEN_BEGIN(DTO) and must be closed with #include OATPP_CODEGEN_END(DTO). Do not forget to close code generation section in order to avoid macro conflicts later in the code!

#include "oatpp/core/data/mapping/type/Object.hpp"
#include "oatpp/core/macro/codegen.hpp"

#include OATPP_CODEGEN_BEGIN(DTO) ///< Begin DTO codegen section

class User : public oatpp::data::mapping::type::Object {

  DTO_INIT(User, Object /* extends */)

  DTO_FIELD(String, name);
  DTO_FIELD(Int32, age);


#include OATPP_CODEGEN_END(DTO) ///< End DTO codegen section

Field Name Qualifier

DTO_FIELD(String, name, "user-name");

Default Value

By default all values are set to nullptr. You can override default values by assigning values to DTO fields.

DTO_FIELD(String, name) = "Ivan";

Primitive Types

Predefined primitive types

  • String - ObjectWrapper over oatpp::base::StrBuffer. Can be null.
  • Int8 - Signed 8-bit integer. ObjectWrapper over v_int8. Can be null.
  • UInt8 - Unsigned 8-bit integer. ObjectWrapper over v_uint8. Can be null.
  • Int16 - Signed 16-bit integer. ObjectWrapper over v_int16. Can be null.
  • UInt16 - Unsigned 16-bit integer. ObjectWrapper over v_uint16. Can be null.
  • Int32 - Signed 32-bit integer. ObjectWrapper over v_int32. Can be null.
  • UInt32 - Unsigned 32-bit integer. ObjectWrapper over v_uint32. Can be null.
  • Int64 - Signed 64-bit integer. ObjectWrapper over v_int64. Can be null.
  • UInt64 - Unsigned 64-bit integer. ObjectWrapper over v_uint64. Can be null.
  • Float32 - 32-bit float. ObjectWrapper over v_float32. Can be null.
  • Float64 - 64-bit float. ObjectWrapper over v_float64. Can be null.
  • Boolean - ObjectWrapper over bool. Can be null.

Assign value

String s = "Hello!";
Int32 a = 32;
Boolean b = true;

Note: By default all values are set to nullptr.

Get value as primitive

Int32 a = 32;
Boolean b = true;

v_int32 ap = a->getValue();
bool bp = b->getValue();


Predefined collections

  • List<T> - LinkedList of T. Can be null.
  • Fields<T> - ListMap<String, T>. Can be null.
    With Fields you always map String to other type.

Declare Field As List

List of primitives:

DTO_FIELD(List<Int32>::ObjectWrapper, colors);

List of Objects:

DTO_FIELD(List<MyObject::ObjectWrapper>::ObjectWrapper, colors);

Declare Field As Map

Map String --> Int32:

DTO_FIELD(Fields<Int32>::ObjectWrapper, colors);

Map String --> Object:

DTO_FIELD(Fields<MyObject::ObjectWrapper>::ObjectWrapper, colors);

Custom Mapping-Enabled Types

Please note that one can define a custom type to be used in custom ObjectMapper.
This section is not documented yet. For information about custom object mapping contact us in dev-chat


ObjectWrapper is a special structure that holds data-type information. In fact all mapping-enabled types in oatpp including String, Int32, Int64, Float32, Float64, Boolean are ObjectWrappers over primitive types and can hold nullptr value.

See ObjectWrapper.


Serialize / Deserialize

Define DTO

#include "oatpp/core/data/mapping/type/Object.hpp"
#include "oatpp/core/macro/codegen.hpp"

#include OATPP_CODEGEN_BEGIN(DTO) ///< Begin DTO codegen section

class User : public oatpp::data::mapping::type::Object {

  DTO_INIT(User, Object /* extends */)

  DTO_FIELD(String, name, "First-Name");
  DTO_FIELD(String, surname, "Family-Name");
  DTO_FIELD(Int32, age);
  DTO_FIELD(Fields<List<User::ObjectWrapper>::ObjectWrapper>::ObjectWrapper, familyMembers); ///< Map<String, List<User>>
  DTO_FIELD(Fields<String>::ObjectWrapper, additionalNotes); ///< Map<String, String>


#include OATPP_CODEGEN_END(DTO) ///< End DTO codegen section

Create object and set fields

/* create user */
auto user = User::createShared();
user->name = "Ivan";
user->surname = "Ovsyanochka";
user->age = 24;
user->familyMembers = user->familyMembers->createShared();
user->additionalNotes = user->additionalNotes->createShared();

/* create user */
auto brother = User::createShared();
brother->name = "Yuriy";
brother->surname = "Ovsyanochka";
brother->age = 30;

/* create user */
auto sister = User::createShared();
sister->name = "Kate";
sister->surname = "Ovsyanochka";
sister->age = 20;

/* create list of siblings */
auto siblings = oatpp::data::mapping::type::List<User::ObjectWrapper>::createShared();

user->familyMembers->put("siblings", siblings);
user->additionalNotes->put("Education", "Master of Computer Science");

Create JSON object mapper

#include "oatpp/parser/json/mapping/ObjectMapper.hpp"


/* create json ObjectMapper with default configs */
auto jsonObjectMapper = oatpp::parser::json::mapping::ObjectMapper::createShared();

Serialize user to json

oatpp::String json = jsonObjectMapper->writeToString(user); 
OATPP_LOGD("json", "value='%s'", json->c_str()); ///< print json


  "First-Name": "Ivan",
  "Family-Name": "Ovsyanochka",
  "age": 24,
  "familyMembers": {
    "siblings": [
        "First-Name": "Yuriy",
        "Family-Name": "Ovsyanochka",
        "age": 30,
        "familyMembers": null,
        "additionalNotes": null
        "First-Name": "Kate",
        "Family-Name": "Ovsyanochka",
        "age": 20,
        "familyMembers": null,
        "additionalNotes": null
  "additionalNotes": {
    "Education": "Master of Computer Science"

Please note: example of above output is beautified with oatpp::parser::json::Beautifier.

Deserizalize from String

auto cloneOfUser = jsonObjectMapper->readFromString<User>(json);

Use JSON Beautifier

Without the use of beautifier the json serializer output will contain no spaces nor newline character:

{"First-Name":"Ivan","Family-Name":"Ovsyanochka","age":24 ...

In order to beautify json output set useBeautifier = true in serializer config:

/* create serializer config */
auto config = oatpp::parser::json::mapping::Serializer::Config::createShared();

/* enable beautifier */
config->useBeautifier = true;

/* create json object mapper with serializer config */
auto jsonObjectMapper = oatpp::parser::json::mapping::ObjectMapper::createShared(config);

More about json object mapper configuration see:

Examples of code