Relationships and Scopes

Relationships connect entities. Scopes control where values come from.

Single Relationship

Use mode: 'single' for one-to-one or many-to-one links.

{
  name: 'company',
  label: 'Company',
  scope: 'relationship',
  dataType: 'string',
  inputType: 'relationship',
  defaultValue: '',
  relationship: {
    mode: 'single',
    entity: 'company',
    field: 'name',
  },
}

Multiple Relationship

Use mode: 'multiple' for one-to-many or many-to-many links.

{
  name: 'tags',
  label: 'Tags',
  scope: 'relationship',
  dataType: 'string',
  inputType: 'relationship',
  defaultValue: '',
  relationship: {
    mode: 'multiple',
    entity: 'tag',
    field: 'name',
  },
}

Relationship Modeling Guidance

• Use entity names that exist in your schema.
• Set field to a stable, user-friendly target attribute (usually primary field).
• Prefer normalized relationship entities for reusable dimensions (tags, currencies, countries, suppliers).
• Use single when cardinality is strictly one.

Scope Types

• global: same value in all scopes.
• local: value per scope (for example localized name or region-specific price).
• relationship: relationship-oriented field semantics.

Scoped Defaults

In non-default scopes, fields can inherit from default values. The form presents a Use default value toggle for scoped behavior.

Practical pattern:

• Keep global invariants in global scope (sku, createdAt).
• Keep market-specific values in local scope (title, price, seoTitle).
• Keep entity links in relationship fields.

Avoid Common Mistakes

• Relationship input without relationship object.
• relationship.entity typo that points to a missing entity.
• Setting a business-critical multi-select as single mode.
• Using free-text fields where controlled relationships are required.