dapr / dapr/components-contrib
metadata.yaml schema: improvements on default values and examples
- Dominant language
- Go
- Stars
- 602
- Forks
- 580
- Avg merge
- 4d 9h
- Merged PRs (30d)
- 6
Description
For our components' metadata, all values are technically strings: even numbers, are interpreted as strings in Component YAMLs.
In the metadata.yaml, we try to reflect this by using quotes around all examples and default values. Sometimes that makes us include awkward double quotes, such as:
https://github.com/dapr/components-contrib/blob/b3e2b1024a508d2aca07a124ea5a6cf63ff9a70c/bindings/http/metadata.yaml#L48-L49
This should be improved in two ways.
## First: remove double quotes - let renderers add quotes when they render the metadat.ayaml
We should update all metadata.yaml documents to not include double quotes, so things like `default: '"100Mi"'` will become `default: "100Mi"` (or even just `default: 100Mi` when it's valid YAML)
Renderers should then add quotes around all examples and default values automatically
## Second: update schema for examples
The change above is fine for the default value, but it does cause issues with examples since examples may contain multiple values (e.g. `example: `"true" or "false"`) where quotes do matter (we can't rely on renderers to add them automatically), or even explanations such as `example: '"100" (as bytes)`
To fix that, we can:
1. Make `example` support arrays too. If a single string is passed, the renderer will quote it. If an array is passed, they are considered as multiple examples and they will be quoted independently in the renderer
2. Add a field `exampleRaw` which is not quoted automatically and allows typing things such as `exampleRaw: '"100" (as bytes)`
- `example` and `exampleRaw` are mutually-exclusive
Contributor guide
Research direction
Start with the bindings/http/metadata.yaml example linked in the issue and inspect the repository's metadata.yaml documents and renderers. Determine how defaults and examples are currently represented, then verify that all metadata files and renderers consistently support unquoted defaults, array-valued example, exampleRaw, and mutual exclusion between example and exampleRaw.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- yaml
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100