GraphQL new custom fields

20 August 2019

Composable Commerce

HTTP API

Enhancement

Deprecation

ExtensibilityGraphQL

The customFields field on GraphQL queries is deprecated in favor of the new custom field. customFields is still available for use in queries, but we strongly encourage all users to switch to using custom in GraphQL queries. For more information about this change, see Beta Features.

We are deprecating the existing customFields graphQL field present on all fields having custom fields for a better alternative.

In the new approach, all fields having custom fields have the new custom field exposes the following sub-fields:

type RawCustomField {
  name: String!
  value: Json!
}

type CustomFieldsType {
  typeRef: Reference!
  type: TypeDefinition

  "This field contains non-typed data. For a typed alternative, have a look at `customFields`."
  customFieldsRaw(
    includeNames: [String!],
    excludeNames: [String!]): [RawCustomField!]

  "This field contains typed data"
  customFields: Type!
}

The customFields provides access to typed custom fields.

The new custom field improves the performance of the query as long as you don't use typed fields. For example:

fragment customFields on ProducePrice {
  custom {
    typeRef {
      id
    }
    rawCustomFields {
      name
      value
    }
  }
}

If you use custom.customFields then you won't profit from the better performance.

[GraphQL API] Added the following types to the GraphQL schema: CustomFieldsType.
[GraphQL API] Changed the Category type:
- Added the custom field to the Category type.
- Field customFieldsRaw was deprecated in Category type
- Field customFields was deprecated in Category type
[GraphQL API] Changed the Channel type:
- Added the custom field to the Channel type.
- Field customFields was deprecated in Channel type
- Field customFieldsRaw was deprecated in Channel type
[GraphQL API] Changed the ProductPrice type:
- Added the custom field to the ProductPrice type.
- Field customFieldsRaw was deprecated in ProductPrice type
- Field customFields was deprecated in ProductPrice type
[GraphQL API] Changed the Cart type:
- Added the custom field to the Cart type.
- Field customFieldsRaw was deprecated in Cart type
- Field customFields was deprecated in Cart type
[GraphQL API] Changed the CustomerGroup type:
- Added the custom field to the CustomerGroup type.
- Field customFieldsRaw was deprecated in CustomerGroup type
- Field customFields was deprecated in CustomerGroup type
[GraphQL API] Changed the Asset type:
- Added the custom field to the Asset type.
- Field customFields was deprecated in Asset type
- Field customFieldsRaw was deprecated in Asset type
[GraphQL API] Changed the CustomLineItem type:
- Added the custom field to the CustomLineItem type.
- Field customFields was deprecated in CustomLineItem type
- Field customFieldsRaw was deprecated in CustomLineItem type
[GraphQL API] Changed the Customer type:
- Added the custom field to the Customer type.
- Field customFieldsRaw was deprecated in Customer type
- Field customFields was deprecated in Customer type
[GraphQL API] Changed the CartDiscount type:
- Added the custom field to the CartDiscount type.
- Field customFields was deprecated in CartDiscount type
- Field customFieldsRaw was deprecated in CartDiscount type
[GraphQL API] Changed the Payment type:
- Added the custom field to the Payment type.
- Field customFieldsRaw was deprecated in Payment type
- Field customFields was deprecated in Payment type
[GraphQL API] Changed the CategorySearch type:
- Added the custom field to the CategorySearch type.
- Field customFields was deprecated in CategorySearch type
- Field customFieldsRaw was deprecated in CategorySearch type
[GraphQL API] Changed the Order type:
- Added the custom field to the Order type.
- Field customFieldsRaw was deprecated in Order type
- Field customFields was deprecated in Order type
[GraphQL API] Changed the InventoryEntry type:
- Added the custom field to the InventoryEntry type.
- Field customFields was deprecated in InventoryEntry type
- Field customFieldsRaw was deprecated in InventoryEntry type
[GraphQL API] Changed the LineItem type:
- Added the custom field to the LineItem type.
- Field customFields was deprecated in LineItem type
- Field customFieldsRaw was deprecated in LineItem type
[GraphQL API] Changed the DiscountCode type:
- Added the custom field to the DiscountCode type.
- Field customFields was deprecated in DiscountCode type
- Field customFieldsRaw was deprecated in DiscountCode type

Introduced the following changes to the GraphQL schema (in SDL format):

extend type Category {
  custom: CustomFieldsType
}

extend type Channel {
  custom: CustomFieldsType
}

extend type ProductPrice {
  custom: CustomFieldsType
}

extend type Cart {
  custom: CustomFieldsType
}

extend type CustomerGroup {
  custom: CustomFieldsType
}

extend type Asset {
  custom: CustomFieldsType
}

extend type CustomLineItem {
  custom: CustomFieldsType
}

extend type Customer {
  custom: CustomFieldsType
}

extend type CartDiscount {
  custom: CustomFieldsType
}

extend type Payment {
  custom: CustomFieldsType
}

extend type CategorySearch {
  custom: CustomFieldsType
}

extend type Order {
  custom: CustomFieldsType
}

extend type InventoryEntry {
  custom: CustomFieldsType
}

extend type LineItem {
  custom: CustomFieldsType
}

extend type DiscountCode {
  custom: CustomFieldsType
}

type CustomFieldsType {
  typeRef: Reference!
  type: TypeDefinition

  "This field contains non-typed data. For a typed alternative, have a look at `customFields`."
  customFieldsRaw(
    """
    The names of the custom fields to include.

    If neither `includeNames` nor `excludeNames` are provided, then all custom fields are returned.
    """
    includeNames: [String!],

    """
    The names of the custom fields to exclude.

    If neither `includeNames` nor `excludeNames` are provided, then all custom fields are returned.
    """
    excludeNames: [String!]): [RawCustomField!]

  "This field contains typed data"
  customFields: Type!
}