Expose value-level metadata for parameters in the Web API

[fpagnoux]

Connected to #677 (subset)

The YAML format used for parameters allows to define metadata at the value level. For instance:

description: Amount of the basic income
values:
  2015-12-01:
    value: 600
    metadata:
      reference: https://law.gov.example/basic-income/amount/2015-12
  2014-01-01:
    value: 595
    metadata:
      reference: https://law.gov.example/basic-income/amount/2014-01

However, the parameter format exposed by the Web API is "too compact" to expose these metadata:

{
  "description": "Amount of the basic income", 
  "id": "benefits.basic_income", 
  "values": {
    "2014-01-01": 595.0,
    "2015-12-01": 600.0
  }
}

---

As a client of the API building a front displaying the parameters,
I can access a value metadata through the Web API
So that I can format a parameter accordingly

[fpagnoux]

Suggested new specification:

Align the JSON to the YAML structure:

{
  "description": "Amount of the basic income", 
  "id": "benefits.basic_income", 
  "values": {
    "2014-01-01": {
      "value": 595.0,
      "metadata": {"reference": "https://law.gov.example/basic-income/amount/2014-01"}
    },
    "2015-12-01": {
      "value": 600.0,
      "metadata": {"reference": "https://law.gov.example/basic-income/amount/2015-12"}
    }
  }
}

(This would be a breaking change)

If you're wondering why the heck the YAML and JSON structures were not the same from the beginning, it's worth remembering that this route was built at a time when parameters were still stored as XML, and that this API route actually inspired the YAML format 👴

[MattiSG]

The values root node seems misnamed if we have a value leaf. Since adding one layer in the leaf would be a major breaking change anyway, I think we should use it as an opportunity to rename values, which would also make it easier to discover for reusers:

Proposition 2A

The renaming of “values” is open (hence the “2 A” naming for this proposition). I suggest “inception” as a short for “inception date” (date d'effet), which sounds more like a domain name and conveys IMO both the date and effect idea.
Other ideas I could come up with (“entries”, “steps”) are more technical.

description: Amount of the basic income
inceptions:
  2015-12-01:
    value: 600
    metadata:
      reference: https://law.gov.example/basic-income/amount/2015-12
  2014-01-01:
    value: 595
    metadata:
      reference: https://law.gov.example/basic-income/amount/2014-01

{
  "description": "Amount of the basic income", 
  "id": "benefits.basic_income", 
  "inceptions": {
    "2014-01-01": {
      "value": 595.0,
      "metadata": {"reference": "https://law.gov.example/basic-income/amount/2014-01"}
    },
    "2015-12-01": {
      "value": 600.0,
      "metadata": {"reference": "https://law.gov.example/basic-income/amount/2015-12"}
    }
  }
}

Proposition 3

For the sake of diverging, another option could be to consider that most use cases are about consuming data, and then some other consume metadata. This implementation adds functionality with no breaking change, keeps data navigation simple on the client, but makes the read and write formats of OF parameters diverge much more.

{
  "description": "Amount of the basic income", 
  "id": "benefits.basic_income", 
  "values": {
    "2014-01-01": 595.0,
    "2015-12-01": 600.0
  },
  "metadata": {
    "2014-01-01": {
      "reference": "https://law.gov.example/basic-income/amount/2014-01"
    },
    "2015-12-01": {
      "reference": "https://law.gov.example/basic-income/amount/2015-12"
    }
  }
}

[bonjourmauko]

Adding to Proposition 2A, and based on #697:

If we turn values into periods, a parameter nested resource with attributes rate, threshold, and reference, representation becomes more natural in terms of evolutions of the legislation, each period representing a change to either a rate, a threshold or both.

Proposition 4

description: Social security contribution tax scale
reference: "https://law.gov.example/basic-income/definition"
periods:
  2013-01-01:
    rate: 0.03
    threshold: 12000
    reference: https://law.gov.example/basic-income/amount/decree/2012-12
  2015-01-01:
    value: 0.04
    threshold: 15000
    reference: https://law.gov.example/basic-income/amount/decree/2012-12
  2017-01-01:
    value: 0.02
    threshold: 18000
    reference: https://law.gov.example/basic-income/amount/decree/2016-12

{
  "description": "Social security contribution tax scale",
  "reference": "https://law.gov.example/basic-income/definition",
  "periods": {
    "2013-01-01": {
      "rate": 0.03,
      "threshold": 12000,
      "reference": "https://law.gov.example/basic-income/amount/decree/2012-12"
    },
    "2015-01-01": {
      "value": 0.04,
      "threshold": 15000,
      "reference": "https://law.gov.example/basic-income/amount/decree/2012-12"
    },
    "2017-01-01": {
      "value": 0.02,
      "threshold": 18000,
      "reference": "https://law.gov.example/basic-income/amount/decree/2016-12"
    }
  }
}

[Morendil]

Closing as stale.