field_details.j2

{%- import 'macros.j2' as macros -%}
{# Title & Description
-#}
[[ecs-{{ fieldset['name'] }}]]
=== {{ fieldset['title'] }} Fields

{{ fieldset['description']|replace("\n", "\n\n") }}

{# Fieldset label beta header -#}
{% if fieldset['beta'] -%}

beta::[ {{ fieldset['beta'] }}]

{% endif -%}

{# Field Details Table Header -#}
[discrete]
==== {{ fieldset['title'] }} Field Details

[options="header"]
|=====
| Field  | Description | Level

// ===============================================================

{# Iterate through each field in the set -#}
{% for field in sorted_fields -%}
{% if 'original_fieldset' not in field -%}

{# `Field` column -#}
|
[[field-{{field['dashed_name']}}]]
<<field-{{field['dashed_name']}}, {{ field['flat_name'] }}>>

{# `Description` column -#}
{#- Beta fields will add the `beta` label -#}
{% if field['beta'] -%}
a| beta:[ {{ field['beta'] }} ]

{{ field['description']|replace("\n", "\n\n") }}
{%- else -%}
a| {{ field['description']|replace("\n", "\n\n") }}
{%- endif %}

{#- iterate through each expected value -#}
{%- if field['expected_values'] %}

Expected values for this field:
{% for val in field['expected_values'] %}
* `{{ val }}`
{%- endfor %}{# for expected_values #}
{%- endif %}{# if 'expected_values' #}

type: {{ field['type'] }}

{% if 'multi_fields' in field -%}

Multi-fields:

{% for mf in field['multi_fields'] -%}

* {{ mf['flat_name'] }} (type: {{ mf ['type'] }})


{% endfor %}{# for mf #}
{% endif %}{# if 'multi_fields' #}
{% if 'array' in field['normalize'] -%}

Note: this field should contain an array of values.


{% endif %}
{% if 'allowed_values' in field %}
*Important*: The field value must be one of the following:

{{ field['allowed_value_names']|join(', ') }}

To learn more about when to use which value, visit the page
<<ecs-allowed-values-{{ field['dashed_name'] }},allowed values for {{ field['flat_name'] }}>>
{% elif 'example' in field -%}

example: `{{ field['example'] }}`

{%- endif %}{# if 'allowed_values' elif 'example' #}

{%-if field['otel'] -%}
{%- for otel in field['otel'] %}

{{ macros.otel_badge }} {{ macros.otel_relation_badge(otel) }} {{ macros.otel_link(field, otel) }}
{%- if 'note' in otel %}

Note: {{ otel['note'] }}
{%- endif -%}{# if 'note' #}
{%- endfor -%}{# for otel #}
{%- endif -%}{# if 'otel' #}

{# `Level` column -#}
| {{ field['level'] }}

// ===============================================================

{% endif %}{# if 'original_fieldset' -#}
{% endfor %}{# for 'field' -#}

|=====

{# do we have `nestings` or `reusable` sections to worry about? -#}
{% if 'nestings' in fieldset or 'reusable' in fieldset -%}

[discrete]
==== Field Reuse

{% if 'reusable' in fieldset -%}

The `{{ fieldset['name'] }}` fields are expected to be nested at:

{% for entry in sorted_reuse_fields %}
* `{{ entry }}`
{% endfor %}

{% if 'top_level' in fieldset['reusable'] and fieldset['reusable']['top_level'] -%}

Note also that the `{{ fieldset['name'] }}` fields may be used directly at the root of the events.

{% else -%}

Note also that the `{{ fieldset['name'] }}` fields are not expected to be used directly at the root of the events.

{%- endif %}{# if 'top_level' -#}
{% endif %}{# if 'reusable' #}


{%- if 'nestings' in fieldset -%}

[[ecs-{{ fieldset['name'] }}-nestings]]
[discrete]
===== Field sets that can be nested under {{ fieldset['title'] }}

[options="header"]
|=====
| Location | Field Set | Description

// ===============================================================


{% for entry in render_nestings_reuse_section -%}

{#- Beta marker on nested fields -#}
| `{{ entry['flat_nesting'] }}`
| <<ecs-{{ entry['name'] }},{{ entry['name'] }}>>
{#- Beta marker on nested fields -#}
{%- if entry['beta'] -%}
| beta:[ {{ entry['beta'] }}]

{{ entry['short'] }}
{%- else %}
| {{ entry['short'] }}
{%- endif %}

{% if entry['normalize'] and 'array' in entry['normalize'] -%}

Note: this reuse should contain an array of {{ entry['name'] }} field set objects.

{% endif -%}
// ===============================================================


{% endfor -%}

|=====

{% endif %}{# if 'nestings' #}
{%- endif %}{# if 'nestings' or 'reusable' in fieldset #}
{%- if usage_doc %}

{# Field Usage Table Header -#}
[discrete]
==== {{ fieldset['title'] }} Field Usage

For usage and examples of the {{ fieldset['name'] }} fields, please see the <<ecs-{{ fieldset['name']|replace("_", "-") }}-usage, {{ fieldset['title'] }} Fields Usage and Examples>> section.

include::usage/{{ fieldset['name'] }}.asciidoc[]

{% endif %}