IntChron Data Schema
Introduction
This data schema is intended to be used for the exchange of chronological information
between databases, data archives and chronological tools.
The data format is specifically designed around the requirements for chronological
analysis tools and is a structured but extensible JSON data format.
Data objects
The data is exchanged as JSON objects. There are three object types defined and these
are designated by the json_applicaiton tag which can take one of three values:
The tag can be given a version suffix like "INCHRON.Project:2" to indicate the version
of the schema being applied. This is to allow conversion if there are changes to the
schema which require different treatment.
Additional tags at the top level define the source and attribution of the data:
- compilation: an object which contains information about the data compilation including
- by: the person or organisation responsible for the compilation
- orcid: the compiler's ORCID (if an indidual)
- url: the compiler's URL (if an organisation)
- updated: the date of the compilation's last update
- retrieved: the date of the data retrieval
- data_url: the url of the data or query that retrieved the data
- schema: the naming schema used (normally a part of this document)
INTCHRON Project
This is the main object type for data exchange. Each such object can
contain the following elements:
- json_application: which should be "INTCHRON.Project"
followed by a suffix for the version number as in "INTCHRON.Project:2"
- records: an array of records each of which has elements:
- file: this url links to the data - or the data is given in file_data
- file_data: the data as defined for a record
- site: the site name
- country (blank if marine)
- longitude (optional but desirable)
- latitude (optional but desirable)
- elevation (optional but desirable)
- site_type (optional but desirable)
- record: the record name
- color (optional)
- selected (optional)
- changed (optional - if set implies file_data is different
from the original file)
- project_series_list: an array of data series not
associated with specific records each of which has elements:
- parameters: an array of parameters used within the project other than those within this schema:
- parameter: the variable name used for the parameter; this should be a valid javascript variable name
- label (optional - the label to be displayed for the parameter)
- record (optional - if set the charactaristics including label etc are only used for this record)
- type: the type of variable
- units (optional but desirable)
- invert (optional - if set plots will show this inverted as default)
- default_value (optional - the default value if cannot be null)
- options (optional - if set is an array of possible values)
- options_colors (optional - if set is an array of associated colors)
- dp: (optional - the number of decimal points for numerial discplay of the parameter)
- selected (optional)
- bibliography: an array of references refered to in the
project.
Only the json_applicaiton tag is required so a project can just be a list of
references or just a list of data series etc. For data exchange and archiving the object
should always include a bibliograpgy unless the data objects only refer to references with
DOIs.
INTCHRON Record
This is primarily intended for users storing site-related data for
their own use. In general data archives should embed these within projects so that
bibliographic information can be included.
The record object contains the following elements:
- json_application: which should be "INTCHRON.Record"
followed by a suffix for the version number as in "INTCHRON.Record:2"
- header: an object containing the record-wide attributes:
- series_list: an array, each element of which has attributes:
- series_type
- data: an object which has elements defined by the series_type
- ... other elements depending on the series_type
- refs: references for the record as a whole
INTCHRON Series
This is primarily intended for users storing specific non site-related series for
their own use. In general data archives should embed these within projects so that
bibliographic information can be included.
The series object has six predefined elements:
- json_application: which should be "INTCHRON.Series"
followed by a suffix for the version number as in "INTCHRON.Series:2"
- project_series_type: which defines what type of
data series this is.
- series: the series name.
- parameter_list: a comma-separated list of extra
parameters included (other than those defined by the project_series_type).
- refs: an array of references for the data series.
- data: which is a data object for the data associated with the
series.
The other elements of the data series are defined by the value of the
project_series_type.
Data series
The data is stored in a very flexible format data object. The object contains an
element which defines it type which is either a:
for a project level object or a:
The series also always contains the following four elements:
- series: the series name.
- parameter_list: a comma-separated list of extra
parameters included (other than those defined by the series_type or
project_series_type).
- refs: an array of references for the data series.
- data: which is a data object for the data associated with the
series.
Only the project series type is normally stored as a data object in
its own right (see INTCHRON Series above).
The other elements of the data object are determined by the the
project_series_type or
series_type, as defined in the tables below. There is always a
data element which is iteself an object. Within this object each of
the dataset parameters is given as an array of values with the name of the parameter.
Elements of project level data series
Elements of data series within a record
As an example of how this works in practice, the following is the structure of a
typical data series within a record:
- series_type: "Proxies"
- series: "Oxygen"
- proxies: "d18O"
- refs: ["doi:10.1038/nature02805"]
- data:
- z: [2426.6,2426.39,...]
- z_range: [0,0,...]
- t: [-58000,-47980,...]
- t_sigma: [0,0,...]
- d18O: [-43.35,-43.55]
Bibliography
The bibiliograpgy is a simple array, each element of which has the following
attributes from the standard BibTeX schema:
In addtion the following elements are included:
- ref: A unique identifier which can be used for references without a doi or as the
citation key.
- reference: a text version of the whole reference.
- citation: a brief first author and year citation.
References are referred to either in the form "ref:citation key" or
"doi:DOI". The latter is to be preferred as it does not require the
bibliography for definition.
Parameters