docs: YAML syntax in the data schema files #11220
Open
+116
−121
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
==========================================
This pull request applies to files
```
docs/api/ref/schemas/api.yaml
docs/api/ref/schemas/ecoscore-country-code.yaml
docs/api/ref/schemas/product-nutriscore.yaml
docs/api/ref/schemas/product-nutristion.yaml
```
Multi-line string
-----------------
The `api.yaml` file contains the following specification:
```
components:
securitySchemes:
[ ... cut ... ]
userAgentAuth:
description: Authentication using User-Agent header
User-Agent header in the format 'app_name/app_version (email)'
type: apiKey
in: header
name: User-Agent
```
The description of `userAgentAuth` spans two lines, so it should be written as:
```
components:
securitySchemes:
[ ... cut ... ]
userAgentAuth:
description: |
Authentication using User-Agent header
User-Agent header in the format 'app_name/app_version (email)'
type: apiKey
in: header
name: User-Agent
```
Array in JSON syntax
--------------------
In a YAML file, an array can use the YAML syntax, i.e. each item on a
separate line, with a dash prefix at a constant indent level, or use
the JSON syntax, i.e. all items separated with a comma and the whole
list enclose dwithin square brackets. Yet, with the `YAML.pm` Perl
module, a JSON-syntax list should be on a single line. A multi-line
JSON syntax triggers an error.
Therefore the lists:
```
components:
schemas:
EcoscoreCountryCode:
type: string
enum:
[
"ad",
"al",
"at",
[ ... cut ... ]
"world",
"xk",
]
```
and
```
id:
type: string
examples:
[
"energy",
"sugars",
"saturated_fat",
"salt",
"fiber",
"fruits_vegetables_legumes",
]
```
and
```
type: string
enum:
[
"公斤",
"公升",
"kg",
"кг",
"l",
"л",
[ ... cut ... ]
"gpg",
]
```
should be written as a single JSON line (rather cumbersome in two
cases, not tested in the third case)
```
id:
type: string
examples: [ "energy", "sugars", "saturated_fat", "salt", "fiber", "fruits_vegetables_legumes" ]
```
or with the YAML syntax (better):
```
components:
schemas:
EcoscoreCountryCode:
type: string
enum:
- "ad"
- "al"
- "at"
[ ... cut ... ]
- "world"
- "xk"
```
and
```
id:
type: string
examples:
- "energy"
- "sugars"
- "saturated_fat"
- "salt"
- "fiber"
- "fruits_vegetables_legumes"
```
and
```
type: string
enum:
- "公斤"
- "公升"
- "kg"
- "кг"
- "l"
- "л"
[ ... cut ... ]
- "gpg"
```
Happy new year!
github-actions
bot
added
📚 Documentation
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #11220 +/- ##
=======================================
Coverage 49.22% 49.22%
=======================================
Files 78 78
Lines 22405 22405
Branches 5374 5374
=======================================
Hits 11028 11028
Misses 10020 10020
Partials 1357 1357 ☔ View full report in Codecov by Sentry. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
docs: YAML syntax in the data schema files
This pull request applies to files
Multi-line string
The
api.yamlfile contains the following specification:The description of
userAgentAuthspans two lines, so it should be written as:Array in JSON syntax
In a YAML file, an array can use the YAML syntax, i.e. each item on a separate line, with a dash prefix at a constant indent level, or use the JSON syntax, i.e. all items separated with a comma and the whole list enclose dwithin square brackets. Yet, with the
YAML.pmPerl module, a JSON-syntax list should be on a single line. A multi-line JSON syntax triggers an error.Therefore the lists:
and
and
should be written as a single JSON line (rather cumbersome in two cases, not tested in the third case)
or with the YAML syntax (better):
and
and
Happy new year!