I agree the documentation is a little confusing here.

I believe the property is there to capture [from an invoice] the standard payment terms messages such as "Payment within 30 days" . To that end I think it should be correctly defined as a Duration eg "P30D".

Equally I believe validFor should for a Duration "P1Y", as different to validThrough.

Whilst reviewing the issue, also noted the obvious omission of an invoiceDate property.

@tmarshbing @nicolastorzec @scor @tilid any opinion on this?

/cc #2648

The changes look good to me. @danbri , I agree with your comment on the grammar of the edit to the description. Once that is fixed, it looks good to go to me.

The billing period for an individual invoice is an interval.
An interval has a duration, and in many cases the interval for an individual invoice is described as 'the interval starting {now} with duration {30 days}' etc. I.e. an interval, parameterised by its start position and duration.

The standard terms for a set/class of invoices is typically specified in terms of a standard duration for the interval that will be associated with the individual invoice, whose individual start-time will be tied to that individual invoice.

Bringing @dr-shorthair 's comment from the pull request in here for visibility:

Terminology is still jumbled here.

time-interval = an interval on the time-line with a beginning and end
duration = distance or amount of time between two instants or temporal positions
period = usually synonym for time-interval
So I would suggest that either the property name or the range needs to be changed:

billingPeriodDuration could have range Duration
billingPeriod should have range Interval or Period, which in 
turn should have a intervalDuration or periodDuration property whose range is Duration
But the proposed state is not coherent.

This issue is being tagged as Stale due to inactivity.

Are you waiting for a proposal?

We have a similar issue; linking here to bring-into-view: #2689 (comment)