Create a derivation rule

curl --request POST \
  --url https://api-dev.narrative.io/derivations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "raw_email_to_sha256",
  "description": "Hashes the raw email address with SHA-256.",
  "source_attribute_id": 123,
  "target_attribute_id": 123,
  "company_id": 123,
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "expression": "<string>",
        "path": "<string>"
      }
    ]
  },
  "lossy": true,
  "imprecise": true,
  "collaborators": {
    "use": {
      "type": "none"
    }
  },
  "fidelity_note": "Hashing is one-way, so the original address cannot be recovered.",
  "cost": 1,
  "active": true
}
'

import requests

url = "https://api-dev.narrative.io/derivations"

payload = {
    "name": "raw_email_to_sha256",
    "description": "Hashes the raw email address with SHA-256.",
    "source_attribute_id": 123,
    "target_attribute_id": 123,
    "company_id": 123,
    "mapping": {
        "type": "object_mapping",
        "property_mappings": [
            {
                "expression": "<string>",
                "path": "<string>"
            }
        ]
    },
    "lossy": True,
    "imprecise": True,
    "collaborators": { "use": { "type": "none" } },
    "fidelity_note": "Hashing is one-way, so the original address cannot be recovered.",
    "cost": 1,
    "active": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'raw_email_to_sha256',
    description: 'Hashes the raw email address with SHA-256.',
    source_attribute_id: 123,
    target_attribute_id: 123,
    company_id: 123,
    mapping: {
      type: 'object_mapping',
      property_mappings: [{expression: '<string>', path: '<string>'}]
    },
    lossy: true,
    imprecise: true,
    collaborators: {use: {type: 'none'}},
    fidelity_note: 'Hashing is one-way, so the original address cannot be recovered.',
    cost: 1,
    active: true
  })
};

fetch('https://api-dev.narrative.io/derivations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-dev.narrative.io/derivations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'raw_email_to_sha256',
    'description' => 'Hashes the raw email address with SHA-256.',
    'source_attribute_id' => 123,
    'target_attribute_id' => 123,
    'company_id' => 123,
    'mapping' => [
        'type' => 'object_mapping',
        'property_mappings' => [
                [
                                'expression' => '<string>',
                                'path' => '<string>'
                ]
        ]
    ],
    'lossy' => true,
    'imprecise' => true,
    'collaborators' => [
        'use' => [
                'type' => 'none'
        ]
    ],
    'fidelity_note' => 'Hashing is one-way, so the original address cannot be recovered.',
    'cost' => 1,
    'active' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-dev.narrative.io/derivations"

	payload := strings.NewReader("{\n  \"name\": \"raw_email_to_sha256\",\n  \"description\": \"Hashes the raw email address with SHA-256.\",\n  \"source_attribute_id\": 123,\n  \"target_attribute_id\": 123,\n  \"company_id\": 123,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"expression\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ]\n  },\n  \"lossy\": true,\n  \"imprecise\": true,\n  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\n  \"fidelity_note\": \"Hashing is one-way, so the original address cannot be recovered.\",\n  \"cost\": 1,\n  \"active\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-dev.narrative.io/derivations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"raw_email_to_sha256\",\n  \"description\": \"Hashes the raw email address with SHA-256.\",\n  \"source_attribute_id\": 123,\n  \"target_attribute_id\": 123,\n  \"company_id\": 123,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"expression\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ]\n  },\n  \"lossy\": true,\n  \"imprecise\": true,\n  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\n  \"fidelity_note\": \"Hashing is one-way, so the original address cannot be recovered.\",\n  \"cost\": 1,\n  \"active\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/derivations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"raw_email_to_sha256\",\n  \"description\": \"Hashes the raw email address with SHA-256.\",\n  \"source_attribute_id\": 123,\n  \"target_attribute_id\": 123,\n  \"company_id\": 123,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"expression\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ]\n  },\n  \"lossy\": true,\n  \"imprecise\": true,\n  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\n  \"fidelity_note\": \"Hashing is one-way, so the original address cannot be recovered.\",\n  \"cost\": 1,\n  \"active\": true\n}"

response = http.request(request)
puts response.read_body

{
  "id": 42,
  "name": "raw_email_to_sha256",
  "description": "Hashes the raw email address with SHA-256.",
  "source_attribute_id": 123,
  "target_attribute_id": 123,
  "company_id": 123,
  "collaborators": {
    "use": {
      "type": "none"
    }
  },
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "expression": "<string>",
        "path": "<string>"
      }
    ]
  },
  "lossy": true,
  "imprecise": true,
  "fidelity_note": "<string>",
  "cost": 1,
  "active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": 123,
  "updated_at": "2023-11-07T05:31:56Z",
  "updated_by": 123,
  "warnings": [
    {
      "type": "cyclic_derivation",
      "cycle": [
        123
      ]
    }
  ]
}

