Best Practices: Data on the Web – #4 Provide structural metadata

And now it is time for the fourth best practice to be recommended in the Data on the Web Best Practices document, which is still about metadata. If you haven't read the first best practices yet, they are here: BP1, BP2, BP3.

BP4: Provide structural metadata

Provide metadata that describes the schema and internal structure of the datasets you are going to distribute.

Providing information about the internal structure of a distribution is essential for others who wish to explore or query the dataset. Providing metadata with structural information also helps people understand the meaning of the data.

Expected Outcome

Humans will be able to interpret the schema of a dataset, and software agents will be able to automatically process this information.

Possible Implementation

But what is structural metadata?

Metadata with structural information that humans can easily read usually provides properties or column names of the dataset schema. On the other hand, machine-readable structural information can be provided in separate documents or embedded within the document itself. The documentation for Tabular Metadata, JSON-LD, XML-SCHEMA, or Datacube presents complete explanations and alternatives for use in describing the structure of your datasets.

Examples of using this metadata:

Machine-readable:

John used the Model for Tabular Data and Metadata on the Web to publish the CSV (dataset) about bus stops (stops-2015-05-05.csv). See how the metadata for the data structures was written in the example below:


{
	"@context": ["http://www.w3.org/ns/csvw", {
		"@language": "en"
	}],
	"url": "http://data.mycity.example.com/transport/dataset/bus/stops-2015-05-05.csv",
	"dc:title": "CSV distribution of stops-2015-05-05 dataset",
	"dcat:keyword": ["bus", "stop", "mobility"],
	"dc:publisher": {
		"schema:name": "Transport Agency of MyCity",
		"schema:url": {
			"@id": "http://example.org"
		}
	},
	"dc:license": {
		"@id": "http://opendefinition.org/licenses/cc-by/"
	},
	"dc:modified": {
		"@value": "2015-05-05",
		"@type": "xsd:date"
	},
	"tableSchema": {
		"columns": [{
			"name": "stop_id",
			"titles": "Identifier",
			"dc:description": "An identifier for the bus stop.",
			"datatype": "string",
			"required": true
		}, {
			"name": "stop_name",
			"titles": "Name",
			"dc:description": "The name of the bus stop.",
			"datatype": "string"
		}, {
			"name": "stop_desc",
			"titles": "Description",
			"dc:description": "A description for the bus stop.",
			"datatype": "string"
		}, {
			"name": "stop_lat",
			"titles": ["Latitude"],
			"dc:description": "The latitude of the bus stop.",
			"datatype": "number"
		}, {
			"name": "stop_long",
			"titles": "Longitude",
			"dc:description": "The longitude of the bus stop.",
			"datatype": "number"
		}, {
			"name": "zone_id",
			"titles": "ZONE",
			"dc:description": "An identifier for the zone where the bus stop is located.",
			"datatype": "string"
		}, {
			"name": "stop_url",
			"titles": "URL",
			"dc:description": "URL that identifies the bus stop.",
			"datatype": "string"
		}],
		"primaryKey": "stop_id"
	}
}

For an example of this same type of metadata with human-readable data, see this page.

To make sure you are applying the 4th best practice, always check if the dataset metadata is in a format that humans can interpret. Check if the metadata includes information about the structure of your datasets in formats that are machine-readable and, preferably, free of syntax errors. :-)