Public/Private Meta

In PrivMX, you create apps using Containers. Containers are a collection of versatile building blocks that can be used to implement anything from a basic chat to an encrypted file storage. Containers can contain items; for instance, in the Threads Container, these items are messages. Both Containers and items have two common fields publicMeta and privateMeta:

Defining Structure

Both private and public meta is sent as a binary array. This makes the fields very versatile, both in terms of the format they use and the structure they contain.

Container's architecture does not require you to use a specific data structure inside the public and private meta. So before working with a Container, define what kind of info you will need in your application.

Let's say you want to assign name to your Container. You may decide to put the name in publicMeta if it doesn't contain sensitive data, or you will need to download or query it on the server. In case the name contains sensitive user data, a better choice is to place it in privateMeta, so that it will be encrypted before sending.

This will greatly increase the security of your application at the cost of your application server not having access to this data.

Serializing Data

The easiest and most common format for serialization is JSON. All modern languages have a way to serialize key-value data structures to a JSON string and from string to a binary array.

Following the previous example we can define simple structure with name property.

std::string publicMeta = "{\"name\": \"NAME_OF_YOUR_CONTAINER\"}";

Serialize it to binary array:

std::string publicMeta = "{\"name\": \"NAME_OF_YOUR_CONTAINER\"}";
core::Buffer serialized = core::Buffer::form(publicMeta);

You can now pass it while creating your Container, e.g., Thread:

std::string publicMeta = "{\"name\": \"NAME_OF_YOUR_CONTAINER\"}";
core::Buffer serialized = core::Buffer::form(publicMeta);
threadApi.createThread(
    CONTEXT_ID,
    {THREAD_MEMBERS},
    {THREAD_MANAGERS},
    serialized,
    core::Buffer() // this thread doesn't have privateMeta so we pass empty core::Buffer
)

Remember that it is only an example and you should always consider your app's requirements and limitations.

Querying by Public Meta

To query publicMeta, the data uploaded to the server must be serialized as JSON so that the server can read it. Next you can use list functions and PagingQuery to query by fields from publicMeta.

core::PagingQuery query = core::PagingQuery{
    .skip=0,
    .limit=100,
    .sortOrder="desc",
    .queryAsJson="{\"name\":\"NAME_OF_YOUR_CONTAINER\"}"
};
auto listThreads = threadApi->listThreads(
    CONTEXT_ID,
    query
);

Good Practices

We recommend future-proofing your meta right from the start.

Using Easily Modifiable Format

While it's possible to pass plain text or a number (encoded to a binary array), it's advised to use something like JSON or other key-value format. In case of changes in app requirements, it is easier to add or remove a field than change an entire type of field.

// rest of container fields
publicMeta:"published"

// rest of container fields
publicMeta:{
    status:"published"
}

Adding Schema Version

This simplifies adding support for backwards compatibility. Versions can have different fields or may introduce changes in field types.

// rest of container fields
publicMeta:{
    _ver: 2
    status:"published"
}