Attribute Values

Attributes are how OneEntry describes content: a page, product, block, user, order or form field carries a map of attribute values keyed by marker. The SDK normalizes every attribute of every response to the same shape, so the same field looks the same no matter which module returned it.

const page = await Pages.getPageByUrl('catalog');

page.attributeValues.title.value;   // "Catalog"        — string
page.attributeValues.amount.value;  // 5                — number
page.attributeValues.cover.value;   // { downloadLink } — the file object itself
page.attributeValues.notes.value;   // null             — no value set

The normalized shape

An attribute value is an IAttributeValue: { type, value, position?, additionalFields? }. What value holds depends on type:

Attribute type	value
string, text	string
integer, float, real	number — cast from the API's string form
image, file with one file	the file object itself
image, file with several files	an array of file objects
groupOfImages	always an array — it is a collection by definition
list	an array
timeInterval	an array of groups — see Time Intervals
no value set	always null

Single-file attributes are unwrapped

When an image or file attribute holds exactly one file, its value is the file object itself. Only values with two or more files stay an array.

const block = await Blocks.getBlockByMarker('promo');

// before: block.attributeValues.img.value[0].downloadLink
// now:    block.attributeValues.img.value.downloadLink

This applies in every module. Previously the unwrapping ran only in products, menus, forms, forms-data, attribute-sets, integration-collections and Pages.searchPage, and only on the attributeValues key — everywhere else (blocks, all other pages methods, Products.getProductsEmptyPage, Products.getProductBlockById, admins, discounts, templates, orders, users) the same attribute arrived as a one-element array, so consumers had to branch on the shape. Form attributes, form-data fields and nested additionalFields were never unwrapped at all.

⚠️ Migration: code that reads value[0] from products or menus is unaffected — those modules already returned the object. Code that reads value[0] from blocks, pages, users or orders must drop the index.

groupOfImages is a collection by definition and always stays an array. On the request side, IBodyTypeFile.value is typed IFileValue | IFileValue[] accordingly.

Numbers are numbers

integer, float and real values are cast to a number. real used to be left as a string, so the same numeric field reached the consumer as 10 or as "10" depending on which of the three types it was declared with:

const page = await Pages.getPageByUrl('catalog');

// before: page.attributeValues.amount.value // "5"
// now:    page.attributeValues.amount.value // 5

Numeric normalization also runs on form attributes and form-data fields, which were skipped entirely — a rating field of an integer form attribute is a number, not a string.

When submitting data, send a string: IBodyTypeStringNumberFloat.value is string | number | null, and responses come back normalized.

An empty value is always null

The API returns an empty localization map for an unset value. The SDK used to pass it through for text-like types while numeric types became null — the same "no value" state had three representations. It is now always null.

if (page.attributeValues.notes.value === null) {
  // nothing configured for this attribute
}

⚠️ Migration: an unset integer/float is no longer 0. Number(null) is 0, so an explicit null from the API used to be reported as a real zero — a value indistinguishable from a configured 0.

Everything is sorted by position

attributeValues has always been returned in position order, and form attributes now are too. The API returns form fields unordered — a field with position: 10 could arrive after position: 14 — so rendering a form in CMS order required sorting on the consumer side.

A form with no attributes returns attributes: []. The API sends an empty object in that case, and the SDK normalizes it to an empty array, so attributes is always IFormAttribute[] and form.attributes.map(...) is safe on every form.

Nested fields: additionalFields

Nested attribute values arrive under additionalFields. By default the SDK converts the array the API returns into an object keyed by marker; set rawData: true in the config to keep the original array — see Additional Fields Format.

// default (rawData: false)
attribute.additionalFields['my_field'].value;

// rawData: true
attribute.additionalFields.find((f) => f.marker === 'my_field').value;

Nested additionalFields go through the same normalization as top-level attributes — single files are unwrapped and numbers are cast there too.

Typing an attribute value

IAttributeValue.value is typed unknown, because its shape depends on type. Narrow it before use — for timeInterval attributes the SDK ships a type guard:

import { isTimeIntervalAttribute } from 'oneentry';
import type { IAttributeValues } from 'oneentry';

function readText(values: IAttributeValues, marker: string): string {
  const value = values[marker]?.value;
  return typeof value === 'string' ? value : '';
}

---

🔗 Related Documentation

• Time Intervals - expanding timeInterval attributes into slots
• Importing Types - IAttributeValue, IAttributeValues and the rest
• AttributesSets Module - how attributes are configured

---