References

Reference entities and their records — brands, manufacturers and any other domain a product points at by attribute value instead of duplicating on every row.

A brand is not a string on nine thousand products. It is a record the catalog points at, so it is edited once.

Two entities do this:

Entity	Base path	Is
`reference_entities`	`/v1/products/reference_entities`	The domain — "brand", "manufacturer", "certification"
`reference_entity_records`	`/v1/products/reference_entity_records`	The rows inside it — "acme", "globex"

The entity

Reference entity

{
  "code": "brand",
  "labels": { "en": "Brand", "de": "Marke" },
  "image": null
}

code is unique per tenant and is the stable identifier. labels is the heading over its record list. image is a delivery path or URL for the entity's own icon and is cosmetic — nothing in this app resolves it.

The records

Reference entity record

{
  "reference_entity_id": "…",
  "code": "acme",
  "labels": { "en": "ACME Tools" },
  "attribute_values": {
    "common": { "founded": 1946, "website": "https://example.com" }
  }
}

code is unique within the entity, and it is the value a product stores when it points at this record — the same way a select stores an option code, never a label.

A record carries attribute_values with the same four-bucket structure a product does, so a reference domain can be modelled as richly as the catalog itself. See Products for the bucket rules.

How a product points at one

An attribute of type: "reference_entity" names the domain in its config.reference_entity, and the product then stores the record's code in attribute_values:

attribute_values

{ "common": { "brand": "acme" } }

Reference-entity attributes are declared exactly like any other attribute — see Data model.

Attributes on a reference domain

Attributes are not products-only. An attribute row carries entity_type (product, reference_entity, asset, category) and, for the reference and asset cases, an entity_ref naming one domain by code — the attributes of brand rather than of every reference entity.

Reference records have attributes but no family, so read their shape without a family:

Request

curl "https://api.revenexx.com/v1/products/attribute-schema?entity_type=reference_entity&entity_ref=brand" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

That returns every attribute declared for that domain, ready to render. See Completeness.

Where to go next

Data model — declaring the attribute that points here.
Assets — the other entity kind with attributes and no family.
Products — the attribute document a reference code is stored in.

Was this page helpful?