Working with object references

An ObjRef points to one object in a workspace: a display form, a measure, a dataset, a dashboard. Every filter, attribute, measure, and widget the SDK hands you carries one. This page lists the helpers for comparing, keying, narrowing, and printing references.

Reference kinds

ObjRef is IdentifierRef | UriRef. ObjRefInScope adds LocalIdRef.

Compare two references

Use areObjRefsEqual. Do not compare identifier fields yourself.

import { areObjRefsEqual, attributeDisplayFormRef, filterObjRef, type IFilter } from "@gooddata/sdk-model";
import * as Md from "./catalog.js";

const regionDisplayForm = attributeDisplayFormRef(Md.Region.Default);

function findRegionFilter(filters: IFilter[]): IFilter | undefined {
    return filters.find((filter) => areObjRefsEqual(filterObjRef(filter), regionDisplayForm));
}

Equality rules:

• Two identifier references are equal when their identifiers match. type is compared only when both carry one.
• An identifier reference never equals a URI reference, even when both point to the same object.
• Two null or undefined values are equal. One null and one reference are not.

Use a reference as a key

serializeObjRef returns a stable string that keeps the kind and the type. deserializeObjRef turns it back into a reference.

import { deserializeObjRef, idRef, measureItem, serializeObjRef, type IMeasure, type ObjRef } from "@gooddata/sdk-model";

const titles = new Map<string, string>();

function rememberTitle(ref: ObjRef, title: string): void {
    titles.set(serializeObjRef(ref), title);
}

function titleOf(measure: IMeasure): string | undefined {
    const ref = measureItem(measure);
    return ref ? titles.get(serializeObjRef(ref)) : undefined;
}

// Round trip
const restored = deserializeObjRef(serializeObjRef(idRef("f_owner.region_id", "displayForm")));

Keys are strict: idRef("x") and idRef("x", "displayForm") produce different keys. When you build references to key by, pass the same type argument every time, or key by the reference the SDK gave you.

Narrow before reading a field

Use the type guards. A cast such as ref as IdentifierRef compiles, but when a URI reference reaches it, ref.identifier is undefined, and the bug shows up later as a missing key.

import { isIdentifierRef, type ObjRef } from "@gooddata/sdk-model";

function identifierOf(ref: ObjRef): string | undefined {
    return isIdentifierRef(ref) ? ref.identifier : undefined;
}

isUriRef and isLocalIdRef work the same way.

Print a reference

objRefToString returns the bare identifier, URI, or local identifier. Use it for logs, debugging, and test output.

Helper summary