What to expect from the "expected" keyword is not clear

[sandcha]

Hello,

openfisca-france is on a grand tour of its parameters 🧑‍🔧
During this trip, we go through the different syntaxes and we found some parameters with expected instead of a value for a certain date: YYYY-MM-DD: expected

Here is what I did:

I looked into the documentation for the pages that mentioned expected to be reminded of its effect.

Here is what I expected on the expected:

To find in the documentation what YYYY-MM-DD: expected meant as it is used in openfisca-france and the country-template.

Here is what actually happened:

There is a small inconsistency on the expected keyword usage.
In the documentation, the used syntax is:

description: Universal income
metadata:
  unit: currency
values:
  1993-01-01:
    value: 1000
  2010-01-01:
    value: 1500
    metadata:
      reference: http://law.reference.org/universal_income
  2020-01-01:
    expected: 1700

Where expected is a keyname followed by a value while in the model(s), expected is the value.

And it says that:

In this example, the parameter universal_income.amount is: (...) expected to be raised to 1700 “local currency” in 2020.

But nothing on how it affects the calculation. 😕

While in the country-template, the comment in the YAML file is clear:

# We expect this parameter to change on the [date]
# Placeholders have no impact on calculations. They are just metadata to indicate that we expect a parameter to change at a certain date.

So, I don't know if the documentation syntax stil works but I know that the country-template and openfisca-france does.
And, would be helpful to read from the documentation if the keyword has an impact on the calculation (Does it raise a warning ?...).