[Proposal] Top level period field

[odscrachel]

What is your proposed change?

To create a top level period field with the following attributes

Title	Field name	Description	Field Type
Period	period	The period of time covered in the dataset given as a year or range of years. If there are multiple resources, each covering a different period of time, this value should be the full range covered by all of the resources.	string

Why is this not covered by the existing model?

This replaces temporal_extent (Years covered in the analysis (one or range) e.g. "2020" or "1980-2015") from DDH_v0.2.xlsx

[duncandewhurst]

I think that we should align the name, title and description of this field with the temporal property from DCAT (already proposed at the resource/distribution level in #54 (comment)):

Field	Title	Description
temporal	Temporal coverage	The temporal period that the dataset covers.

In order to make it possible to validate the data and to further align with DCAT, I think that temporal coverage should be modelled as a Period object. Ideally, that would have .startDate and .endDate properties expressed as full dates, e.g. "2020-01-01". However, if it is possible for only the start and end years to be known, then we can instead have startYear and endYear properties:

Property	Title	Description	Type
startYear	Start year	The year in which the period begins.	integer
endYear	End year	The year in which the period ends.	integer

[duncandewhurst]

Noting that we should align this with the modelling proposed in #54 (comment):

* `start` and `end` could refer to day, month, year... E.g. agricultural damage for first crop season of 2010. But we can also have an individual month/year. E.g. Population layer for 2019;  then user would enter the same `start` and `end`?

In that case, to avoid a proliferation of potentially contradictory fields, I think it would be better to just have .start and .end and to allow them to be expressed as years, months or dates using a subset of ISO8601:

* Year: YYYY

* Month: YYYY-MM

* Day: YYYY-MM-DD

In terms of validation, we can either author a regex for the pattern keyword or a custom format and associated format validator. I think that a regex is preferable as it will be compatible with any validation tooling with support for JSON Schema, but some extra work will be required to make error messages user-friendly.

Regarding the example of a population layer for 2019, if no more detail on the exact dates is known, then both .start and .end should be set to '2019'. We provide guidance in the field description or documentation.

[odscjen]

Combining related comments from #81 (comment), #54 and #81 (comment) the proposal is now

Field	Title	Description
temporal	Temporal coverage	The temporal period that the dataset covers.

Property	Title	Description	Type
start	Start date	The date in which the period begins. This can refer to a year (YYYY), a month (YYYY-MM) or a day (YYYY-MM-DD) as appropriate for the dataset.	date-time
end	End date	The date in which the period ends. This can refer to a year (YYYY), a month (YYYY-MM) or a day (YYYY-MM-DD) as appropriate for the dataset.	date-time
duration	Duration	The total number of time periods covered using ISO 8601 duration format.	date-time
year	Reference year	A general reference year to which the modelled scenario(s) refers (e.g. '2050')	integer

This temporal object will be referenced in hazard.event_set, loss and the top level object.

[odscjen]

The temporal object will also be referenced by exposure.reference_year

[odscjen]

@stufraser1 can we clarify what year is used for which isn't already covered by allowing start and end to be the same year?

[odscjen]

answer to my question in #62 (comment)

[odscjen]

see #62 (comment) for potential change

[odscjen]

addressed by #104