New orderby key added to configuration schema for sequences

In Drupal 8.3.x and earlier, sequences in configuration are not sorted unless code responsible for saving explicitly sorts. In 8.4.x, sequences can be sorted by specifying an orderby key in the config schema definition. Possible values are: key and value. By default all sequences are still not sorted. This is to preserve backwards-compatibility and not result in unexpected change on configuration save.

It is strongly recommended to add preferred sorting to avoid confusing diffs in configuration and even potential data integrity problems. Drupal core configuration schemas will be updated with default sorting for sequences in a future release. If the value you are storing in the sequence is an associative array the recommended sort is key. If the value is an non-associative array then the recommended sort is value.

If you use orderby: value any keys set will be lost. This behaviour is analogous to PHP's sort() function - see https://secure.php.net/manual/en/function.sort.php.

Non-associative array example:

The user role configuration stores a non-associative array of permission machine names in its permissions key. This should be sorted by value because we are not interested in what order the permissions where added to the role.

user.role.*:
    // ... other config schema key definitions
    permissions:
      type: sequence
      label: 'Permissions'
      orderby: value
      sequence:
        type: string
        label: 'Permission'

Before adding the orderby

Permissions are added in the order added to the role.

permissions:
  - 'access comments'
  - 'access content'
  - 'access shortcuts'
  - 'access site-wide contact form'
  - 'post comments'
  - 'search content'
  - 'use text format basic_html'
  - 'skip comment approval'

After adding the orderby

Permissions are sorted by value

permissions:
  - 'access comments'
  - 'access content'
  - 'access shortcuts'
  - 'access site-wide contact form'
  - 'post comments'
  - 'search content'
  - 'skip comment approval'
  - 'use text format basic_html'

Associative array example:

The Workflow config entity stores states keyed by state machine name. This should be sorted by key because we don't want to lose the state machine name.

workflows.workflow.*:
  type: config_entity
  label: 'Workflow'
  mapping:
    //... some other config schema info
    states:
      type: sequence
      label: 'States'
      orderby: key
      sequence:
        type: mapping
        label: 'State'
        mapping:
          label:
            type: label
            label: 'Label'
          weight:
            type: integer
            label: 'Weight'