-
Notifications
You must be signed in to change notification settings - Fork 1
CEDAR Template, Element, and Fields
While CEDAR's Template Designer provides the most user-friendly mechanism for creating templates, elements, and fields, in some cases users may wish to programmatically create them.
This page describes the format of templates, elements, and fields and outlines how they can be programmatically created and then validated and uploaded to CEDAR using its REST APIs.
The CEDAR Repository Model specifies the structure of the three core CEDAR schema artifacts: templates, elements, and fields. (A paper describing this model can be found here; a full specification of the model is available here.) These three artifacts are represented using JSON Schema. The structure of the JSON-based CEDAR instance derived from each artifact is constrained by the artifact's JSON Schema specification. The three corresponding instance types are template instances, element instances, and field instances. (Instructions on how to programmatically create, validate, and upload CEDAR instances can be found here.)
While the specification of templates, elements, and fields is relatively verbose due to the JSON Schema-based representation, they have a relatively simple conceptual structure.
Here is a simple text field expressed in CEDAR's JSON Schema-based representation:
{
"$schema": "http://json-schema.org/draft-04/schema#"
"type": "object",
"title": "Name field schema", "description": "Name field schema generated by the MyTool, v3.4.4",
"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" ] }
},
"required": [ "@value" ], "additionalProperties": false,
"@type": "https://schema.metadatacenter.org/core/TemplateField",
"@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:schemaVersion": "1.6.0",
"pav:version": "0.0.1", "bibo:status": "bibo:draft",
"schema:name": "Name Field", "schema:description": "Please enter your name",
"skos:prefLabel": "User Name", "schema:identifier": "",
"_ui": { "inputType": "textfield" },
"_valueConstraints": { "requiredValue": false },
"@id": null, "pav:createdOn": null, "pav:createdBy": null, "pav:lastUpdatedOn": null, "oslc:modifiedBy": null
}
While this representation looks quite complex, it follows a simple pattern, with five main groups of fields:
JSON Schema Fields | $schema, type, title, description, properties, required and additionalProperties are JSON Schema fields that describe the field itself and the structure of conforming field instances. |
JSON-LD Fields | @type, @context are JSON-LD fields and provide semantic context for the field. |
Core CEDAR Fields | schema:schemaVersion, pav:version, bibo:status, schema:name, schema:description, skos:prefLabel, and schema:identifier are CEDAR-defined fields that describe the field itself. |
UI and Value Constraint Fields | _ui and _valueConstraints are also CEDAR-defined fields, which describe the user interface rendering and constraints placed on field values, respectively. |
Metadata Fields | @id, pav:createdOn, pav:createdBy, pav:lastUpdatedOn, and oslc:modifiedBy are CEDAR-defined fields describing system-level metadata about the field. These values are generated by a CEDAR server on field creation. |
The top-level @context
field contains boilerplate definitions that are common to all field specifications. Similarly properties
field specification is the same for all fields containing non-IRI JSON-LD values (i.e., the values are held in a @value
field). So, if we elide those we get the following more digestible view of a field specification:
{ "$schema": "http://json-schema.org/draft-04/schema#" "type": "object", "title": "Name field schema", "description": "Name field schema generated by the MyTool, v3.4.4", "properties": { ... }, "required": [ "@value" ], "additionalProperties": false, "@type": "https://schema.metadatacenter.org/core/TemplateField", "@context": { ... }, "schema:schemaVersion": "1.6.0", "pav:version": "0.0.1", "bibo:status": "bibo:draft", "schema:name": "Name Field", "schema:description": "Please enter your name", "skos:prefLabel": "User Name", "schema:identifier": "", "_ui": { "inputType": "textfield" }, "_valueConstraints": { "requiredValue": false }, "@id": null, "pav:createdOn": null, "pav:createdBy": null, "pav:lastUpdatedOn": null, "oslc:modifiedBy": null }
These fields lend themselves to be generated programmatically using a templating mechanism with the overall structure of the JSON Schema field being pre-defined and specific customizations then made for individual fields.
The following fields within these JSON Schema field definitions should be customized:
title | This is a JSON Schema field. It is not typically rendered in CEDAR UIs and is instead used to store an internal name for a field, e.g., "Name field schema". |
description | This is a JSON Schema field. It is not typically rendered in CEDAR UIs and is instead used to store an internal description for a field, e.g., "Name field schema generated by MyTool, V3.4.4". This field can be left empty. |
schema:schemaVersion | This is a Schema.org field that specifies the current version of the CEDAR model. This model version must match the model enforced by the CEDAR server that the field is to be uploaded to. |
schema:name | This is a Schema.org field that contains the name of the instance. This is the user-specified name that is rendered in CEDAR UIs. |
schema:description | This is a Schema.org field that contains the description of the instance. This is the user-specified description that is rendered in CEDAR UIs. This field can be left empty. |
pav:version | This is a PAV field that specifies the current version of the field. Detailed information about this field can be found in the section "Representing Schema Artifact Version Information" in the CEDAR Template Model. |
bibo:status | This is a BIBO field that specifies if the field in draft or release status. Detailed information about this field can be found in the section "Representing Schema Artifact Version Information" in the CEDAR Template Model. |
skos:prefLabel | This is a SKOS field than can be used to store the default question text for a field that is presented to users. This field can be left empty. |
schema:identifier | This is a Schema.org field that can be used to store a field identifier. Typically, this field is used to indicate a source identifier of a corresponding field in a 3rd-party system. This field can be left empty. |
As mentioned above, if a field stores its value in a JSON-LD @value
field then the property
field specification outlined above is appropriate. If, however, the field stores IRI-based values then a JSON-LD @id
field is used and the properties
field specification and the associated requiredValues
must be updated to reflect this.
So, instead of the @value
property specification:
"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" ] } },
we will have a @id
property specification as follows:
"properties": { "@type": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" }, "uniqueItems": true } ] }, "rdfs:label": {"type": [ "string", "null" ] }, "@id": { "type": "string", "format": "uri" } },
Note that an rdfs:label
field is required here to store a user-friendly value in instances in addition to the IRI.
The _ui
and _valueConstraints
fields may also need to be customized for different field types or when additional constraints are placed on field values. Full details about these fields can be found in the "Representing User Interface Rendering Specifications" and "Expressing Field Value Constraints" sections, respectively, of the CEDAR Template Model. A full specification of CEDAR template fields can be found in the "Representing Template Fields" section of this document.
Template specifications use the same overall structure as fields, though they are more verbose because they require a lot more constraints on template instances.
Here, for example, is a study template specification with a "Study Name" field nested inside it:
{ "$schema": "http://json-schema.org/draft-04/schema#" "type": "object", "title": "Study template schema", "description": "Study template schema generated by MyTool, v3.6.6", "properties": { "@context": { "type": "object", "properties": { "rdfs": { "type": "string", "format": "uri", "enum": ["http://www.w3.org/2000/01/rdf-schema#"]}, "xsd": { "type": "string", "format": "uri", "enum": ["http://www.w3.org/2001/XMLSchema#"]}, "pav": { "type": "string", "format": "uri", "enum": ["http://purl.org/pav/"]}, "schema": { "type": "string", "format": "uri", "enum": ["http://schema.org/"]}, "oslc": { "type": "string", "format": "uri", "enum": ["http://open-services.net/ns/core#"]}, "skos": { "type": "string", "format": "uri", "enum": ["http://www.w3.org/2004/02/skos/core#"]}, "rdfs:label": { "type": "object", "properties": { "@type": { "type": "string", "enum": ["xsd:string"]}}}, "schema:isBasedOn": { "type": "object", "properties": {"@type": { "type": "string", "enum": ["@id"]}}}, "schema:name": { "type": "object", "properties": {"@type": { "type": "string", "enum": ["xsd:string"]}}}, "schema:description": { "type": "object", "properties": { "@type": { "type": "string", "enum": ["xsd:string"]}}}, "pav:derivedFrom": { "type": "object", "properties": { "@type": { "type": "string", "enum": ["@id" ]}}}, "pav:createdOn": { "type": "object", "properties": { "@type": { "type": "string", "enum": ["xsd:dateTime"]}}}, "pav:createdBy": { "type": "object", "properties": { "@type": { "type": "string", "enum": ["@id"]}}}, "pav:lastUpdatedOn": { "type": "object", "properties": { "@type": { "type": "string", "enum": ["xsd:dateTime"]}}}, "oslc:modifiedBy": { "type": "object", "properties": { "@type": { "type": "string", "enum": ["@id"]}} }, "skos:notation": { "type": "object", "properties": { "@type": { "type": "string", "enum": ["xsd:string"]}}}, "Study Name": { "enum": [ "https://schema.metadatacenter.org/properties/2bf5c18f-df51-4d0c-849f-c4c13608bab5"] } }, "required": [ "xsd", "pav", "schema", "oslc", "schema:isBasedOn", "schema:name", "schema:description", "pav:createdOn", "pav:createdBy", "pav:lastUpdatedOn", "oslc:modifiedBy", "Study Name" ], "additionalProperties": false }, "@id": { "type": [ "string", "null" ], "format": "uri" }, "@type": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" }, "uniqueItems": true }]}, "schema:isBasedOn": { "type": "string", "format": "uri" }, "schema:name": { "type": "string", "minLength": 1 }, "schema:description": { "type": "string"}, "pav:derivedFrom": { "type": "string", "format": "uri" }, "pav:createdOn": { "type": ["string", "null"],"format": "date-time" }, "pav:createdBy": { "type": ["string", "null"],"format": "uri" }, "pav:lastUpdatedOn": { "type": ["string", "null"],"format": "date-time" }, "oslc:modifiedBy": { "type": ["string", "null"],"format": "uri" }, "Study Name": { Study Name Field Specification } }, "required": [ "@context", "@id", "schema:isBasedOn", "schema:name", "schema:description", "pav:createdOn", "pav:createdBy", "pav:lastUpdatedOn", "oslc:modifiedBy", "Study Name" ], "additionalProperties": false, "@type": "https://schema.metadatacenter.org/core/Template", "@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:schemaVersion": "1.6.0", "schema:name": "Study", "schema:description": "Template describing a study", "pav:version": "0.0.1", "bibo:status": "bibo:draft", "schema:identifier": "", "_ui": { "pages": [], "order": ["Study Name"], "propertyLabels": { "Study Name": "Study Name" }, "propertyDescriptions": { "Study Name": "Study Name" } }, "@id": null, "pav:createdOn": null, "pav:createdBy": null, "pav:lastUpdatedOn": null, "oslc:modifiedBy": null }
As with field specifications, the same five groups of fields are present. Since templates do not have individual values to specify there is no _valueConstraints
field. The _ui
field also has additional specifications relating to field order inside the template and other rendering aspects of these fields. See the "Template Rendering Information" section of the CEDAR Template Model.
As can be seen, the specification for the nested field is added to the JSON Schema properties
field. And additional enforcement of JSON-LD mapping of this field to an IRI in the template instance (in this case an auto-generated https://schema.metadatacenter.org/properties/2bf5c18f-df51-4d0c-849f-c4c13608bab5
, though a user-specified property for an ontology is preferable) is also created, which ensures that the conforming instance will generate a complete RDF graph that includes the nested field value.
Again, the top-level fields properties
and @context
contain boilerplate definitions that are common to all template specifications, so if we elide those we get the following:
{ "$schema": "http://json-schema.org/draft-04/schema#" "type": "object", "title": "Study template schema", "description": "Study template schema generated by the MyTool, V3.4.4", "properties": { ..., "Study Name": { Study Name Field Specification } }, "required": [ "@context", "@id", "schema:isBasedOn", "schema:name", "schema:description", "pav:createdOn", "pav:createdBy", "pav:lastUpdatedOn", "oslc:modifiedBy", "Study Name" ], "additionalProperties": false, "@type": "https://schema.metadatacenter.org/core/Template", "@context": { ... }, "schema:schemaVersion": "1.6.0", "schema:name": "Study", "schema:description": "Template describing a study", "pav:version": "0.0.1", "bibo:status": "bibo:draft", "schema:identifier": "", "_ui": { "pages": [], "order": ["Study Name"], "propertyLabels": { "Study Name": "Study Name" }, "propertyDescriptions": { "Study Name": "Study Name" } }, "@id": null, "pav:createdOn": null, "pav:createdBy": null, "pav:lastUpdatedOn": null, "oslc:modifiedBy": null }
Elements follow the exact same structure as templates. In an element, the @type
is defined as https://repo.metadatacenter.org/core/TemplateElement, and the
_ui` field does not have pagination. Otherwise, they are identical.
The https://resource.metadatacenter.org/command/
route can be used to validate templates, elements, and fields. A parameter called resource_type
is used to indicate the artifact type. This value can be template
, element
, or field
to specify one of the three artifact types.
Here is an example curl
invocation to validate a template contained in a file called MyTemplate.json
:
curl -H "Content-Type: application/json" -H "Authorization: apiKey <KEY>" -H "Accept: application/json"
-X POST --data-binary @MyTemplate.json "https://resource.metadatacenter.org/command/validate?resource_type=template"
See CEDAR REST APIs for information on creating an API key to authenticate with CEDAR REST APIs.
Three REST end-points are available to create templates, elements, and fields. The https://resource.metadatacenter.org/templates
route can be used to create templates; elements can be created using the https://resource.metadatacenter.org/elements
route; and fields can be created using the https://resource.metadatacenter.org/fields
route.
Swagger-generated documentation for the CEDAR template REST routes can be found here; element routes here, and field routes here.
For example, assuming we have an instance in a file called MyTemplate.json
, here is an example curl
invocation of the call to create a new template:
curl -H "Content-Type: application/json" -H "Authorization: apiKey <KEY>"
-X POST --data-binary @MyTemplate.json "https://resource.metadatacenter.org/templates"