raml-org
Use tables and links to specific section instead of text only
Currently, the spec has tables, text, and only few links. We want to improve the content by introducing a better table structure that basically contains the key name of a property, the value type (with link to the specific section), and a description.
For example, the value of the documentation node should look like the following:
| Key Name | Value Type | Description |
|---|---|---|
| title | string |
Non-empty string that represents the title of an individual document. |
| content | string |
Non-empty markdown string that contains the content of an individual document. |
That approach has to be applied consistently throughout the spec. Any redundant text should be also removed.
The table should also include any default value information, right now for some fields is included in the table and for others it is described in a separate paragraph (e.g: displayName). The idea is to know if a field has a default value (either a constant or calculated from another field) just looking at the table.
It will also be good to have an agreement on what is a required field (e.g: title at api level). In 0.8 the interpretation was that is enough to have the key, no matter the value, which makes no sense at all, like having a form with a mandatory field and leaving it blank. My suggestion, is that a mandatory string scalar field should at least have a character, otherwise make the field optional.
The table should also include any default value information, right now for some fields is included in the table and for others it is described in a separate paragraph (e.g: displayName). The idea is to know if a field has a default value (either a constant or calculated from another field) just looking at the table.
Yes, that needs to be part of it.
In 0.8 the interpretation was that is enough to have the key, no matter the value, which makes no sense at all, like having a form with a mandatory field and leaving it blank. My suggestion, is that a mandatory string scalar field should at least have a character, otherwise make the field optional.
Agree. We can put a small paragraph inside the definition and terminology section that defines what a required field needs to have. Especially around scalar-valued nodes it is important that they are non-empty; regardless if they are required or not.