Skip to main content
POST
/
attributes
Create an attribute
curl --request POST \
  --url https://api-dev.narrative.io/attributes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "price",
  "description": "The price of an order, product, or a price component. Currency field accepts ISO 4217 currency codes",
  "display_name": "Price",
  "type": "object",
  "properties": {
    "value": {
      "type": "double",
      "validations": [
        "$this.value >= 0.0"
      ]
    },
    "iso_4217_currency": {
      "type": "string",
      "enum": [
        "USD",
        "GBP",
        "JPY"
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "value",
    "iso_4217_currency"
  ],
  "tags": [
    "ecommerce",
    "pricing"
  ],
  "collaborators": {
    "view": {
      "type": "all"
    },
    "map": {
      "type": "inclusion",
      "companies": [
        12345,
        67890
      ]
    }
  }
}
'
{
  "id": 123456789,
  "name": "price",
  "description": "The price of an order, product, or a price component. Currency field accepts ISO 4217 currency codes",
  "display_name": "Price",
  "type": "object",
  "properties": {
    "value": {
      "type": "double",
      "validations": [
        "$this.value >= 0.0"
      ]
    },
    "iso_4217_currency": {
      "type": "string",
      "enum": [
        "USD",
        "GBP",
        "JPY"
      ]
    }
  },
  "required": [
    "value",
    "iso_4217_currency"
  ],
  "company_id": 12345,
  "collaborators": {
    "view": {
      "type": "inclusion",
      "companies": [
        12345,
        67890
      ]
    },
    "map": {
      "type": "inclusion",
      "companies": [
        12345
      ]
    }
  },
  "tags": [
    "ecommerce",
    "transaction"
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

An short identifier for the attribute to be used when it is referenced in validations.

Attribute names must consist of only alphanumeric characters or underscores and be < 255 characters long.

​
display_name
string
required

A public-facing descriptive name for the attribute.

​
collaborators
object
required

Defines which companies have access to view and map this attribute. Defaults to no companies (owner only).

​
type
enum<string>
required

An array with elements of any data type.

Available options:
array
​
description
string

A description of the type of data the attribute represents, including collection methodology, assumptions, etc.

​
tags
string[]

List of tags to associate with the attribute

​
validations
string[]

A raw Spark SQL expression determining whether a value for the given column is valid or not.

If more than one validation is specified then all the validation must evaluate to true for the column value to be considered valid.

If validations is not specified or empty then all rows will match the access rule.

E.g. for an attribute with the following definition:

{
  "name": "unique_id",
  "type": "object",
  "properties": {
    "identifier_value": {
      "type": "string"
    },
    "identifier_type": {
      "type": "string"
    },
    "timestamp": {
      "type": "timestamptz"
    }
  },
  "required": [
    "value"
  ]
}

Valid validations include:

  • Is the ID type lowercased?
"identifier_type": {
  "type": "string",
  "validations": [
    "lower($this.identifier_type) = $this.identifier_type"
  ]
}
  • Was the row collected within the last 90 days?
"timestamp": {
  "type": "timestamptz",
  "validations": [
    "$this.timestamp > date_sub(current_date(), 90)"
  ]
}

Response

200 - application/json

OK

An owned attribute response includes additional fields for attributes owned by the requesting company.

​
type
enum<string>
required

An array with elements of any data type.

Available options:
array
​
company_id
integer
required

The ID of the company that owns this attribute

​
collaborators
object
required

Defines which companies have access to view and map this attribute

​
id
integer

Unique identifier for the attribute.

​
description
string

A description of the type of data the attribute represents, including collection methodology, assumptions, etc.

​
display_name
string

A public-facing descriptive name for the attribute.

​
name
string

An short identifier for the attribute to be used when it is referenced in validations.

Attribute names must consist of only alphanumeric characters or underscores and be < 255 characters long.

​
tags
string[]

List of tags associated with the attribute

​
validations
string[]

A raw Spark SQL expression determining whether a value for the given column is valid or not.

If more than one validation is specified then all the validation must evaluate to true for the column value to be considered valid.

If validations is not specified or empty then all rows will match the access rule.

E.g. for an attribute with the following definition:

{
  "name": "unique_id",
  "type": "object",
  "properties": {
    "identifier_value": {
      "type": "string"
    },
    "identifier_type": {
      "type": "string"
    },
    "timestamp": {
      "type": "timestamptz"
    }
  },
  "required": [
    "value"
  ]
}

Valid validations include:

  • Is the ID type lowercased?
"identifier_type": {
  "type": "string",
  "validations": [
    "lower($this.identifier_type) = $this.identifier_type"
  ]
}
  • Was the row collected within the last 90 days?
"timestamp": {
  "type": "timestamptz",
  "validations": [
    "$this.timestamp > date_sub(current_date(), 90)"
  ]
}