Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document the 'experimental.config.utils.schema' module #4469

Merged
merged 33 commits into from
Oct 22, 2024
Merged

Document the 'experimental.config.utils.schema' module #4469

merged 33 commits into from
Oct 22, 2024

Conversation

andreyaksenov
Copy link
Contributor

@andreyaksenov andreyaksenov commented Aug 26, 2024 •
edited by p7nov
Loading

Fixes #4279.

New samples

The following new samples were added to demonstrate the main use cases of this module.

Config hierarchy

  • config_schema_nodes_scalar
  • config_schema_nodes_record
  • config_schema_nodes_record_hierarchy (based on config_schema_node_record)
  • config_schema_nodes_array (based on config_schema_node_record)
  • config_schema_nodes_map (based on config_schema_node_record)

Annotations

  • config_schema_annotations (based on config_schema_node_record)

Helper methods

  • config_schema_methods (based on config_schema_node_record)

Environment variables

  • config_schema_fromenv (based on config_schema_node_record)

Computed annotations

  • config_schema_computed_annotations (based on config_schema_nodes_record_hierarchy)

Updated samples

The application_role_http_api sample has been updated to use the new module.

Docs

@andreyaksenov andreyaksenov added the do not merge Not ready to be merged label Aug 26, 2024
@andreyaksenov andreyaksenov linked an issue Aug 26, 2024 that may be closed by this pull request
experimental.config.utils.schema: schema-aware hierarchical data processing #4279
Closed
9 tasks
@andreyaksenov andreyaksenov force-pushed the config_utils_schema branch 4 times, most recently from f01f27b to cce41ab Compare August 27, 2024 10:09
@andreyaksenov andreyaksenov marked this pull request as draft August 27, 2024 10:17
@andreyaksenov andreyaksenov removed the do not merge Not ready to be merged label Aug 28, 2024
@andreyaksenov andreyaksenov force-pushed the config_utils_schema branch 15 times, most recently from e5435c9 to 123b26e Compare August 30, 2024 14:19
@andreyaksenov andreyaksenov force-pushed the config_utils_schema branch 5 times, most recently from 35000a1 to 2bfc0ea Compare September 10, 2024 08:36
Totktonada
Totktonada approved these changes Oct 16, 2024
View reviewed changes
Copy link
Member

@Totktonada Totktonada left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No strict objections from my side.

There are points that require some polishing, but everything is generally good.

Thanks for working on it!

@p7nov p7nov requested a review from lenkis October 21, 2024 10:19
lenkis
lenkis requested changes Oct 21, 2024
View reviewed changes
doc/reference/reference_lua/config/utils_schema.rst Outdated Show resolved Hide resolved
doc/reference/reference_lua/config/utils_schema.rst Outdated
Schema nodes describe the hierarchy of options within a schema. There are two types of schema nodes:

- *Scalar* nodes hold a single value of a supported primitive type. For example,
a string configuration option of a role is a scalar node its schema.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
a string configuration option of a role is a scalar node its schema.
a string configuration option of a role is a scalar node.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the missing preposition

doc/reference/reference_lua/config/utils_schema.rst Outdated Show resolved Hide resolved
doc/reference/reference_lua/config/utils_schema.rst Outdated Show resolved Hide resolved
doc/reference/reference_lua/config/utils_schema.rst Outdated Show resolved Hide resolved
doc/reference/reference_lua/config/utils_schema.rst
Comment on lines +1065 to +1066
- a string in the dot notation
- an array-like table
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- a string in the dot notation
- an array-like table
- a string in the dot notation
- an array-like table

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above ^^

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

doc/reference/reference_lua/config/utils_schema.rst

.. method:: pairs()

Walk over the schema and return scalar, array, and map schema nodes
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above, in the reference summary, we annotate the function as "Traverse a configuration". "Walk over" and "traverse" are synonyms, but I'd rather not use them interchangeably for annotating the same function in order to avoid confusion for non-native technical readers. I'd vote for "walk over" in both places.

doc/reference/reference_lua/config/utils_schema.rst Outdated Show resolved Hide resolved
doc/platform/app/app_roles.rst Outdated Show resolved Hide resolved
doc/platform/app/app_roles.rst Outdated

.. _roles_create_custom_role_validate:

Validating a role configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To validate a role's configuration, you need to define the :ref:`validate([cfg]) <roles_api_reference_validate>` function.
To validate a role configuration, you need to define the :ref:`validate([cfg]) <roles_api_reference_validate>` function.
The ``cfg`` argument provides access to the :ref:`role's configuration <roles_create_custom_role_config>` and check its validity.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The ``cfg`` argument provides access to the :ref:`role's configuration <roles_create_custom_role_config>` and check its validity.
The ``cfg`` argument provides access to the :ref:`role's configuration <roles_create_custom_role_config>` and checks its validity.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence seems irrelevant with the new schema validation module, I'm removing it. Thanks for spotting.

@p7nov p7nov requested a review from lenkis October 22, 2024 04:08
@p7nov p7nov merged commit f7d76f6 into latest Oct 22, 2024
1 check passed
@p7nov p7nov deleted the config_utils_schema branch October 22, 2024 04:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Totktonada Totktonada Totktonada approved these changes

@p7nov p7nov p7nov left review comments

@lenkis lenkis lenkis approved these changes

Assignees
No one assigned
Labels
3.2
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

experimental.config.utils.schema: schema-aware hierarchical data processing
4 participants
@andreyaksenov @Totktonada @lenkis @p7nov