Metadata: information about a record

The business fields in a record tell you what it says about a customer. Metadata tells you how to interpret that record: its identity, where it came from, what Golden measured, or why a search returned it.

These are different kinds of evidence. A recent update does not prove the values are correct. A quality score does not prove that two records describe the same person. Knowing the source does not tell you who last changed a value.

Find the metadata in the JSON

This excerpt shows Ana’s record after installing Aurelia Utilities, before any edits or duplicate decisions. Unrelated fields are omitted. The update time varies with the installation.

{
  "_id": "CRM-0001",
  "fullName": "Ana García Muñoz",
  "email": "ana.garcia@example.com",
  "_source": [
    {
      "_src": "sample-source-crm",
      "_src_id": "CRM-0001"
    }
  ],
  "_metadata": {
    "_updated": "2026-10-03T16:03:26.605623154Z",
    "_quality": 93
  },
  "qualityState": "CURRENT"
}

Read the locations as well as the names:

There is no single wrapper containing every kind of metadata. _source is beside _id; _updated is inside _metadata. Search evidence, when supplied, is in a top-level _search object. qualityState is also at the top level, even though its name has no underscore.

Golden reserves underscore-prefixed field names for product purposes; use ordinary dataset field names for business data. Do not decide whether a field is business data from its spelling alone: qualityState is response context, not a customer field you should define or write back.

An API operation can also wrap a record in a response. A single-record response can carry it under record, while search results carry records in result. The fields of that response wrapper are distinct from the fields inside each record. Always identify the record before reading its metadata.

Identity and provenance are different

_id answers which Golden record is this? _source answers which source representations contributed to it?

An entry in _source uses _src for the source and _src_id for its optional reference. The reference can be absent when the source does not provide one. A list allows more than one source representation to be recorded. The same source can contribute different references; its name alone is not a complete identity.

Aurelia’s CRM loader records sample-source-crm as the source and CRM-0001 as its reference. The source name identifies the configured source resource. The supplied sample does not require business fields called sourceSystem or sourceRef: provenance has its own representation.

Source identity is useful when reconciling a result with the CRM or billing system. It is not an audit trail of every change, nor a guarantee that the source’s values are accurate.

Stored information and query context

Some metadata describes recorded processing; other information is added when you request a view of the record.

This distinction explains why the same record can appear with different context in a table read and a search response. The search did not have to change Ana’s email to explain how it found her.

_search can identify the index mapping and normalized value that matched. Its origin helps distinguish a direct match from a record reached through a relationship. A returned record is therefore not necessarily evidence that its own visible fields matched the query directly. Search metadata belongs to the result being interpreted, not to a permanent customer attribute.

Read a measurement together with its state

When present, the score is at _metadata._quality. It is an integer from 0 to 100. The accompanying definition and calculation time describe what was measured and when.

The response’s qualityState is essential to interpretation:

For example, this illustrative excerpt contains an old score:

{
  "_metadata": {
    "_quality": 80
  },
  "qualityState": "STALE"
}

Other measurement fields are omitted from this excerpt. The presence of 80 does not turn the measurement into a current one. In a non-current response, Golden omits the detailed quality findings and their error/warning counts; it can retain the score alongside the state. Missing findings therefore do not mean that there are no problems.

When current findings are returned, they describe individual conditions, with severity and a stable messageKey. schemaPath identifies the field in the definition; recordPath identifies where it occurred in this record. The distinction matters for repeated structures: a definition can describe the postcode in every address, while a finding concerns one particular address.

Read the findings to understand the condition. Read the score to summarize the measurement. The calculation and validation rules are separate topics; neither a high score nor CURRENT proves that the record describes the right person.

Metadata does not replace audit or history

An update timestamp answers when an update was recorded. It does not, by itself, supply the actor, reason, changed fields, or their previous values.

Keep three questions separate:

Ordinary record responses do not include the audit trail. Audit has a separate record-audit operation; requesting an expanded record does not add that trail. A missing _audit member in a record response is therefore not evidence that auditing is disabled.

Audit and history have their own activation, access, and retention conditions. Neither reconstructs information that was never captured. See Audit and history for the controls and separate read operation.

Metadata in write requests

The application supplies business values through the supported write operation. Golden manages processing results such as quality measurements, search evidence, and audit information. Posting a record with _quality: 100 is not a way to make its data valid.

Record identity and declared provenance have dedicated input rules. The fact that an operation accepts _id or _source does not imply that all underscore-prefixed response fields are writable. Construct write requests from the operation’s contract rather than copying an entire read response.

Only rely on documented fields, and allow for fields that are optional or additional. Their absence can reflect the operation, measurement state, or configuration; do not silently convert missing information into a zero score, an empty history, or a successful check.

Check your understanding

You should now be able to locate an update time inside _metadata, distinguish it from top-level provenance, and explain why a search can add evidence without changing the customer fields.

You should also be able to explain why an old score is not a current quality assessment and why a record with no inline audit trail may still be audited.

Use the Record metadata reference to look up field paths and types. Continue with Validation and error policies, Data quality, or Audit and history.