Records and their representation

A record is one representation of a customer, product, supplier, or other subject. In Trazadera Golden, you work with its fields, its identity, and the information Golden attaches to it as it is processed.

Aurelia Utilities keeps customer information in a CRM and a billing system. Both can describe the same person. They may use different identifiers, contain different details, and disagree. Golden must first represent those records before it can validate them, find them, or help decide whether they describe the same customer.

Read a record

Here is a shortened record using Ana’s values from the Aurelia CRM sample. Fields unrelated to this explanation and processing metadata are omitted. This is an illustration of the record itself, not a complete API response.

{
  "_id": "CRM-0001",
  "fullName": "Ana García Muñoz",
  "taxId": "12345678Z",
  "email": "ana.garcia@example.com",
  "phone": "611000000",
  "contractDate": "2024-01-01"
}

Each name on the left identifies a field; the value on the right is what this record says about that field. fullName is the field and Ana García Muñoz is its value. Field names connect the data with its definition and with operations such as searching or validation.

_id identifies the record in Golden. Aurelia’s CRM file supplies CRM-0001 in its _id column. The customer dataset uses a SCRIPT identity with input['_id'] to retain that identifier during loading. Other datasets can derive identity from designated business columns or a different script. See Dataset identity.

Record identity and customer identity answer different questions. CRM-0001 and CRM-DUP-0001 are different records. They can nevertheless describe the same person. A matching tax identifier is evidence for deciding that; it does not make the two record identifiers interchangeable.

Stable record identity also matters on a repeated load. Golden needs to recognize which existing record a new representation should update. Changing the identity can create another record instead of updating the intended one.

The dataset explains the fields

The JSON shows values. A dataset supplies their definition: field names, meaning, structure, identity rules, and validation settings.

Three separate choices describe a field:

Golden calls the meaning of a simple value its token. A token tells Golden how the value should be interpreted for the configured processing. A quoted JSON string can represent a date, a phone number, or ordinary text; quotes alone do not tell you which one it is.

For example, "2024-01-01" represents a date in Ana’s dataset, while "611000000" represents a phone number. Treating the phone as a quantity would lose its meaning: you do not add two customer phone numbers together, and formatting can be significant. The dataset declares a DATE token for the first and a PHONE token for the second.

Validation and formatting settings complete that definition. Choosing a token and choosing what to do with an invalid value are separate decisions.

A field can contain several values

Suppose Aurelia needs to retain two contact emails. The following examples are teaching extensions, not fields added by the installed Aurelia sample. They show the structures a suitable dataset would describe.

{
  "emails": [
    "ana.garcia@example.com",
    "ana.personal@example.net"
  ]
}

The brackets hold multiple values of the same field. This is one record with two emails, not two customer records. The field definition combines a simple EMAIL token with array: true.

Joining both addresses with a semicolon inside one JSON string does not express the same structure as the array above.

Multiplicity does not establish which email is preferred. If the business needs a primary contact, that meaning must be represented explicitly rather than inferred from the position of an item.

Nested data uses a list of records

An address groups related parts such as street, city, and postcode. Golden represents nested DATASET columns as arrays of records. Even when you have only one address, place it inside a list:

{
  "addresses": [
    {
      "street": "Calle Mayor 12",
      "city": "Madrid",
      "postcode": "28013"
    }
  ]
}

A nested dataset defines these address fields. The parent column declares type: "DATASET", references the nested definition through dataset, and sets array: true. Golden rejects a DATASET column with array: false; an ordinary JSON object such as "address": {"city": "Madrid"} is not a supported single-value dataset column.

If you need only one fixed address, you can instead use flat fields. The supplied Aurelia customer dataset does this with street, city, postcode, and province. The nested examples here are teaching extensions.

Keeping the postcode as text preserves leading zeros. Its semantic token can describe a postcode without making the value an arithmetic quantity.

Nesting represents containment. A lookup reference is different: Aurelia’s province field refers to a value in a separate catalog table. It does not embed the whole province record inside each customer.

Multiple values can themselves be objects

The same structure can hold more than one address:

{
  "addresses": [
    {
      "kind": "HOME",
      "street": "Calle Mayor 12",
      "city": "Madrid",
      "postcode": "28013"
    },
    {
      "kind": "BILLING",
      "street": "Calle Fuencarral 45",
      "city": "Madrid",
      "postcode": "28004"
    }
  ]
}

The parent field is now a DATASET column with array: true. Each element follows the same nested address definition. kind is a business field in this teaching example; it makes the purpose of each address explicit.

The grouping matters. Separate arrays of streets and postcodes would leave you to infer which street belongs with which postcode. Objects retain that relationship. A validation finding can then identify the postcode in a particular address rather than just say that the customer has a bad postcode.

The supported column shapes are:

These illustrations show shape, not complete field definitions. The dataset must also define the tokens or nested dataset and the applicable rules.

Missing information is part of the model

A record can omit a field, contain null, contain an empty string, or have an empty array. Those JSON representations are different. Whether a particular input is acceptable and how it is stored depend on the dataset and processing rules.

For example, an email being optional is different from an invalid email being accepted. A missing value and "ana.garcia@" are different conditions, even if both prevent you from contacting the customer. Validation identifies the condition; error policy determines the configured treatment.

Place the record in Golden

A golden record is a mastered result of resolving records believed to describe the same subject. It still has fields and an identity. To understand where its information came from and what happened to it, you also need the metadata that accompanies it.

Records that might describe the same subject can be brought together for comparison. Read Comparison, candidates, and groups and Resolve duplicates for group classifications and decisions. Search and duplicate resolution depend on the entity configuration; a table of records does not by itself imply a mastering workflow.

Check your understanding

Before continuing, you should be able to explain why:

• two customer records can have different _id values and still describe Ana;
• two emails in one array do not constitute two customer records;
• a list of address objects preserves relationships that separate field lists do not; and
• a dataset describes records, while a table contains them.

Continue with Metadata: information about a record to read the parts of a record that describe its origin, processing, and query context.