Improve readability

[tdelmas]

What problem does your proposal solve? Please begin with the relevant issue number. If there is no existing issue, please also describe alternative solutions you have considered.

This PR tries to improve the readability of some points:

• Objects and array of objects, which are too often described as "An array of objects, each containing the keys below."
• REQUIRED field inside OPTIONAL objects, which are marked "Conditionally REQUIRED" with the description "REQUIRED if (name of the object) is defined".

Those make the specification too much verbose, thus blurs the important things. For example, when a field is "Conditionally REQUIRED", it's important to clearly understand why, and having too many fields defined as such without a reason make the specification unnecessarily complicated

What is the proposal?

• Describe the type object, to say once at the top that the keys are defined below.
• Clarify that a REQUIRED field in an OPTIONAL object is only required when the object is present

Is this a breaking change?

• Yes
• No
• Unsure

[tdelmas]

Ping @richfab : Can I have your opinion on those changes?

[richfab]

Thank you @tdelmas for this contribution! We all love precise and concise documentation 💯

I gave my personal opinion as requested. Curious to know what others think!

[richfab]

I like that the proposed solution is more compact and less verbose. I am slightly concerned that the proposed solution may be less obvious for the newcomers to the spec.

Curious to know what @josee-sabourin and others think.

[tdelmas]

I have the opposite feeling : conditionals are hard to read, and having a required field in an optional object is, in my opinion, easier to understand, especially for newcomers. But I want to see if others are feeling something else.

[richfab]

Tagging recent contributors to get your opinion: @mplsmitch, @testower, @cmonagle, @simonsolnes, @ezmckinn, @AntoineAugusti, @ArashMansouri, @jkurzanski.

What is your view on the proposal to make the specification less verbose for REQUIRED fields inside OPTIONAL objects?

Before	After
Conditionally REQUIRED with the mention "REQUIRED if object is defined"	REQUIRED

[testower]

I agree with @tdelmas. If the object itself is optional, there's no need to repeat that information on each property of the object.

[futuretap]

+1 for the changes!

[josee-sabourin]

My two cents:
Personally, I prefer the more explicit version of Conditionally Required / Required if simply because I don't think the "-" before what is contained in an object, or the tab for subsequent objects within that object are super clear. See image below:

If we can make these dashes more explicit, then I would be in favour of this proposal.

[tdelmas]

If we can make these dashes more explicit, than I would be in favour of this proposal.

@josee-sabourin I 100% agree with that analysis. Any suggestion to make it clearer? Maybe one dash per level?

|----------------|---|---|
|`rental_apps`   |   |   |
| - `android`    |   |   |
| - - `store_uri`|   |   |

[josee-sabourin]

A dash per level would be more clear. We could also amend the Object field definition to say "The key value pairs contained within an object are identified by a dash (-). In the instance of an Object within an Object, an extra dash (-) is present."?

The last sentence needs some more work. Open to suggestions.

[mplsmitch]

1. the definition for object at line 191 should be combined with, or replace the existing object definition in the alphabetized list at line 225
2. I'm all for improved readability but I agree with the 2 cents from @josee-sabourin. I think it's pretty easy to misinterpret the "-" and tabs currently used in the Field Name column. One dash per level is an improvement. Another option would be to use the format that Google uses in their GBFS definitions, for example :
   plans
plans[].per_km_pricing
plans[].per_km_pricing[].start

[richfab]

+1 for using the format that Google uses in their GBFS definitions.

[richfab]

Closing in favor of #583