Document @kbn/config-schema. #50307
Document @kbn/config-schema. #50307
Conversation
azasypkin
added
Team:Core
|
Pinging @elastic/kibana-platform (Team:Platform) |
|
@restrry @kobelb it's my first attempt to document this library, any suggestions and criticism would be highly appreciated! |
💔 Build FailedNot relevant to this PR since it touches only |
|
ACK: reviewing now! |
| # `@kbn/config-schema` — The Kibana config validation library | ||
|
|
||
| `@kbn/config-schema` is a TypeScript library inspired by the Joi and designed to allow run-time validation of the | ||
| Kibana configuration entries providing developers with a fully typed model of the validated data. |
There was a problem hiding this comment.
allow run-time validation of the Kibana configuration entries
This is definitely how this started, but it's used in more situations now. For example, at least currently, it's used for HTTP route validation. Perhaps we should keep the current docs until we figure out the scope of where we want this to be used long-term in the NP and rename the package and update the docs at this point?
There was a problem hiding this comment.
Yeah, its main official focus is still configuration and if decide to recommend using it for anything else we can update this doc then.
Co-Authored-By: Brandon Kobel <brandon.kobel@gmail.com>
… to TS docs from literal schema section.
… first schema violation and unify notes sections.
|
@elasticmachine merge upstream |
|
Hey @elastic/kibana-platform can someone please take a look at this PR? |
This comment has been minimized.
This comment has been minimized.
💚 Build Succeeded |
|
|
||
| Validates input data as an object with a predefined set of properties. | ||
|
|
||
| __Output type:__ `{ [K in keyof TProps]: TypeOf<TProps[K]> } as TObject` |
There was a problem hiding this comment.
There are no references to TProps in the interface. BTW, if we had those types as comments in TSDoc it would solve the problem.
As a by-product:
- we can be sure that comments are always in sync with code.
- have suggestions in IDE.
There was a problem hiding this comment.
There are no references to TProps in the interface.
True, I struggled to find a better way to describe properties type here. Do you have any suggestions?
BTW, if we had those types as comments in TSDoc it would solve the problem
Yeah, but it sounds like a bigger separate effort, I'd leave it for a follow-up.
| ``` | ||
|
|
||
| __Notes:__ | ||
| * Conditional schemas may be hard to read and understand and hence should be used only sparingly. |
There was a problem hiding this comment.
I feel the same every time I see rxjs.iif
Would it be useful to follow their naming convention and use trueResult/falseResult instead of TConditional1/TConditional2 ?
|
Thanks everyone for review! PR includes only md file change so won't wait for CI run this time. |
|
7.x/7.6.0: 52d15e4 |
The attempt to document @kbn/config-schema based on my past knowledge and memory.
cc @jinmu03
Fixes: #39727
[skip-ci]