Closed scottdyer closed 7 years ago
I have started to write the JSON Schema for the format and there were some breaking stuff to be addressed as per #26.
The schema is as follows with description of what fields are and can/must be validated:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"definitions": {
},
"id": "#",
"properties": {
"header": {
"id": "/properties/header",
"properties": {
"schema_version": {
"description": "Required, schema version of the current document.",
"id": "/properties/header/properties/api_version",
"type": "string"
},
"catalog_number": {
"description": "Optional, ",
"id": "/properties/header/properties/catalog_number",
"type": ["string", "null"]
},
"comments": {
"description": "Optional, additional information to the spectral dataset.",
"id": "/properties/header/properties/comments",
"type": ["string", "null"]
},
"description": {
"description": "Required, description of the spectral dataset",
"id": "/properties/header/properties/description",
"type": "string"
},
"document_creation_date": {
"description": "Required, document creation date expressed as per RFC 3339 - Date and Time on the Internet: Timestamps, e.g. 2017-01-01T12:00:00Z",
"id": "/properties/header/properties/document_creation_date",
"type": "string",
"format": "date-time"
},
"document_creator": {
"description": "Required, creator of the document, e.g. company, individual, laboratory, etc...",
"id": "/properties/header/properties/document_creator",
"type": "string"
},
"laboratory": {
"description": "Optional, laboratory or company that performed the measurements.",
"id": "/properties/header/properties/laboratory",
"type": ["string", "null"]
},
"license": {
"description": "Required, usage license of the document, e.g. CC-BY-NC-ND",
"id": "/properties/header/properties/license",
"type": "string"
},
"manufacturer": {
"description": "Optional, manufacturer of the device being tested.",
"id": "/properties/header/properties/manufacturer",
"type": ["string", "null"]
},
"measurement_equipment": {
"description": "Optional, measurement equipment used to test the device.",
"id": "/properties/header/properties/measurement_equipment",
"type": ["string", "null"]
},
"model": {
"description": "Optional, model of the device being tested.",
"id": "/properties/header/properties/model",
"type": ["string", "null"]
},
"unique_identifier": {
"description": "Optional, generated unique identifier for the document, e.g. SHA256.",
"id": "/properties/header/properties/unique_identifier",
"type": ["string", "null"]
}
},
"required": [
"description",
"document_creation_date",
"document_creator",
"license"
],
"type": "object"
},
"spectral_data": {
"id": "/properties/spectral_data",
"properties": {
"bandwidth_FWHM": {
"description": "Optional, spectro-radiometer full-width at half-maximum bandwidth in nm.",
"id": "/properties/spectral_data/properties/bandwidth_FWHM",
"type": ["number", "null"]
},
"bandwidth_corrected": {
"description": "Optional, whether bandwidth correction has been applied to the spectral data.",
"id": "/properties/spectral_data/properties/bandwidth_corrected",
"type": ["boolean", "null"]
},
"data": {
"description": "Required, defines the spectral dataset: at least a *key* from `index` whose *value* is an *object* containing wavelength/values pairs.",
"id": "/properties/spectral_data/properties/data",
"patternProperties": {
"^.*$": { "type": "object" }
},
"additionalProperties": false,
"type": "object"
},
"index": {
"description": "Required, indexes the spectral dataset.",
"id": "/properties/spectral_data/properties/index",
"patternProperties": {
"^.*$": { "type": "array" }
},
"additionalProperties": false,
"type": "object"
},
"reflection_geometry": {
"description": "Required if `units` is *reflectance*, reflection geometry attributes as per CIE 15:2004.",
"id": "/properties/spectral_data/properties/reflection_geometry",
"type": ["string", "null"],
"enum": ["di:8", "de:8", "8:di", "8:de", "d:d", "d:0", "45a:0", "45c:0", "0:45a", "45x:0", "0:45x", "other", null]
},
"transmission_geometry": {
"description": "Required if `units` is *transmittanceā*, transmission geometry attributes as per CIE 15:2004.",
"id": "/properties/spectral_data/properties/transmission_geometry",
"type": ["string", "null"],
"enum": ["0:0", "di:0", "de:0", "0:di", "0:de", "d:d", "other", null]
},
"units": {
"description": "",
"id": "/properties/spectral_data/properties/units",
"type": "string",
"enum": ["flux", "absorptance", "transmittance", "reflectance", "intensity", "irradiance", "radiance", "exitance", "R-Factor", "T-Factor", "relative", "other"]
}
},
"required": [
"data",
"index",
"units"
],
"type": "object"
}
},
"required": [
"header",
"spectral_data"
],
"type": "object"
}
In addition to the labeling/data-identification requirements previously mentioned, documentation should also include details of how data is spaced for internal calculations and describe range, increment, and normalization requirements for data that is added by the user. Extended documentation should make clear whether or not interpolation/extrapolation is done by rawtoaces or if such processing should be done externally before importing to rawtoaces. (I have to check the source code, but I don't believe this type of robust data handling is done "automagicly" by rawtoaces in it's current state - if not, it may be a potentially useful feature for someone to add in later.)
See: http://acescentral.com/t/rawtoaces-calling-all-developer-types/1048/8 and http://acescentral.com/t/rawtoaces-calling-all-developer-types/1048/9
Closed with #55
There is placeholder in README for info about the data format. Details should be provided about what rawtoaces looks for and what fields in JSON are essential for rawtoaces to pick up on the user-added data. e.g. what is the formatting and origin of "proper" strings for the fields found in "header"?