{
  "error": "Unauthorized",
  "error_description": "You are not authorized to use this endpoint."
}

Derivations

Create a derivation rule

Create a new derivation rule. Requires an admin grant on attribute_derivations, and the rule is owned by your own company. A user token whose user is a Narrative global admin is accepted without the grant; an app token always needs it.

The rule’s transformation is validated before the rule can exist: the source and target attributes must exist and be viewable — and the target must additionally grant your company map, since the rule produces values for it — every expression must parse and type-check against the source attribute’s shape, the result must match the target attribute’s declared type, every function must resolve. Each failure returns a 400 with a descriptive message.

A rule that closes a cycle in the derivation graph is created anyway; the cycle comes back as a warning on the response.

POST

derivations

Create a derivation rule

curl --request POST \
  --url https://api-dev.narrative.io/derivations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "raw_email_to_sha256",
  "description": "Hashes the raw email address with SHA-256.",
  "source_attribute_id": 123,
  "target_attribute_id": 123,
  "company_id": 123,
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "expression": "<string>",
        "path": "<string>"
      }
    ]
  },
  "lossy": true,
  "imprecise": true,
  "collaborators": {
    "use": {
      "type": "none"
    }
  },
  "fidelity_note": "Hashing is one-way, so the original address cannot be recovered.",
  "cost": 1,
  "active": true
}
'

import requests

url = "https://api-dev.narrative.io/derivations"

payload = {
    "name": "raw_email_to_sha256",
    "description": "Hashes the raw email address with SHA-256.",
    "source_attribute_id": 123,
    "target_attribute_id": 123,
    "company_id": 123,
    "mapping": {
        "type": "object_mapping",
        "property_mappings": [
            {
                "expression": "<string>",
                "path": "<string>"
            }
        ]
    },
    "lossy": True,
    "imprecise": True,
    "collaborators": { "use": { "type": "none" } },
    "fidelity_note": "Hashing is one-way, so the original address cannot be recovered.",
    "cost": 1,
    "active": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'raw_email_to_sha256',
    description: 'Hashes the raw email address with SHA-256.',
    source_attribute_id: 123,
    target_attribute_id: 123,
    company_id: 123,
    mapping: {
      type: 'object_mapping',
      property_mappings: [{expression: '<string>', path: '<string>'}]
    },
    lossy: true,
    imprecise: true,
    collaborators: {use: {type: 'none'}},
    fidelity_note: 'Hashing is one-way, so the original address cannot be recovered.',
    cost: 1,
    active: true
  })
};

fetch('https://api-dev.narrative.io/derivations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-dev.narrative.io/derivations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'raw_email_to_sha256',
    'description' => 'Hashes the raw email address with SHA-256.',
    'source_attribute_id' => 123,
    'target_attribute_id' => 123,
    'company_id' => 123,
    'mapping' => [
        'type' => 'object_mapping',
        'property_mappings' => [
                [
                                'expression' => '<string>',
                                'path' => '<string>'
                ]
        ]
    ],
    'lossy' => true,
    'imprecise' => true,
    'collaborators' => [
        'use' => [
                'type' => 'none'
        ]
    ],
    'fidelity_note' => 'Hashing is one-way, so the original address cannot be recovered.',
    'cost' => 1,
    'active' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-dev.narrative.io/derivations"

	payload := strings.NewReader("{\n  \"name\": \"raw_email_to_sha256\",\n  \"description\": \"Hashes the raw email address with SHA-256.\",\n  \"source_attribute_id\": 123,\n  \"target_attribute_id\": 123,\n  \"company_id\": 123,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"expression\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ]\n  },\n  \"lossy\": true,\n  \"imprecise\": true,\n  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\n  \"fidelity_note\": \"Hashing is one-way, so the original address cannot be recovered.\",\n  \"cost\": 1,\n  \"active\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-dev.narrative.io/derivations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"raw_email_to_sha256\",\n  \"description\": \"Hashes the raw email address with SHA-256.\",\n  \"source_attribute_id\": 123,\n  \"target_attribute_id\": 123,\n  \"company_id\": 123,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"expression\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ]\n  },\n  \"lossy\": true,\n  \"imprecise\": true,\n  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\n  \"fidelity_note\": \"Hashing is one-way, so the original address cannot be recovered.\",\n  \"cost\": 1,\n  \"active\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/derivations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"raw_email_to_sha256\",\n  \"description\": \"Hashes the raw email address with SHA-256.\",\n  \"source_attribute_id\": 123,\n  \"target_attribute_id\": 123,\n  \"company_id\": 123,\n  \"mapping\": {\n    \"type\": \"object_mapping\",\n    \"property_mappings\": [\n      {\n        \"expression\": \"<string>\",\n        \"path\": \"<string>\"\n      }\n    ]\n  },\n  \"lossy\": true,\n  \"imprecise\": true,\n  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\n  \"fidelity_note\": \"Hashing is one-way, so the original address cannot be recovered.\",\n  \"cost\": 1,\n  \"active\": true\n}"

