schema.json

{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"$id": "https://github.com/nblmc/Data-Context/blob/master/schema.json",
	"title": "LMEC Data Description Schema",
	"type": "object",
	"properties": {
		"core": {
			"description": "General information about the dataset or collection ",
			"type": "object",
			"properties": {
				"$id": {
					"type": "string",
					"description": "The dataset or collection's unique identifier",
					"format": "uri"
				},
				"title": {
					"description": "Dataset's full title",
					"type": "string"
				},
				"recordType": {
					"description": "Distinguishes between records describing collections, and records describing singular datasets",
					"type": "string",
					"enum": ["Collection", "Dataset"]
				},
				"excludeIndex": {
					"description": "Optional flag to keep the record from showing up in search results",
					"type": "boolean"
				},
				"collectionItems": {
					"description": "If the record describes a collection, this field is used to link to collection items",
					"type": "array",
					"items": {
						"type": "string",
						"format": "uri"
					}
				},
				"shortDescription": {
					"description": "Description of the dataset used for search results preview. Format this as theme; geographic coverage; temporal coverage",
					"type": "string"
				},
				"fullDescription": {
					"description": "The full description gives an overview of the dataset. This includes topic, geographic coverage, temporal coverage, reason for including the dataset as a public resource, and any important actors",
					"type": "string"
				},
				"keyAttributes": {
					"description": "List of important attributes to preview dataset contents prior to download",
					"type": "array",
					"items": {
						"type": "string"
					}
				},
				"dataTypes": {
					"description": "Optional field for denoting data types, to power interface faceting",
					"type": "array",
					"items": {
						"type": "string",
						"minItems": 1,
						"enum": ["Polygon", "Raster", "Line", "Point", "MultiPolygon", "MultiLineString", "MultiPoint", "Undetermined"]
					}
				},
				"bboxPreview": {
					"description": "Information about the dataset's coordinate system and geographic extent",
					"type": "object",
					"properties": {
						"previewSRS": {
							"description": "EPSG code",
							"type": "string",
							"const": "EPSG:4326"
						},
						"lowerCorner": {
							"type": "array",
							"description": "Lower corner coordinates",
							"items": {
								"type": "number",
								"examples": [-71.181891, 42.330256]
							}
						},
						"upperCorner": {
							"type": "array",
							"description": "Upper corner coordinates",
							"items": {
								"type": "number",
								"examples": [-71.181891, 42.330256]
							}
						}
					}
				},
				"accessCondition": {
					"description": "Notes about access conditions, specifically relating to copyright and use restrictions",
					"type": "string",
					"examples": ["This item is in the public domain. There are no restrictions on use.", "Access restriction details"]
				}
			},
			"required": ["$id", "title", "recordType", "shortDescription", "fullDescription", "accessCondition"]
		},
		"access": {
			"description": "Points to direct access to the dataset",
			"type": "array",
			"items": [{
				"type": "object",
				"properties": {
					"$id": {
						"description": "Unique ID",
						"type": "string",
						"format": "uri"
					},
					"accessURL": {
						"description": "Direct data access endpoint",
						"type": "string"
					},
					"title": {
						"description": "Resource title",
						"type": "string"
					},
					"format": {
						"description": "Data format. Examples - 'Shapefile', 'GeoPackage', 'GeoJSON', 'GeoTIFF', 'CSV', 'Web Tiles', 'Web Service'",
						"type": "string",
						"example": ["Shapefile", "GeoPackage", "GeoJSON", "GeoTIFF", "CSV", "Web Tiles", "Web Service"]
					},
					"source": {
						"description": "Data source",
						"type": "string"
					}
				}
			}],
			"required": ["$id", "accessURL", "title", "source", "format"]
		},
		"tags": {
			"description": "Theme, geography and time tags to ease search and filter ",
			"type": "object",
			"properties": {
				"thematic": {
					"description": "Tags which ease the process of filtering by theme or topic",
					"type": "object",
					"properties": {
						"LCSH": {
							"description": "Library of Congress Subject Headings",
							"type": "array",
							"items": [{
								"type": "object",
								"properties": {
									"authorityName": {
										"type": "string",
										"const": "LCSH"
									},
									"authorityID": {
										"type": "string",
										"const": "http://id.loc.gov/authorities/subjects.html"
									},
									"subjectTag": {
										"type": "string",
										"examples": ["Administrative and political divisions", "National Highway System", "Census districts"]
									}
								},
								"required": ["authorityName", "authorityID", "subjectTag"]
							}]
						},
						"otherSubjectAuthorities": {
							"description": "Place to tag subjects based on authorities not formally encoded in this schema",
							"type": "array",
							"items": [{
								"type": "object",
								"properties": {
									"authorityName": {
										"description": "Define the authority",
										"type": "string"
									},
									"authorityID": {
										"description": "Link to the controlled terms",
										"type": "string",
										"format": "uri"
									},
									"subjectTag": {
										"description": "Enter tag",
										"type": "string"
									}
								}
							}]
						},
						"freeSubjectTags": {
							"type": "array",
							"description": "Place to add any tags for filtering, regardless of whether they belong to a standard vocabulary",
							"items": [{
								"type": "object",
								"properties": {
									"language": {
										"description": "https://www.loc.gov/standards/iso639-2/php/code_list.php",
										"type": "string"
									},
									"subjectTag": {
										"description": "Enter tag",
										"type": "string"
									}
								},
								"required": ["subjectTag"]
							}]
						}
					}
				},
				"geographic": {
					"type": "array",
					"description": "Geonames tags which ease the process of filtering by geography",
					"items": [{
						"type": "object",
						"properties": {
							"authorityName": {
								"type": "string",
								"const": "geonames"
							},
							"authorityID": {
								"type": "string",
								"const": "http://www.geonames.org/ontology#"
							},
							"valueID": {
								"type": "string",
								"examples": ["http://sws.geonames.org/4931353"]
							},
							"placeTag": {
								"type": "string",
								"examples": ["Brighton"]
							}
						}
					}]
				},
				"temporal": {
					"type": "object",
					"description": "Information to contextualize the temporal extent of the dataset, including time coverage and publication date",
					"properties": {
						"temporalNotes": {
							"description": "Used to provide clarity about the temporal details of the dataset",
							"type": "string"
						},
						"temporalRepresentation": {
							"description": "Place to indicate the temporal period the data represents. For instance, if a dataset was published in 2019 but the data itself describes life as it were in 1995, aspects described in temporalRepresentation should point to 1995.",
							"type": "object",
							"properties": {
								"encoding": {
									"type": "string",
									"description": "Observes: https://www.w3.org/TR/NOTE-datetime",
									"const": "https://www.w3.org/TR/NOTE-datetime"
								},
								"valueType": {
									"description": "This field indicates whether the temporal extent of this dataset is expressed as a singular date, or as a range.",
									"type": "string",
									"enum": ["singleDate", "range"]
								},
								"singleDate": {
									"description": "Use this field if the temporal representation is best described as a singular date or year",
									"type": "string"
								},
								"rangeStart": {
									"description": "Use these fields if the temporal representation is best described as a range",
									"type": "string"
								},
								"rangeEnd": {
									"description": "Use these fields if the temporal representation is best described as a range",
									"type": "string"
								}
							}
						},
						"temporalPublication": {
							"description": "Used to indicate details about when the data was published.  Any other date-based information can be added in `temporalNotes` or `temporalRepresentation` for clarity.",
							"type": "object",
							"properties": {
								"encoding": {
									"type": "string",
									"description": "Observes: https://www.w3.org/TR/NOTE-datetime",
									"const": "https://www.w3.org/TR/NOTE-datetime"
								},
								"valueType": {
									"description": "This field indicates whether the temporal extent of this dataset's publication date is expressed as a singular date, or as a range.",
									"type": "string",
									"enum": ["singleDate", "range"]
								},
								"singleDate": {
									"description": "Use this field if the publication date is best described by a singluar date or year",
									"type": "string"
								},
								"rangeStart": {
									"description": "Use these fields if the publication date is best described as a range",
									"type": "string"
								},
								"rangeEnd": {
									"type": "string",
									"description": "Use these fields if the publication date is best described as a range"
								}
							}
						}
					}
				}
			},
			"required": ["thematic"]
		},
		"lifecycle": {
			"description": "Provides context on how people have managed the data during different aspects of the data information lifecycle ",
			"type": "object",
			"properties": {
				"acquisition": {
					"description": "Used to point to a dataset's originating sources, if the data improves upon, derives from, or combines other data sources. This context powers the 'data genealogy' section of the portal interface",
					"type": "object",
					"properties": {
						"ingredients": {
							"description": "A link back to the URI of each source dataset",
							"type": "array",
							"items": [{
								"type": "object",
								"properties": {
									"$id": {
										"type": "string",
										"format": "uri",
										"description": "The unique ID of the source dataset"
									},
									"notes": {
										"type": "string",
										"description": "Qualifies the relationship between the source dataset and the new dataset, if that relationship is not clear"
									}
								}
							}]
						}
					}
				},
				"description": {
					"description": "Information about who wrote metadata describing the dataset",
					"type": "object",
					"properties": {
						"contextProvider": {
							"description": "Person describing this dataset or project",
							"type": "object",
							"properties": {
								"name": {
									"description": "Person's name",
									"type": "string"
								},
								"relationshipToData": {
									"type": "string",
									"description": "Person's relationship to dataset or project"
								}
							}
						},
						"contextOnBehalfOf": {
							"description": "If the person filling out the context is different than the person responsbile for the creation or processing of the dataset or project, note that here",
							"type": "object",
							"properties": {
								"name": {
									"description": "Person's name",
									"type": "string"
								},
								"relationshipToData": {
									"type": "string",
									"description": "Person's relationship to dataset or project"
								}
							}
						},
						"contextPublicationDate": {
							"description": "Date this context was first made available",
							"type": "string",
							"format": "date"
						},
						"metadataSchema": {
							"type": "object",
							"description": "Links out to full LMEC Data Description Schema",
							"properties": {
								"schemaName": {
									"type": "string",
									"const": "LMEC Data Description Schema"
								},
								"$id": {
									"type": "string",
									"description": "https://github.com/bplmaps/data-description-schema/blob/master/schema.json",
									"const": "https://github.com/bplmaps/data-description-schema/blob/master/schema.json"
								}
							}
						}
					},
					"required": ["contextProvider", "contextPublicationDate"]
				},
				"maintenance": {
					"type": "object",
					"description": "Information about who is responsible for updating and maintaining the dataset",
					"properties": {
						"officialMaintainer": {
							"description": "Person or organization responsible for maintaining the dataset",
							"type": "string"
						},
						"maintenanceFrequency": {
							"description": "Regularity with which this dataset is updated. Example values could be 'None', 'Every Monday at Midnight', 'Annually', 'Unknown'",
							"type": "string"
						},
						"typicalUpdates": {
							"description": "If this data is regularly updated, describe the typical nature of the changes",
							"type": "string"
						}
					},
					"required": ["officialMaintainer"]
				},
				"processing": {
					"description": "Place to link out to and describe documentation provided by the data processor. You can encourage data contributors to submit processing context as a README or step-by-step tutorial. ",
					"type": "object",
					"properties": {
						"steps": {
							"description": "Notes about how the dataset came to be, if it was inferred from or combined from other datasets",
							"type": "string"
						},
						"choices": {
							"description": "Links out to READMEs, tutorials or other documentation contributed by the data processor",
							"type": "array",
							"items": [{
								"type": "object",
								"properties": {
									"title": {
										"description": "Name for the record",
										"type": "string"
									},
									"author": {
										"description": "Name of person who authored the record",
										"type": "string"
									},
									"format": {
										"type": "string",
										"description": "Place to denote resource type",
										"examples": ["Blog", "Article", "Guide", "Tutorial", "Jupyter Notebook", "Plain-text README"]
									},
									"accessURL": {
										"description": "Direct link to access the process documentation",
										"type": "string"
									}
								}
							}]
						},
						"tools": {
							"description": "Links out to scripts or other tools created by the processor to aid in the data processing",
							"type": "array",
							"items": [{
								"type": "object",
								"properties": {
									"title": {
										"description": "Name for the record",
										"type": "string"
									},
									"author": {
										"description": "Name of person who authored the record",
										"type": "string"
									},
									"format": {
										"type": "string",
										"description": "Place to denote resource type",
										"examples": ["Python Script"]
									},
									"accessURL": {
										"type": "string"
									}
								}
							}]
						}	
					}
				}
			},
			"required": ["maintenance"]
		},
		"considerations": {
			"description": "A place to note the usefulness of the dataset and supporting materials. ",
			"type": "object",
			"properties": {
				"machineReadability":{
					"description": "Place to provide considerations on the machine readability of the dataset. ",
					"type": "object",
					"properties":{
						"value":{
							"description": "Place for the data describer to provide data users a sense of how well-formatted or contextualized the dataset is. 0 means the data describer has identified potential sandtraps that should give a data user pause when working with the dataset. It also can mean that not enough contextual information is available for the data describer to be able to assign a score.  1 means the data describer believes the data provider has formatted or contextualized the data in a way that allows the data user to proceed with reasonable confidence. 2 means the data describer believes the dataset to be well formatted or described. ",
							"type": "integer"
						},
						"notes":{
							"description": "A place to add qualifying information about the value provided. ",
							"type": "string"
						}
					}
				},
				"humanReadability":{
					"description": "Place to provide considerations on the machine readability of the dataset. ",
					"type": "object",
					"properties":{
						"value":{
							"description": "Place for the data describer to provide data users a sense of how well-formatted or contextualized the dataset is. 0 means the data describer has identified potential sandtraps that should give a data user pause when working with the dataset. It also can mean that not enough contextual information is available for the data describer to be able to assign a score.  1 means the data describer believes the data provider has formatted or contextualized the data in a way that allows the data user to proceed with reasonable confidence. 2 means the data describer believes the dataset to be well formatted or described. ",
							"type": "integer"
						},
						"notes":{
							"description": "A place to add qualifying information about the value provided. ",
							"type": "string"
						}
					}
				},
				"socialEmbeddedness":{
					"description": "Place to provide considerations on the machine readability of the dataset. ",
					"type": "object",
					"properties":{
						"value":{
							"description": "Place for the data describer to provide data users a sense of how well-formatted or contextualized the dataset is. 0 means the data describer has identified potential sandtraps that should give a data user pause when working with the dataset. It also can mean that not enough contextual information is available for the data describer to be able to assign a score.  1 means the data describer believes the data provider has formatted or contextualized the data in a way that allows the data user to proceed with reasonable confidence. 2 means the data describer believes the dataset to be well formatted or described. ",
							"type": "integer"
						},
						"notes":{
							"description": "A place to add qualifying information about the value provided. ",
							"type": "string"
						}
					}
				}
			}
		},
		"resources": {
			"description": "Datasets or data projects are often not useful on their own. Often, we need an entire constellation of supporting resources to make sense of the data we find. The information in this section can be added to as more learning materials become available. ",
			"type": "object",
			"properties": {
				"documentation": {
					"description": "Reference to official documentation sources",
					"type": "array",
					"items": [{
						"type": "object",
						"properties": {
							"$id": {
								"description": "Unique identifier",
								"type:": "string",
								"format": "uri"
							},
							"title": {
								"description": "Resource title",
								"type": "string"
							},
							"maintainedBy": {
								"description": "Person or organization responsible for maintaining and providing access to the documentation",
								"type": "string"
							},
							"notes": {
								"description": "Place to put helpful notes or information about finding, using or interpreting the documentation",
								"type": "string"
							}
						},
						"required": ["$id", "title", "maintainedBy"]
					}]
				},
				"codebooks": {
					"description": "Reference to any codebooks or data dictionaries intended to aid interpretation of the data's attributes or field names",
					"type": "array",
					"items": [{
						"type": "object",
						"properties": {
							"$id": {
								"description": "Unique identifier",
								"type:": "string",
								"format": "uri"
							},
							"title": {
								"description": "Resource title",
								"type": "string"
							},
							"maintainedBy": {
								"description": "Person or organization responsible for maintaining and providing access to the codebook",
								"type": "string"
							},
							"notes": {
								"description": "Place to put helpful notes or information about finding, using or interpreting the codebook",
								"type": "string"
							}
						},
						"required": ["$id", "title", "maintainedBy"]
					}]
				},
				"publishedWorks": {
					"description": "Reference to related blogs, articles, books, data visualizations or other published research based on this data.",
					"type": "array",
					"items": [{
						"type": "object",
						"properties": {
							"$id": {
								"description": "Unique identifier",
								"type:": "string",
								"format": "uri"
							},
							"title": {
								"description": "Resource title",
								"type": "string"
							},
							"author": {
								"description": "Resource author",
								"type": "string"
							},
							"publisher": {
								"description": "Resource publisher",
								"type": "string"
							},
							"datePublished": {
								"description": "Resource publication date",
								"type": "string",
								"format": "date"
							},
							"notes": {
								"description": "Place to note how this resource is relelvant",
								"type": "string"
							},
							"format": {
								"description": "Published works medium",
								"type": "string",
								"example": ["Map", "Article", "Book"]
							}
						}
					}]
				},
				"tutorials": {
					"description": "Reference to guides, tutorials, Jupyter notebooks, or any resource with people-centered instructions on how to work with, use and understand this data",
					"type": "array",
					"items": [{
						"type": "object",
						"properties": {
							"$id": {
								"description": "Unique identifier",
								"type:": "string",
								"format": "uri"
							},
							"title": {
								"description": "Resource title",
								"type": "string"
							},
							"author": {
								"description": "Resource author",
								"type": "string"
							},
							"datePublished": {
								"description": "Resource publication date",
								"type": "string",
								"format": "date"
							},
							"notes": {
								"description": "Place to note how this resource is relelvant",
								"type": "string"
							}
						},
						"required": ["$id", "title"]
					}]
				}
			}
		}
	},
	"required": ["core", "tags", "lifecycle", "considerations"]
}