Preliminaries
The metadata template that is described in these pages is normatively specified using a CEDAR Template. This page describes the terminology that we use when talking about a template.
Terminology
Instances
A metadata instance is a document that specifies some specific metadata for some specific data. For example, given a data file, the metadata for the file may describe the file creation date and the name of the person that created the file.
Metadata instances are represented using JSON documents, or more specifically JSON-LD (JSON for Linked Data) documents. A portion of a metadata instances that describes the creation of a file is shown below. You should not worry about understanding the formatting or meaning of this snippet at this stage. This metadata specifies that the file was created on October 10, 2022 at 16:44:03 (4:44pm) GMT, it specifies the identifer for the person who created the file as https://orcid.org/0000-0002-1825-0097 and the name of the person who created the file as "Josiah Carberry". In this case, the identifier for the person is an ORCID.
"Creation Date" {
"@value" : "2022-10-10T16:44:03.195Z"
},
"Creator Identifier" {
"@id" : "https://orcid.org/0000-0002-1825-0097"
},
"Creator Name": {
"@value": "Josiah Carberry"
}
Templates
A metadata template is a schema for metadata instances. Following on from the example above, a metadata template would specify that the "Creation Date" is a date/time, that the "Creator Identifier" field is a string that represents an Internationalized Resource Identifier (IRI), and that the "Creator Name" field is a string.
At their core metadata templates are specified as JSON-Schema. They do however also contain other details, for example information that can be used to generate user-interfaces for metadata instance collection. Like metadata instances, templates contain JSON Linked Data (JSON-LD) markup that is used to embed semantic information into the template that precisely specifies the meaning of "Creation Date", "Creator Identifier" and "Creator Name". This JSON-LD markup is most visible as @context objects that are spread throughout a template.
An example of the template description of the "Creator Identifier" field that was used in the metadata instance description is shown below. As can be seen, the JSON-Schema/JSON-LD representation of metadata templates is quite verbose and considerably more complex and intimidating that the simple representation of metadata instances. We only provide this example here so you can seen what a fragment of a template looks like.
"Creator Identifier": {
"@type": "https://schema.metadatacenter.org/core/TemplateField",
"@id": "https://repo.metadatacenter.org/template-fields/f88856cc-5b85-444a-bbd1-7d56ff71ed34",
"schema:identifier": "creator_identifier",
"schema:name": "Creator Identifier",
"schema:description": "Globally unique string that identifies the creator (an individual or legal entity).",
"pav:derivedFrom": "",
"skos:prefLabel": "Creator Identifier",
"skos:altLabel": [],
"pav:version": "0.9.1",
"bibo:status": "bibo:draft",
"_valueConstraints": {
"defaultValue": "",
"requiredValue": false,
"multipleChoice": false
},
"_ui": {
"inputType": "textfield"
},
"pav:createdOn": null,
"pav:createdBy": null,
"pav:lastUpdatedOn": null,
"oslc:modifiedBy": null,
"type": "object",
"title": "Field(Creator Identifier)",
"description": "Generated by CSV2CEDAR.",
"properties": {
"@type": {
"oneOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"format": "uri"
},
"uniqueItems": true
}
]
},
"@value": {
"type": [
"string",
"null"
]
},
"rdfs:label": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false,
"schema:schemaVersion": "1.6.0",
"@context": {
"xsd": "http://www.w3.org/2001/XMLSchema#",
"pav": "http://purl.org/pav/",
"bibo": "http://purl.org/ontology/bibo/",
"oslc": "http://open-services.net/ns/core#",
"schema": "http://schema.org/",
"skos": "http://www.w3.org/2004/02/skos/core#",
"schema:name": {
"@type": "xsd:string"
},
"schema:description": {
"@type": "xsd:string"
},
"skos:prefLabel": {
"@type": "xsd:string"
},
"skos:altLabel": {
"@type": "xsd:string"
},
"pav:createdOn": {
"@type": "xsd:dateTime"
},
"pav:createdBy": {
"@type": "@id"
},
"pav:lastUpdatedOn": {
"@type": "xsd:dateTime"
},
"oslc:modifiedBy": {
"@type": "@id"
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
Fields
A field is the most basic descriptive unit of a metadata template. The key aspects of a field are that is has a name (for example "Creator Identifier"), a description (or help text). Fields are either directly or indirectly embedded into template to form a complate metadata description.
Field values can either by literals, which are essentially strings, or they can be Internationalized Resource Identifiers (IRI). IRIs are typically resolvable, which means they can be opened in a Web browser.
Literal Field Values
In JSON-LD literals are represented with JSON objects that have a @value field. For example, to represent the string literal "Stanford University" the following JSON-LD would be used.
{
"@value" : "Stanford University"
}
IRI Field Values
In JSON-LD Internationalized Resource Identifiers (IRIs) are represented with JSON object that have an @id field. For example, to represent the IRI https://ror.org/00f54p054, which is the Research Organization Registry (ROR) identifier for Stanford University, we would write,
{
"@id" : "https://ror.org/00f54p054"
}
Note that you can visit https://ror.org/00f54p054 to read, or programmatically access, more details about Stanford University.
As can be seen, the raw Research Organization Registry IRI that we used for Stanford University doesn't provide any clue about its meaning. In some cases we therefore attach a human-friendly label to the IRI using an rdfs:label field, for example,
{
"@id" : "https://ror.org/00f54p054",
"rdfs:label" : "Stanford University"
}
Labels like make JSON-LD metadata easier to read but they are not required. Tools such as CEDAR will automatically insert labels.
Elements
An element is an ordered collection of fields and other nested elements. For example, we may have a "Creator" element that comprises the "Creator Identifier", "First Name" and "Last Name" fields. Like fields, elements have a name and a description, amongst other attributes. The artifacts contained in an element may have multiplicities assigned to them. Thus, we can say that a field in an element is required (min 1) and/or single valued (max 1).
Technologies
Template, fields and elements make heavy use of JSON-Schema and JSON for Linking Data (JSON-LD). We provide a very brief summary of these technlogies here. For more detailed information on these technologies please see the linked Web sites.
JSON-Schema
Like XML Schema for XML documents, JSON-Schema provides a declarative way of describing JSON documents and a JSON-Schema can be used to validate a JSON document.
JSON-LD
JSON-LD adds Semantic markup to JSON, making the meaning of JSON documents precise and increasing interoperability across the Web. Indeed, search engines such as Google take advantage of JSON-LD markup to discover the unambiguous meaning of information in JSON documents. For our purposes, JSON-LD aids us in making metadata FAIR – Findable, Accessible, Interoperable and Resuable.