To create a vAtom, a template and a template variation is needed. Those are blueprints which are used to create vAtoms.
The template provides the structure of the vAtom with defaults, whereas the template variation can overwrite most of the values defined by the template. A template can for example define attributes for a pizza object, the template variation then describes a pizza margarita or a pizza prosciutto.
A template mainly consists of three sections:
This section contains fields that are used to configure the template like its name
or if the template is published.
There is one special case: cloneable
is not used to configure the template, but defines if vAtoms that are based on this template can be cloned. This field cannot be overwritten in the template variation.
The difference to other boolean fields that are part of the vAtom object is that cloneable
is either true
or false
and is not changed by an action. The template variation keeps track of the number of clones and if the maximum is reached. Whereas fields like acquirable
might initially be set to true
, but can be changed for each vAtom individually after an action was executed because after a user acquired a vAtom from a publisher, other users should not be able to acquire that vAtom anymore.
This section contains the structure of a vAtom that will be used to create vAtoms when they are emitted.
The structure of this section is predefined, no fields can be added or removed. The only mandatory field is root_type
, which defines what type of vAtoms will be created.
For fields of type array
(states
and resources
) the allowed list entries can be defined. For example for resources
an entry could look like this:
[
{
"name": "ActivatedImage" ,
"resourceType": "ResourceType::Image::JPEG" ,
"value": {
"resourceValueType": "ResourceValueType::URI",
"value": ""
}
}
]
In this case the template variation is only allowed to contain resources with the name ActivatedImage
and the only field that can be overwritten in the template variation is value
.
This section contains fields that are defined by the publisher. Built in actions will not modify custom fields in this section. When a template variation is created, only fields that are defined in the template are allowed in the template variation.
Fields defined in the ETH section will be recorded on the Ethereum blockchain. Each time a value of a field in the ETH section changes, the value will also be changed in the smart contract. The publisher will be charged in VEEs for those operations (smart contract creation, transactions, etc.).
Templates can be created in draft mode by setting the flag unpublished: true
. Templates can be deleted, while they are not published.
A template can be published by setting unpublished: false
. Once published, a template cannot be deleted anymore.
Content-Type: application/json
App-Id: {app_id}
Name | Type | Description |
---|---|---|
template
*
| string | specifies the Template Name and has to be a unique string beginning with the publisher domain name
publisher_fqdn |
cloneable | boolean | true
or
false
, default:
false
defines if the vAtoms based on this template can be shared with other users by sending them a clone of your vAtom using a Clone Action |
unpublished | boolean | true or false defines if the template can still be changed (unpublished=true) or if it is the final version (unpublished=false) |
public | boolean | false by default, if set to true then the template will be publicly accessible (read only) |
eth | object | Optional section to define custom properties that will be recorded on the Ethereum Blockchain. |
vatom
*
| object | The vAtom object |
Name | Type | Description |
---|---|---|
network
*
| string | The network on which the data is stored (
mainnet
or
testnet
). If the data is stored on
mainnet
, then the transaction costs will be charged in VEE. |
symbol | string | The symbol that is used in the smart contract. If no symbol is provided, the publishers fully qualified domain name is used. |
fields
*
| object | A map of fields that will be stored on the Ethereum Blockchain. The field name is they key and the value contains the datatype and the value. |
Each field has a unique identifier, which is the field name, for example my_field
, with the following values:
Name | Type | Description |
---|---|---|
type
*
| string | The datatype that is used to store the field on the Ethereum blockchain:
bool
,
uint
and
string
are supported. |
value
*
| string | The initial value of the field. |
{
"eth": {
"fields": {
"my_flag": {
"type": "bool",
"value": true
},
"my_number": {
"type": "uint",
"value": 0
},
"my_field": {
"type": "string",
"value": "test"
}
},
"network": "testnet"
}
}
Name | Type | Description |
---|---|---|
vAtom::vAtomType | object | In the
vAtom::vAtomType
section the built in properties are defined |
private | object | In the private section you can define custom properties, states and resources. Built-in action will not modify private |
Name | Type | Description |
---|---|---|
root_type | string | defines the vAtomType and version e.g.
vAtom::vAtomType
. For more
types |
transferable | boolean | true or false defines if the vAtom can be transferred with a Transfer Action |
acquirable | boolean | true or false defines if the vAtom can be acquired with a Acquire Action e.g. Billboard use-case |
redeemable | boolean | true or false defines if a vAtom can be redeemed with a Redeem Action |
title | string | specifies a title or name of the vAtom |
description | string | you can add a text to describe the function of the vAtom |
category | string | you can define a category for the vAtom |
commerce | object | optional if
redeemable
is false. Defines the
pricing
of the vAtom based on a
currency
and
price |
states | array | includes the states defined for the vAtom. At least one State has to be defined, otherwise the default Activated State will automatically be assigned |
resources | array | Defines an array of Resource objects |
visibility | object | Defines who can see the vAtom |
root_type | Description |
---|---|
vAtom::vAtomType | A regular vAtom/object. Most common type |
vAtom::vAtomType::FolderContainerType | A folder that can contain child vAtoms. At emit step, the folder is empty. The publisher needs to pack vatoms before using. To fill the folder - pre- and post- actions can be defined to fill it. e.g.? |
vAtom::vAtomType::PackageContainerType | Same as the folder, it also contains children, but once it is opened it will vanish e.g. like a gift box or a fortune cookie. At emit step, the folder is empty. The publisher needs to pack vatoms before using. To fill the folder - pre- and post- actions can be defined to fill it. |
vAtom::vAtomType::DiscoverContainerType | Dynamically queries the child vAtoms by using a
discover query
. It has the same fields as
vAtom::vAtomType::FolderContainerType
, except for the
query
field that is nested under
vAtom::vAtomType
. |
vAtom::vAtomType::DefinedFolderContainerType | Same as a folder, but it has predefined vAtoms in it when it is created. They will be created based on the child_policy. Rules can be defined that govern the membership. |
Categories can be used by viewers to group vAtoms. The following categories are supported.
Name | Type | Description |
---|---|---|
pricing | object | Pricing object is optional. When not present vAtom can be redeemed with the merchant with out of band pricing terms. |
Pricing can be based on fiat currency like USD
Name | Type | Description |
---|---|---|
pricingType | string | "Fixed" is the only type supported |
value | object | value object |
Name | Type | Description |
---|---|---|
value | object | Value object. |
currency | string | |
price | float | |
valid_from | ISO Date | Date or an * |
valid_through | ISO Date | Date or an * |
vat_included | boolean | true or false |
Name | Type | Description |
---|---|---|
name | string | select between valid values: "Activated" |
on_state_change | object | Not yet implemented |
value | object | currently boolean is supported via
{"type": "boolean", "value": "true"} |
Resources are used by faces to display a vAtom. The resources are the building blocks for faces to put together a representation of a vAtom for a specific kind of device.
For example multiple ResourceType::Image::JPEG
resources can be used to create a faces that shows the vAtom on a website.
Supported resource types:
Name | Type | Description |
---|---|---|
type | string | |
value | string | Finer grained control for the selected visibility type. Currently only
*
is supported, which means no further restrictions. |
Currently supported visibility types:
owner
the vAtom can only be discovered by the current ownerpublic
the vAtom is visible to all userscontainer
If the vAtom is part of a folder, then it inherits the visibility of the folder{
"template": "publisher_fqdn::Template_Name::v1",
"public": false,
"cloneable": false,
"unpublished": true,
"vatom": {
"vAtom::vAtomType": {
"root_type": "vAtom::vAtomType",
"redeemable": true,
"states": [
{
"name": "Activated",
"value": {
"type": "boolean",
"value": "true"
}
}
],
"resources": [
{
"name": "ActivatedImage",
"resourceType": "ResourceType::Image::JPEG",
"value": {
"resourceValueType": "ResourceValueType::URI",
"value": ""
}
},
{
"name": "CardImage",
"resourceType": "ResourceType::Image::JPEG",
"value": {
"resourceValueType": "ResourceValueType::URI",
"value": ""
}
}
]
},
"private": {}
}
}
Error | Type | Description |
---|---|---|
200 | http | Everything is OK |
400 | http | Invalid data |
403 | http | Not Authorized |
{
"payload": {
"success_message": "created Template successfully",
}
}