Skip to main content
This reference documents all attribute types available in Rosetta Stone, including their properties, validations, and usage examples.

Attribute structure

All attributes share a common structure based on the platform’s type system:
Required properties:
  • id (number): Unique identifier for the attribute
  • name (string): Machine-readable name
  • type (string): One of the supported types
Optional properties:
  • display_name (string): Human-readable name for UI display
  • description (string): Explanation of the attribute’s purpose
  • validations (string[]): Array of validation rules
  • metadata (object): Additional metadata including co-occurrence data
  • hints (object[]): Guidance for anyone mapping data to the attribute. See Hints

Primitive types

Primitive types represent basic data values.

String

Variable-length Unicode text. Can optionally include an enum property to restrict allowed values. Basic definition:
With validations:
With enum (restricted values):
When a string attribute has an enum property, only those values are allowed. Values are case-sensitive.

Long

64-bit signed whole numbers. Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807. Definition:

Double

Double-precision (64-bit) floating-point numbers. Definition:

Boolean

True or false values. Definition:
Mapping from source data:

Timestamptz

Date and time with timezone, stored in UTC. Follows ISO 8601 format. Definition:
Mapping from source data:

Object type

Objects group related fields into a single composite value. Use properties to define the fields and required to specify which fields are mandatory. Definition:
Properties:
  • properties: Object mapping field names to field definitions
  • required: Array of field names that must be present
Nested objects: Objects can contain other objects:
Mapping example:
Accessing object fields in queries:

Array type

Arrays contain multiple values of the same type. Definition:
Properties:
  • items: Definition of the element type
Array of objects:
Mapping examples:
Querying arrays:

Reference type

References link to other attribute definitions using their numeric ID. This enables reuse of standardized definitions. Definition:
Properties:
  • $ref: The numeric ID of the referenced attribute
Behavior:
  • The field inherits the full type definition of the referenced attribute
  • Validations from the referenced attribute apply
  • Changes to the referenced attribute automatically propagate
Use cases:
  • Reusing standardized definitions (like event_timestamp)
  • Ensuring consistency across attributes
  • Building complex schemas from well-defined components

Validation expressions

Validations are NQL expressions that filter out invalid values. Use $this to reference the value being validated. These expressions are injected into compiled NQL queries to enforce data quality.

Numeric validations

Comparison operators check value ranges:

String length validations

Use LENGTH() to validate string length:

Pattern matching

Use LIKE for pattern validation:

Blank strings

Use TRIM() before the comparison to reject a value that is empty or only spaces:

Validations on object properties

A validation can sit on one property of an object attribute. In it, $this is the object, so the expression names the property by its path, $this."full_name". A bare $this also works and means the property’s value.
When a value fails the validation of an optional property, that property is NULL in rosetta_stone and the other properties of the row keep their values. A blank middle_name reads as NULL, and the row’s full_name is still returned.

Examples


Join key attributes

Primitive attributes can be marked as join keys using the is_join_key property:
Join key attributes are optimized for use in JOIN operations across datasets.

Hints

An attribute can carry hints: guidance for anyone mapping data to it, in addition to its description. Each hint has a kind that says what it is about. An attribute has at most 20 hints.

when_to_map

Says when a dataset should be mapped to the attribute. An attribute has at most one when_to_map hint per level.
GET /attributes finds attributes by their hints: hint_kind=when_to_map returns the attributes that carry that kind, and adding hint_level=dataset returns only those to check against a dataset as a whole.

Transformation Functions

Functions for mapping transformations

How Rosetta Stone Works

Understand attributes and mappings

The Normalization Model

Type system and validation concepts

Creating Normalized Attributes

Best practices for designing attributes