Update a derivation rule

curl --request PATCH \
  --url https://api-dev.narrative.io/derivations/{derivation_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "raw_email_to_sha256",
  "description": "Hashes the raw email address with SHA-256.",
  "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
}
'

import requests

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

payload = {
    "name": "raw_email_to_sha256",
    "description": "Hashes the raw email address with SHA-256.",
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  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.',
    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
  })
};

fetch('https://api-dev.narrative.io/derivations/{derivation_id}', 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/{derivation_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'raw_email_to_sha256',
    'description' => 'Hashes the raw email address with SHA-256.',
    '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
  ]),
  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/{derivation_id}"

	payload := strings.NewReader("{\n  \"name\": \"raw_email_to_sha256\",\n  \"description\": \"Hashes the raw email address with SHA-256.\",\n  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\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  \"fidelity_note\": \"<string>\",\n  \"cost\": 1,\n  \"active\": true\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api-dev.narrative.io/derivations/{derivation_id}")
  .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  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\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  \"fidelity_note\": \"<string>\",\n  \"cost\": 1,\n  \"active\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Patch.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  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\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  \"fidelity_note\": \"<string>\",\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."
}

PATCH

derivations

{derivation_id}

Update a derivation rule

curl --request PATCH \
  --url https://api-dev.narrative.io/derivations/{derivation_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "raw_email_to_sha256",
  "description": "Hashes the raw email address with SHA-256.",
  "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
}
'

import requests

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

payload = {
    "name": "raw_email_to_sha256",
    "description": "Hashes the raw email address with SHA-256.",
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  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.',
    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
  })
};

fetch('https://api-dev.narrative.io/derivations/{derivation_id}', 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/{derivation_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'raw_email_to_sha256',
    'description' => 'Hashes the raw email address with SHA-256.',
    '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
  ]),
  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/{derivation_id}"

	payload := strings.NewReader("{\n  \"name\": \"raw_email_to_sha256\",\n  \"description\": \"Hashes the raw email address with SHA-256.\",\n  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\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  \"fidelity_note\": \"<string>\",\n  \"cost\": 1,\n  \"active\": true\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api-dev.narrative.io/derivations/{derivation_id}")
  .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  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\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  \"fidelity_note\": \"<string>\",\n  \"cost\": 1,\n  \"active\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Patch.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  \"collaborators\": {\n    \"use\": {\n      \"type\": \"none\"\n    }\n  },\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  \"fidelity_note\": \"<string>\",\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.

Path Parameters

derivation_id

integer<int64>

required

Id of the derivation rule.

Required range: x >= 1

Body

application/json

Body of PATCH /derivations/{id}. Only the fields present in the request change. Setting fidelity_note to null clears it; leaving the key out keeps the current value. The source and target attributes of a rule are immutable — there is no key for them here, and one sent anyway is ignored.

name

string

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

Maximum string length: 256

Example:

"raw_email_to_sha256"

description

string

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."

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" } }

mapping

object

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

imprecise

boolean

fidelity_note

string | null

Maximum string length: 2048

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

Response

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