response = http.request(request)
puts response.read_body

{
  "id": 42,
  "name": "raw_email_to_sha256",
  "description": "Hashes the raw email address with SHA-256.",
  "source_attribute_id": 123,
  "target_attribute_id": 123,
  "company_id": 123,
  "collaborators": {
    "use": {
      "type": "none"
    }
  },
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "expression": "<string>",
        "path": "<string>"
      }
    ]
  },
  "lossy": true,
  "imprecise": true,
  "fidelity_note": "<string>",
  "cost": 1,
  "active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": 123,
  "updated_at": "2023-11-07T05:31:56Z",
  "updated_by": 123,
  "warnings": [
    {
      "type": "cyclic_derivation",
      "cycle": [
        123
      ]
    }
  ]
}

{
  "error": "Unauthorized",
  "error_description": "You are not authorized to use this endpoint."
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Body of POST /derivations.

name

string

required

Name of the derivation rule, unique within the owning company.

Maximum string length: 256

Example:

"raw_email_to_sha256"

description

string

required

What the rule does, for whoever is deciding whether to accept derived data.

Maximum string length: 2048

Example:

"Hashes the raw email address with SHA-256."

source_attribute_id

integer<int64>

required

The attribute the rule reads from through $source.

target_attribute_id

integer<int64>

required

The attribute whose value the rule produces. Must differ from source_attribute_id.

company_id

integer<int64>

required

The company that owns the rule. Must be the caller's company.

mapping

object

required

The transformation that produces the target attribute's value from the source attribute's value. Expressions reference the source attribute's shape through $source — for a rule from raw_email to sha256_hashed_email, the value property maps to SHA2(NORMALIZE_EMAIL($source.value), 256).

The shape mirrors mapping expressions, except cached_mapping is not allowed: a cached mapping reads values out of a stored dataset, so there would be nothing to substitute a $source reference into.

Expressions may use the current date or time (CURRENT_DATE, CURRENT_TIMESTAMP, …): the expression runs when a query resolves the rule, so a rule like birthdate → age in years is correct as of each query that uses it. Enum constraints and validation expressions on the target attribute do not restrict the transformation, exactly as they do not restrict a dataset mapping.

Option 1
Option 2

Show child attributes

lossy

boolean

required

The transformation loses information, e.g. hashing.

imprecise

boolean

required

The transformation is approximate, e.g. bucketing an age into a range.

collaborators

object

Which companies, besides the one that owns the rule, may have the rule applied to their data. A rule grants a single thing, so there is one use dimension. Only Narrative can share a rule broadly — with all companies or with everyone outside an exclusion set.

Show child attributes

Example:

{ "use": { "type": "none" } }

fidelity_note

string

Explains the lossy and imprecise flags to whoever is deciding whether to accept derived data.

Maximum string length: 2048

Example:

"Hashing is one-way, so the original address cannot be recovered."

cost

integer

default:1

Breaks ties when more than one rule reaches the same target attribute — cheapest first. Resolution over multi-step paths sums the cost of every rule on a path and prefers the cheapest total.

Required range: x >= 1

active

boolean

default:true

Inactive rules are never applied.

Response

Created

integer<int64>

required

Unique identifier of the derivation rule.

Example:

42

name

string

required

Name of the derivation rule, unique within the owning company.

Maximum string length: 256

Example:

"raw_email_to_sha256"

description

string

required

What the rule does, for whoever is deciding whether to accept derived data.

Maximum string length: 2048

Example:

"Hashes the raw email address with SHA-256."

source_attribute_id

integer<int64>

required

target_attribute_id

integer<int64>

required

company_id

integer<int64>

required

collaborators

object

required

Show child attributes

Example:

{ "use": { "type": "none" } }

mapping

object

required

Option 1
Option 2

Show child attributes

lossy

boolean

required

imprecise

boolean

required

fidelity_note

string | null

required

Explains the lossy and imprecise flags to whoever is deciding whether to accept derived data. null when the rule has no note.

Maximum string length: 2048

cost

integer

default:1

required

Breaks ties when more than one rule reaches the same target attribute — cheapest first. Resolution over multi-step paths sums the cost of every rule on a path and prefers the cheapest total.

Required range: x >= 1

active

boolean

required

created_at

string<date-time>

required

created_by

integer<int64>

required

Id of the user who created the rule.

updated_at

string<date-time>

required

updated_by

integer<int64>

required

Id of the user who last updated the rule.

warnings

object[]

required

Populated on create and update responses; empty on reads.

Show child attributes