Introduce "docs_only" attribute for subsets

[ebeahan]

Overview

Introduce a new attribute for subset file definitions, docs_only. Setting docs_only: True only filters the field to include it in the ECS docs.

Example usage

name: event
fields:
  base:
    fields:
      "@timestamp": {}
  agent:
    fields: "*"
  dll:
    fields: "*"
  ecs:
    fields: "*"
  process:
    fields:
      same_as_process:
        docs_only: True

Use case

Support for situations like the process.same_as_parent field, which is only populated in process reuses. In the current documentation, a field still must be defined and described at the top level. The field's description includes the guidance of which reuses contains the field.

Design

The changes to support docs_only were added to schema.subset_filter. If docs_only is defined on any subset fields, these extra steps take place:

• A second subset with only docs_only fields is created
• Filter a list of docs_only fields using this second subset
• Remove any docs_only fields from the main fields list. Removing the fields prevents them from appearing in any other artifacts.
• Pass the filtered list into the ascii_doc generator alongside the main fields.

Resolves #1907

[ebeahan]

I've also added the two initial entries mentioned as examples in #1907 to the docs-only defs: process.same_as_process and process.entry_meta.type: ECS docs preview

With the refactoring, I've removed these entries. We can handle it in a separate PR.

[andrewkroh]

LGTM.

[ebeahan]

💚 All backports created successfully

Status	Branch	Result
✅	8.2

Questions ?

Please refer to the Backport tool documentation