dapr / dapr/components-contrib

metadata.yaml schema: improvements on default values and examples

Open
#3,083 4 comments 2 reactions 0 assignees View on GitHub
kind/enhancement pinned
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.