Document reuseable.order attribute

[ebeahan]

Summary

The optional attribute reusable.order was introduced in #864 to ensure chained reuses happen in the right order. It may be a necessary setting when dealing with chained reuses.

This attribute should be added to the schemas/README.md doc.

Background

As of ECS 1.7.0, reusable.order is configured on the group fieldset to handle the group => user, user => many places chained reuse case.

Custom fields may also use reusable.order for custom chained reuse. Example:

./custom_schemas/host.yml:

---
- name: host
  title: Host
  type: group
  reusable:
    order: 3
    top_level: true
    expected:
    - acme

./custom_schemas/acme.yml:

---
- name: acme
  title: acme
  group: 2
  description: >
    acme
  type: group

  fields:

  - name: products
    level: custom
    type: keyword
    required: true
    description: >
      products

  - name: people
    level: custom
    type: keyword
    description: >
      people

Generator script command:

$ python scripts/generator.py --include _testing/discuss/schemas --out _testing/discuss/output

Without adding order: 3 in host.yml, the generator will default order to 2. Under the default, host won't have all the expected nestings before host is reused under acme.

Documenting this parameter will be useful for users dealing with this particular scenario.