Relationships and Scopes

Relationships connect entities. For a full guide to project-level scope configuration and Studio behavior, see Scopes.

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',
  },
}

Ordered Asset Relationship

Use a multiple relationship to _asset when a field needs a reusable ordered asset gallery. The order is stored on the relationship edge, so the same asset can appear in different galleries with different positions.

{
  name: 'images',
  label: 'Images',
  scope: 'relationship',
  dataType: 'string',
  inputType: 'relationship',
  relationship: {
    mode: 'multiple',
    entity: '_asset',
    field: 'originalFilename',
  },
  options: {
    accept: 'image/*',
    comment: 'Product gallery images',
  },
}

Read ordered asset metadata through the generated connection field so each asset node is returned with its edge properties:

query ProductImages {
  products {
    imagesConnection {
      edges {
        properties {
          sortOrder
        }
        node {
          _id
          originalFilename
          path
        }
      }
    }
  }
}

When connecting assets in mutations, write the order in the generated edge payload:

mutation ConnectProductImage {
  updateProducts(
    where: { _id_EQ: "product-id" }
    update: {
      images: [
        {
          connect: [
            {
              where: { node: { _id_EQ: "asset-id" } }
              edge: { sortOrder: 0 }
            }
          ]
        }
      ]
    }
  ) {
    products {
      _id
    }
  }
}

Persisting sortOrder does not guarantee the plain images list is returned sorted. Query the connection edge data and sort by sortOrder in the client unless your generated GraphQL schema exposes a suitable connection sort argument.

Relationship Modeling Guidance

• Use entity names that exist in your schema.
• Use _asset only for multiple asset gallery fields.
• 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, local fields can inherit from the default scope. 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.