Traits: API for elements traits

What are Traits?

Traits are a new feature that allows to associate metadata to objects within a workspace via a REST API, they are open-ended metadata for workspace objects. For example, if you upload assets (images, documents, etc.) that belong to a specific project, you can add that project information as Traits to each asset in the workspace. Later, you could download those assets and the data in the Traits of each asset will let you know the original project data.

Highlights of Traits

Important points regarding Traits:

  • Traits are always represented as a JSON array.
  • Unlike Bluescape comments, traits can be specified on object creation.
  • Any number of traits can be associated with a workspace object, forming an ordered list.
  • Similarly to Bluescape comments, traits are append-only, i.e., traits can only grow monotonically over time, they cannot be deleted.

To what elements can I associate a Trait?

Traits may be associated with the following workspace elements (object_type):

  • Notes
  • Canvas
  • Browsers
  • Documents
  • Images
  • Strokes
  • Text

Traits may be associated with a workspace element upon its creation, or at a later time, until the deletion of the element. The following element types currently support trait association upon element creation:

  • Notes
  • Canvas
  • Browsers
  • Strokes
  • Text

Trait structure

In every request and response of the Bluescape REST API operating on elements of the supported types, traits are represented as a JSON array. Each item in the array must conform to the JSON-LD specification ( While the JSON-LD specification contains a rich set of features for data modeling, their use not necessary. The only relevant constraint imposed by the JSON-LD specification is that every JSON property name must either:

  • be a Uniform Resource Locator (URI)
  • be a JSON-LD keyword - one of 13 reserved names starting with the "@" symbol
  • resolve to a URI, as directed by the "@context" keyword

IMPORTANT: If traits do not conform to this structure, traits API calls will produce HTTP error response 400 Bad Request.

API clients are encouraged to choose the HTTP URI schema to reduce the possibility of inadvertent namespace collisions, and use a base URI derived from the DNS name of their organization, thus enabling multiple organizations to cooperatively share the traits namespace. For instance, the traits specified above can be augmented by another organization. See example below:

Example of the data load:

        // trait from framework A
        "":  “background-test-1.jpg”,
        "": "1.0.4-First-review"
    { // trait from framework B
        "": {
            "": "Joe Smith",
            "": "2019Q4"
        "": "Lorem Ipsum, the Return"

How to implement Traits?

Add Traits when creating an element

As mentioned above, you can add Traits to an element at the creation moment if the element is one of the following ones:

  • Notes
  • Canvas
  • Browsers
  • Strokes
  • Text

You will need to add the JSON Array as a 'traits' field in the data load. For example, when craeting a Canvas, you can add Traits as in the example below:

data_load = {
    'x': 10000,
    'y': 1000,
    'width': 4000,
    'height': 4000,
    'name': "New Canvas - Creation time: " + str(timestamp),
    'borderColor': 'Yellow',
    'traits' : [{"": "Lorem Ipsum, The Return"},{"" : "First Review, gathering Feedback"}]

Add Traits to an existing element

Endpoint /v2/workspaces/<workspace_uid>/elements/<object_type>/<object_id>/traits
Method POST
Comments If traits do not conform to the specified structure, Traits API calls will produce HTTP error response 400 Bad Request.

When adding Traits to an object, you will need to provide a JSON Array as the data load for the API. An example of the data load for adding Traits to an image object would be:
data_load = [{
    "": "Sand dunes picture",
    "": "Sand Dunes, big, light on one side, shadow on the other side",
    "": ["sand dunes","light","desert","blue sky","yellow sand","sand"]

Get a list of the Traits in an object

Endpoint /v2/workspaces/<workspace_uid>/elements/<object_type>/<object_id>/traits
Method GET

Cannot Delete/Edit Traits: alternative

As previously mentioned, the traits of an element are never deleted during its lifetime, and all the traits association is cumulative. However, the API client is free to interpret cumulative traits associations as updates or deletions. For instance, another traits association may result in the traits array becoming this:

[{ "": "869C287E-59BB-4319-9261-F791F659C54A" },
    { "": "98d03812452e0b6cabdbde5eff14e89f" },
    { "": null }]

The API client using the "" prefix is free to interpret such association as a deletion of the assetId property of the associated bluescape#assetId element by processing the values from older to newer (top to bottom in this example).

If you have any questions or comments, please contact us at Bluescape support.