Add the "es_quirk" annotation to capture snowflakes in ES behavior

[swallez]

Adds a new @es_quirk jsdoc tag to capture weird snowflakes in the specification. This tag's value is a description of the quirk.

It is exported in schema.json as an esQuirk?: string property on type definition and properties. This allows code generators to track the quirks they have effectively implemented and fail if a new quirk appears in the schema that needs to be handled in the code generator.

[delvedor]

Can you add a note about this new tag in both docs/known-issues.md and docs/modeling-guide.md?

[swallez]

Added some docs.

[github-actions]

Following you can find the validation results for the APIs you have changed.

API	Status	Request	Response
indices.add_block	🟢	2/2	2/2
indices.analyze	🟢	20/20	20/20
indices.clear_cache	🟢	4/4	4/4
indices.clone	🟢	6/6	6/6
indices.close	🟢	42/42	42/42
indices.create_data_stream	🟢	25/25	25/25
indices.create	🔴	669/679	679/679
indices.data_streams_stats	🟢	4/4	4/4
indices.delete_alias	🟢	15/15	15/15
indices.delete_data_stream	🟢	27/27	27/27
indices.delete_index_template	🟢	1/1	1/1
indices.delete_template	🟢	9/9	9/9
indices.delete	🟢	104/104	104/104
indices.disk_usage	🟢	1/1	1/1
indices.exists_alias	🟢	36/36	36/36
indices.exists_index_template	⚪	Missing test	Missing test
indices.exists_template	🟢	15/15	15/15
indices.exists	🟢	39/39	39/39
indices.field_usage_stats	🟢	5/5	5/5
indices.flush	🟢	9/9	9/9
indices.forcemerge	🔴	4/4	3/4
indices.get_alias	🔴	80/80	68/80
indices.get_data_stream	🟢	12/12	12/12
indices.get_field_mapping	🔴	15/15	14/15
indices.get_index_template	🔴	16/16	14/16
indices.get_mapping	🔴	74/74	73/74
indices.get_settings	🔴	54/54	47/54
indices.get_template	🟢	30/30	30/30
indices.get	🔴	52/52	48/52
indices.migrate_to_data_stream	⚪	Missing test	Missing test
indices.modify_data_stream	⚪	Missing test	Missing test
indices.open	🟢	17/17	17/17
indices.promote_data_stream	⚪	Missing test	Missing test
indices.put_alias	🟢	54/54	54/54
indices.put_index_template	🔴	36/37	37/37
indices.put_mapping	🔴	70/71	71/71
indices.put_settings	🔴	45/48	48/48
indices.put_template	🔴	39/41	41/41
indices.recovery	🟢	11/11	11/11
indices.refresh	🟢	202/202	202/202
indices.reload_search_analyzers	🟢	2/2	2/2
indices.resolve_index	🟢	5/5	5/5
indices.rollover	🟢	14/14	14/14
indices.segments	🔴	6/6	4/6
indices.shard_stores	🔴	5/5	2/5
indices.shrink	🟢	5/5	5/5
indices.simulate_index_template	🟢	4/4	4/4
indices.simulate_template	🟢	4/4	4/4
indices.split	🟢	4/4	4/4
indices.stats	🟢	82/82	81/81
indices.unfreeze	🟢	1/1	1/1
indices.update_aliases	🟢	22/22	22/22
indices.validate_query	🟢	7/7	7/7

You can validate these APIs yourself by using the make validate target.

[github-actions]

The backport to 7.17 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-7.17 7.17
# Navigate to the new working tree
cd .worktrees/backport-7.17
# Create a new branch
git switch --create backport-1674-to-7.17
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick --mainline 1 6b87085253f821375e300dd82bac6fdcf8e2cc78
# Push it to GitHub
git push --set-upstream origin backport-1674-to-7.17
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-7.17

Then, create a pull request where the base branch is 7.17 and the compare/head branch is backport-1674-to-7.17.