Skip to main content
GET
Get a derivation rule

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

Response

OK

id
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

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.

Example:
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.

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.