Skip to content

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.

Creating Fields

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:

titleThis 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".
descriptionThis 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:schemaVersionThis 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:nameThis 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:descriptionThis 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:versionThis 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:statusThis 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:prefLabelThis 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:identifierThis 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.

Creating Templates

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
}

Creating Elements

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.

Validating Templates, Elements and Fields with CEDAR's REST APIs

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.

Uploading Templates, Elements, and Fields with CEDAR's 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"