• Getting Started: CEDAR Workbench Orientation: If you want to understand just a little about the CEDAR Workbench tool before diving in, start here!
• CEDAR Frequently Asked Questions: The most common questions we get about CEDAR and the CEDAR Workbench

We invite your feedback if you would like to see additions or changes to this User's Guide.

Accounts and Logging In

Creating a CEDAR Account

The first step to create metadata templates and metadata with the CEDAR workbench is to create a CEDAR workbench user account. To do this, visit https://cedar.metadatacenter.org and click on the “Register” link below the Password line.

In the next window, enter your first name, last name, a functional email address, and a password as shown in the screenshot below. You should make the first name and last name what you want to appear on your user folder. (If you are creating a second account, be sure to make the first name/last name combination for that account different than it was for your first account, so you can tell them apart in CEDAR.)

After clicking on the REGISTER button, check your email (at the address you provided) for a link to validate your user account. (This should not take very long, a few minutes at most. Check your spam/junk folder if you do not see the mail. You can go back and resend the email from the registration screen, and if that doesn’t work after a few minutes, and you’re sure your email is working, send us an email to get help.)

Click on the link in your email to complete the account creation process. After validation you can easily log in to the CEDAR workbench as indicated in the next section.



---




Logging in with CEDAR

To log in, go to https://cedar.metadatacenter.org, and enter the account name and your password as shown in the screenshot below. If you have forgotten your password, you can use the “Forgot Password?” link just below the Password line. Once you have logged in, you will see the CEDAR Workspace.

In the next section, we provide important information about the visibility of your account, your content, and your user information. Or if you prefer, you may skip to the CEDAR Workspace Desktop and Navigation section, or the Finding Resources section.



---




Visibility of your CEDAR Account

All of the CEDAR account names are visible to other CEDAR users, by navigating to the /All/Users folder. (Only 100 users are loaded at a time; scroll to the bottom of the page to load more names.)

In fact, because sometimes you may want to share or describe the location of your directory, we encourage you to make sure your user name is unique, and if you have two accounts, to give them different user names. If you want to change an existing user name on an account, please contact us at user-support@metadatacenter.org.

If the shared resources include any folders, everything within those folders (recursively) will be shared with the same permissions.

If you share content that you have created in your workspace, anyone who can see your shared resources will also see name of the folder hierarchy within which they live. (They will not be able to navigate into unshared parts of that hierarchy.)

Finally, when you create or update assets, the unique identifier that CEDAR creates for your account is saved in the metadata of the asset. Eventually we may publish a service that provides your account name—and any other profile information you have explicitly shared—to someone who visits the unique identifier. To avoid this, keeping all your work private will prevent anyone from discovering your unique identifier.

---

Finding Resources

Simple Searching

To learn about simple navigation in the Desktop, visit Navigating Within CEDAR.

Searching use the search bar

Searching for a resource in CEDAR is simple if you know text in its title, description, or version. Just input the search string as free text (e.g., “Antibody”) in the Search bar provided in the navigation header of the CEDAR Workbench. All the resources that have the string “Antibody” in their labels, version, or description will be shown.

More advanced search patterns, using wildcards and boolean expressions (with AND, OR, NOT, and parentheses), and searching on fields and their values, are addressed in the following sections.

Narrowing the list of returned resources

You may find there are too many resources available to you in the returned selection. The CEDAR Workbench organizes resources in three different categories, depending on the ownership and sharing: 1) resources created by you, the logged-in user, listed under the “Workspace” tab, 2) resources shared with the logged-in user, and 3) public resources that are shared with every user.

Searching for a resource in a particular set is very simple. Just click on the given set (e.g., “Shared with everybody”) and input the search string as free text in the search bar, as described above. All the resources in the selected set that have the string listed in their labels, version, or description are shown.

You can also constrain the resulting resources by their type, as described in Constraining the Results by Type.

The search results are illustrated in the Figure below. In later sections, we will demonstrate how to organize and constrain these search results, and perform advanced searches.



---




Organizing the Results

You can view the search resources either as a grid of different resource tiles (as shown in the figure below) or as a list of different resources. You can switch between these views using the icon highlighted in the small blue rectangle in the upper right of the figure.

You can also sort the different resources based on their titles, creation dates, and modification dates. To sort the resources, click on the sort icon highlighted in the small red rectangle at upper right, and select from the desired option that pops up. You can also click on the column header to sort by that column.

In the next section, we will discuss how to constrain the search results by filtering on the different resource types.



---




Constraining the Results by Type

When you search for resources (for example, all resources that mention “Antibody”), by default all types of matching resources are shown, including folders, templates, elements, fields, and metadata instances. If you have access to many resources, you may find it hard to navigate these lists of matching resources.

You can constrain the search results by resource type using the type filter. To set a type filter, simply click on the icons indicated in the left side-bar of the CEDAR Workbench, as highlighted in the figure below. These icons are listed as Template, Element, Field, and Metadata, from left to right. You can also display corresponding type represented by the icon by hovering over the icon. When the icon is displayed as a white icon, the resources for the corresponding type are NOT displayed in the search results (for example, Field resources are not shown in the search results in the figure below). To revert back (that is, to show the Field resources), simply click on the corresponding icon again to make its dominant color green.

There is no way to disable the folder resource, as it is used to navigate to lower levels of content.

These settings also apply to any other view of resources in the Workspace window, for example in the user’s home directory. Note the settings persist from one session to the next, as long as the user stays logged in, so subsequent searches will have the same resource type constraints.



---




Advanced Searching - Search Fields

This section contains some examples of the query syntax that can be used to find CEDAR artifacts by field name and/or value.

In this section, the term ‘field name’ refers to the internal name (not displayed label) of fields that are defined for that metadata instance. It does not refer to the metadata attributes for the instance artifact, for example, the assigned Title of the metadata instance. Those artifact metadata fields can not yet be searched individually by CEDAR. (When a search pattern is entered into CEDAR without a prefixed field name, CEDAR will search through the title, description, and version number of the artifact for the entered search pattern.)

Finding metadata instances by field name and/or field value

Suppose the following metadata instance:



Examples of queries that will retrieve the instance above:

• Search by field name and value:

  title:statistics

  publisher:"City of New York"

  "publishing institution":"City of New York" (note that ‘Publishing Institution’ has been defined in the template as the preferred label of the field ‘Publisher’)

• Search by field name (any value):

  publisher:*, or publisher:

• Search by field value (any name):

  *:"New York", or :"New York"

• Boolean queries:

  title:Statistics OR title:Math (the OR is optional—it is the assumed conjunction)

  title:(Statistics OR Math)

  title:Math OR (title:Statistics AND publisher:"New York")

  Dataset OR disease:CRC searches for Dataset anywhere, OR a field ‘disease’ with value ‘CRC’

• Wildcard queries:

  • One or more characters: title:stat*

  • Single character: title:stat?stics

• URLs:

  • url:https://catalog.data.gov/dataset/demographic-statistics-by-zip-code-acfc9

• Ontology terms:

  • Search by term label: topic:statistics

  • Search by term URI: topic:http://edamontology.org/topic_2269

  • Search by term label and URI: topic:http://edamontology.org/topic_2269 AND topic:data

Finding templates, elements, and fields, by field name

Given the template for the previous instance:



Here are some examples of queries that can be used to find the template above:

title:*, or simply title:

Publish*:

"Contact Email": use quotes for multi-word strings

to?ic:

---




Advanced Searching - Patterns

This section describes the more complex search patterns available in CEDAR. You can find examples using these patterns with fields and values in the previous section.

Regular expressions (beyond the ones described below) are not yet available in CEDAR.

Multi-word strings

To search for a literal string that contains spaces (e.g., a multi-word phrase), surround the phrase with double quotes, like this: “Injury Type”.

Boolean queries

Boolean expressions let you combine different search patterns. These expressions include AND, OR, and NOT, and they can be organized with parentheses following algebraic rules.

OR

Use OR to broaden your search results by connecting multiple keywords or phrases. The OR operator is interpreted as “at least one of the search terms is required” for the resource to be returned in the search list.

A space between two words is interpreted as an OR condition.

AND

Use AND to narrow your search: all the search terms that have been combined with AND must be present for the resource to be returned.

NOT

To indicate that a resource should be excluded if a term is present, the term can be preceded by the NOT expression. “Injur NOT Template” will find “Articles about Injuries” but not “Injury Template”.

Parenthetical Expressions

The logical priority of the searches is determined by parentheses. For example, injury AND (health or operation) will find resources with the term injury and either health or operation. The AND operator takes precedence, so without the parentheses, the same search pattern would find resources with both injury and health, or with just operation.

In complex searches, using parentheses to make all your patterns explicit is the best way to be sure you will get what you want in your returned results.

Wildcard queries

You can use special characters to replace a single character, or any number of characters. However, you can only use each special character once in each word.

Replacing multiple characters

You can use an asterisk (*) in your search term to indicate that any number of characters can be substituted in place of the asterisk.

For example: ‘injur*’ will return resources with any of these words: injury, injuries, and injured.

CEDAR treats single-word search patterns as if they have an asterisk at the beginning and end, so ‘injur’ or ‘jur’ will also find the three examples above.

Replacing a single character

The question mark (?) replaces any single character when searching in the resources. injur? will find anything containing the word injury, injured, or injuries.

---

Viewing Resource Information

Viewing Resources Overview

Introduction to the Resources

There are four types of resources in CEDAR: folders, metadata templates, metadata elements, metadata fields, and metadata instances. In this section we will drop the term ‘metadata’ from these names and refer to each resource by its shorter form.

CEDAR folders are used to organize CEDAR content and the sharing settings for that content. To view folder resources you navigate into the folders. This is described in Navigating Within CEDAR, under Browsing Within the Desktop.

The rest of this section emphasizes CEDAR artifacts: templates, elements, fields, and instances. The section summarizes the more detailed content found in subsequent sections.

Viewing Resource Content

We use the phrase ‘viewing resource content’ to mean looking at the resource in human-friendly form, either in the CEDAR application or on the web using OpenView.

Natively in CEDAR

To open an artifact for viewing in CEDAR that is listed in the Desktop view, either double-click on the artifact, or select the artifact and use the resource menu (⋮) to select Open. Both techniques work whether you are in search or browse mode.

You will be shown a viewing window that lets you navigate throughout the artifact, open and close sections of metadata instances, and if you have write permission, make changes to the document.

This is also the view which enables seeing the raw artifact content inside CEDAR.

For more details about this viewing mode, visit Viewing Resource Content.

On the Web with OpenView

If you click on the resource menu (⋮) and find the OpenView section, you will be able to see whether OpenView is enabled for this artifact. (The View in OpenView command must be selectable.)

By selecting View in OpenView, you will be directed in a new browser tab to the web page for this artifact that supports navigation and viewing features. (Modifications are not available in OpenView mode.)

You can also see artifact metadata and raw artifact content from the OpenView format.

For more details about this viewing mode, visit Viewing Resource Content on the Web.

Viewing Resources in Raw Formats

All three CEDAR templating artifacts—templates, elements, and fields—are maintained as JSON Schema documents, an ASCII format following the JSON specification. CEDAR metadata instances are maintained in JSON-LD (for JSON-Linked Data), which also follows the JSON specification. JSON-LD is expressly designed for interoperability with RDF, so the CEDAR metadata instances can be expressed as JSON-LD or RDF.

Whichever format applies, the information is accessible at the bottom of the artifact’s view in CEDAR by clicking on the appropriate link. (Raw formats can also be accessed via the web when OpenView is enabled for the artifact.)

For more details about this viewing mode, visit Viewing Resource as Raw JSON.

Viewing Resource Metadata

Within CEDAR, metadata for an artifact or a folder is viewed from the Desktop. Once a resource is selected, if the metadata panel is not visible on the right side of the Desktop, click on the ‘i’ information icon to open it.

Another metadata panel is available from the top part of the OpenView format, with a different metadata collection appropriate to OpenView users.

For more details about viewing resource , visit Viewing Resource Metadata.

---




Viewing Resource Content in CEDAR

We use the phrase ‘viewing resource content’ to mean looking at the resource in human-friendly form, in this case within the CEDAR application.

When you want to open an artifact for viewing that is listed in the Desktop view, either double-click on the artifact, or select the artifact and use the resource menu (⋮) to select Open. Both techniques work whether you are in search or browse mode.

The artifact will open in the appropriate editor for that artifact. This is the Template Designer for templating artifacts—templates, elements, and fields—and the Metadata Editor for metadata instances.

In either case, the editor is opening a modal window, and no other CEDAR tools are accessible until the window is dismissed. The artifact is saved only when you click the Save button; it will not be saved if the browser window is closed or a back button is pressed, although a warning is issued.

All Artifact Editors

When the artifact opens, you will see a formatted view of its content. You can navigate throughout the artifact, in some cases open and close sections of the document, and if you have write permission, make changes to the document.

Artifact Headers

At the top of the view, you will see the name of the artifact, an identifier field, and the artifact description. All three fields can be modified by a user with write permission on the artifact.

To the left of the artifact name is a left arrow. If you click on this left arrow, CEDAR will return to the previous folder view. (If the current document is modified but not saved, you will be warned and given a chance to save your work.)

To the right of the left arrow is an artifact type icon, showing the kind of artifact being modified. The following images show the artifact type icons for templates and instances.

In the upper right of each editor is an artifact status display, shown to the right. The artifact display shows white icons to reflect normal status, and yellow icons if there is an issue. The left-most icon indicates whether the artifact has been modified without saving. The center icon indicates whether the document can be edited, showing a locked icon if it can not be edited. (This can happen if you do not have permission to edit the document, or if the document is a published version, which means no one can edit it.) The right icon shows whether the document validates. (The document should always validate if the system correctly implements the template model specifications.)

Artifact Footers

At the foot of every artifact one or two horizontal bars let you view the raw format of the artifact. See Viewing Resource as Raw JSON for more information.

Template Designer View

For templating artifacts, the Template Designer will show the elements and fields of the template, with visual indentation to show the organization of the elements within the template.



There is also an identifier field, which can be used to provide an external identifier for the template. (This is not the same as the artifact’s identifier, which is always a CEDAR-generated IRI.) The external identifier does not have to be an IRI, and does not have to be unique across different artifacts, though both are highly recommended.

More information about using the Template Designer can be found in the CEDAR Templates chapter, starting with Description of a Template.

Metadata Editor View

For metadata instances, the Metadata Editor will show the metadata as a form to be filled out, again with visual indentation to show the organization of the elements within the form.



If there is an arrow to the left of a given line, clicking on the arrow will expand or collapse the content under that entity.

Information about using the Metadata Editor can be found in the Filling Out (Creating) Metadata chapter, starting with Filling Out Metadata.

---




Viewing Resource Content on the Web

We use the phrase ‘viewing resource content’ to mean looking at the resource in human-friendly form, in this case viewing it on the web using CEDAR OpenView.

OpenView is a CEDAR feature that allows you to publish CEDAR artifacts to the web, where anyone with the IRI can view them. The details of this process are described in Sharing Via the Web. Under the heading Viewing the Shared Content on the Web, that page also describes how to access an OpenView page, what content is visible on the page, and how to view additional hidden information.

An added feature of the web-based view of instance artifacts is that you can view not just the raw JSON-LD or RDF for the instance, but also the JSON Schema for that instance. Simply click on the appropriate viewing link at the bottom of the form on the web.

Another feature of the web view is that the artifact’s metadata are customized for public viewing. For example, in the screenshot below of a demonstration template in CEDAR OpenView, you can see the links to visit the template in CEDAR, and to fill it out in CEDAR.



---




Viewing Resource as Raw JSON

As noted in the Viewing Resources Overview, all CEDAR artifacts are maintained internally in JSON.

The three CEDAR templating artifacts—templates, elements, and fields—are maintained as JSON Schema documents, an ASCII format following the JSON specification. (They are validated using a higher-level JSON Schema specification.)

CEDAR metadata instances are maintained in JSON-LD (for JSON-Linked Data), which also follows the JSON specification. JSON-LD is expressly designed for interoperability with RDF, so the CEDAR metadata instances can be expressed as JSON-LD or RDF. The JSON-LD instances are validated using the JSON Schema of the CEDAR templates.

Whichever format applies to your artifact, you can access the artifact in that format using links in horizontal bars at the bottom of the artifact when it is being viewed. For metadata instances, you can also see the metadata in RDF form using similar links.

Raw formats can also be accessed via the web when OpenView is enabled for the artifact. When visiting an OpenView page, scroll the page to the bottom to find the JSON-LD and RDF viewing links. On the OpenView page for metadata instances you can also find a link to the JSON Schema for the template under which the instance was produced.

---




Viewing Resource Metadata

There are 3 ways you can view metadata about a CEDAR resource: within your CEDAR Workspace view; in the OpenView of any artifact that has OpenView enabled; and by looking at the content. Each of these is described below.

As a reminder, the term ‘resource’ refers to any CEDAR artifact or folder; while ‘artifact’ refers only to templating resources (templates, elements, and fields) and metadata instances.

In the CEDAR Workspace

By selecting any resource in the main file viewing window in your CEDAR Workspace (see diagram below), you can view an information panel to the right side of the display with metadata for that resource. Click on the ‘i’ icon (shown as item L in the diagram) to make the metadata panel visible if it is not already visible.

If no resource is selected, the ‘i’ icon presents metadata about the folder (B) shown in the Resources box. The right-hand smaller image below shows the information panel for one of these artifacts.

The information panel displays 3 types of metadata in the corresponding tabs: metadata about the resource’s general characteristics; metadata about an artifact’s version history (for templating resources only, not instances); and metadata about the categories into which the resource has been classified (artifacts only, not folders).

In the main window, most of the metadata is self-explanatory, but there are two features of special interest. The Description field is the same content as the description at the top of the artifact when it is open, and this field is editable in the information panel. Also, for metadata templates the panel shows all the metadata instances that are visible to you; clicking on any of the instances in the list will open it. The count at the top of that metadata instances sub-panel is the count of instances you can see, and the total count of instances.



Metadata in an artifact's OpenView

If an artifact has OpenView enabled, you can navigate to the OpenView either with the direct IRI (if you have it), or by navigating to the artifact in CEDAR (if you have access to that) and clicking on the Visit in OpenView resource menu item.

In either case, the top line of the artifact in OpenView has a metadata block with the title in the middle. By clicking on this metadata block, you will unfold a metadata view, as shown in Viewing Resource Content on the Web

Metadata in the raw artifact views

By looking in any raw artifact view, you can see the metadata that CEDAR maintains as part of that artifact.

To understand the metadata in more detail, you will need to understand the CEDAR Template Model, as described in the Description of a Template.

---

Desktop and Navigation

Managing CEDAR Resources

Introduction

This section describes how to manage CEDAR resources. In CEDAR, resources include the various artifact types (templates, elements, fields, metadata instances) and folders. These are all managed through the CEDAR Desktop, typically through your workspace view. Management operations include copying, moving, renaming, and deleting resources, and setting sharing permissions on resources.

If you want to fill out metadata for a particular template, the Populate command will open the Metadata Creator set up to fill in metadata for that template. If you want to edit an artifact (including a populated metadata instance), the Open command will open the appopriate tool (Template Editor for templates, elements, and fields; and Metadata Creator for metadata instances) with that resource. For a folder, the Open command changes the Resources box view to show the selected folder.

Other artifact-related commands like Publish/Create version, Submit, and Enable/Disable/View OpenView are addressed in their respective sections of the User Guide.

Resource Menu

All the resource options are managed through the menu of the resource (shown below). Access the resource menu by clicking on the vertical dots (the ‘kebab menu’, ⋮) on the right side of the resource. A drop-down menu provides access to the options for moving, copying, renaming, deleting, and sharing the resource. If a menu item like Copy… is grayed out, it is not available for that resource. If all menu items are grayed out, either no resource is selected, or there is a permissions inconsistency.

Destination Commands and Selection Window

The Copy to… and Move to… commands will display a window for you to choose the destination for the command, shown here. The starting location is your current workspace folder. To navigate in this window, click on the left arrow to move up in the folder hierarchy, click on the right arrow for a folder to move into that folder, and click on the Home icon at upper left go to to your workspace (home folder).

If you try to navigate to a folder to which you do not have needed permissions, an error message will be displayed.

There is always a destination folder selected. If no folder is highlighted in the window, the destination folder is the currently displayed folder. If a folder is highlighted in the window, the highlighted folder is the target folder that will be used.



Copy to… Command

After selecting the Copy… command, you will be asked to select the destination folder, and can then complete the operation by clicking on COPY.

his operation requires read permission for the resource. You can copy any CEDAR artifact to another directory for which you have write permissions. However, you can not copy an entire CEDAR folder with a single command.

Move to… Command

After selecting the Move… command, you will be asked to select the destination folder, and can then complete the operation by clicking on MOVE.

his operation requires write permission for the resource. You can move any CEDAR artifact or folder to another directory for which you have write permissions.

Rename Command

After selecting the Rename… command, you will be asked for the new name. This operation requires write permission for the resource.

Share… Command

The Share… command opens a sharing configuration window.

In this window you can perform all sharing and group management operations needed to control resource access in CEDAR. See the Sharing Your Content section for detailed information about sharing resources in CEDAR.

Delete Command

The delete command displays a confirmation box, then deletes the item.

Use this command with caution, as there is no undo command. Contact the CEDAR team to restore content you have deleted.



---




Navigating Within CEDAR

Introduction

Navigating around CEDAR is pretty easy, but it helps to understand a few basics.

CEDAR (the “CEDAR Workbench”) has 3 tools:

• the Desktop (which includes your workspace),
• the Template Editor, and
• the Metadata Creator.

The Components

For managing CEDAR content you’ll use the Desktop, which can either display a Workspace, or search results. (More on search results below.)

When you want to create a template, element, or field, you will use the Template Editor. This is a form-building tool that lets you drag-and-drop form components.

To fill out a form, you’ll use the Metadata Creator, which lets you edit and save metadata, and view it in JSON-LD or RDF.

Browsing in the Desktop

When the location bar is shown at the top of the Resources box, you can click on any of the highlighted components of the location to go to that folder.

In any Desktop view, if you want to navigate into any of the folders that are listed, double-click on the folder. (You can also use the resource menu (⋮) and click on Open.) This works in either search or browse mode to display the contents of folder in the Desktop.

Note that when My Workspace is the selected viewing mode (see Your CEDAR Workspace for more details on viewing modes), you only see resources at the current folder level. In either of the Shared views you will see all the folders and artifacts that explicitly satisfy the chosen criteria.

Moving Back and Forth

From the Desktop, you’ll move to one of the other tools by opening an artifact or populating metadata for a template. Once in the Template Editor or Metadata Creator, you can’t perform any Desktop functions. The only way back to the Desktop is via the CEDAR back button in the upper left of the template or metadata instance. Think of these tools as ‘modal overlays’ on the Desktop view—they replace the Desktop view until they stop.

The Desktop can also move into a search mode, either by entering a search string in the search bar, or by selecting the Shared with Me or Shared with Everybody search links from the left side. In these modes, the current location is not shown above the Resources box, but is replaced by a string indicating what information is being shown. To return to the Desktop from one of these search modes, you can click on the Workspace link at upper left.

Key Tip: If you open another tool (by opening an artifact) from the search mode of the Desktop, clicking on the left arrow in the CEDAR window will return you to your last Desktop location, not to the search interface (with the previous results in it). To return to your previous results in the search interface, click on the browser back button.

Navigating Long Screens

When searches or folders contain a lot of content, CEDAR uses paging to quickly display the first set of results (usually 100 results). In this case, if you search for content via the browser, you may not see it if it has not been paged into view. You can see from the Displaying i of j message at the bottom of the screen whether more results are available.

To display more results, scroll the list by using the faint scroll bar on the right of the list, or using your computer’s ‘swipe’ gesture to move the list upward. You may have to repeat this gesture several times to see all the content. You’ll know all the content is displayed when the final message reads Displaying j of j.

---




Your CEDAR Workspace

After you first log in to CEDAR, you will be in your own workspace, which will look something like the first annotated screenshot below. (Your workspace will not include any of the resources in the middle of this diagram.) The two smaller screenshots that follow present slightly different views of the CEDAR workspace.

We will walk you through the content of this screenshot using the letters in the yellow circles.

• (A) The search bar lets you find other CEDAR resources.
• (B) The location string tells you the local folder for this display. (If it is not present, you are in a search display, and can click on Workspace (C) to return to this folder view. You can navigate to higher level folders by clicking on them in the location string.
• (C) These 3 options on the left of the window control which kind of resources you will see. The Workspace view shows your home directory. The Shared With Me view shows content that has been explicitly shared with you, or a team you are on. The Shared with Everybody view shows content that has been shared with everyone on CEDAR.
• (D) To start creating your own content—templates, elements, fields, and folders—you will click on the New+ button and select what you want to create. (If you want to create a metadata instance, you must find the template that you want your metadata to follow.)
• (E) The large white Resources box lists the resources you can view. Controls (A), (B), (C), (H), and (I) affect what content you see in this box. You can sort the items in this box by clicking on the header of each column, or by clicking on the sort icon (M).
• (F) Each resource in the Resources box has its own menu dropdown, selected by these vertical triple-dots at the right of the resource. With this menu you can rename, copy, move, share, and perform many other functions with the item.
• (G) Any template can create a form for you to fill in metadata that follows that template. Click on this metadata tag to enter the Metadata Creator and start filling out metadata following that template.
• (H) These round icons on the left side of the window filter what kind of content you can see. If the icon is green (with white figures), it is highlighted and you can see the corresponding content. If the icon is white (with green figures), that content type is disabled. (Folders are always visible.)
• (I) The Version selector dropdown menu lets you control whether you see only the latest published version of a template (including a draft version if it exists), or all versions. The default lets you see only the latest published version (and any draft) of a template.
• (J) The number of items listed in the Resources box is shown here. If the number of items is larger, only a subset are shown. Scroll the display up to see more items.
• (K) In this location is an icon to let you switch your Resources box to cards or list format. The cards format is shown in the left-hand smaller image.
• (L) The ‘i’ icon will bring up an information panel to the right side of your display, providing additional information (metadata) about the selected resource. If no resource is selected, the ‘i’ icon presents metadata about the folder (B) shown in the Resources box. The right-hand smaller image below shows the information panel for one of these artifacts.
• (M) The sort icon lets you choose the sort criteria for the Resource box contents.
• (N) The bell icon indicates whether you have any messages from CEDAR. A white icon indicates no messages.
• (O) The profile icon lets you see information about your CEDAR profile, including your API key, and offers features like ‘Support’ and ‘Logout’.



The left-hand image below shows the cards-based view of the Resources box. The right-hand image below shows the informational panel with metadata displayed for the highlighted resource.



---

Filling Out (Creating) Metadata

Creating the Metadata Form (Instance) for Filling

CEDAR’s Metadata Instance

In CEDAR, the forms to fill out with metadata are created as what we call metadata forms, or to avoid confusion with templates, Metadata Instances or Instances. The instances contain provided answers for each of the fields, and if the answers are unique identifiers for controlled terms, the instances also contain the labels so that tools can display the values without performing a lookup. When instances allow multiple entries for a field or element, entered values are stored in arrays. CEDAR stores all of this information in JSON-LD-formatted documents

CEDAR instances contain contextual metadata describing the instance, just as templates contain contextual metadata for template artifacts. One of those contextual fields specifies the CEDAR Metadata Template (and its version) from which the instance was created.

CEDAR instances do not contain detailed descriptions of the questions being asked, nor details about the possible answers for those questions. Anyone who wants this information can use the identifier of the instance’s source template to get a copy of the instance and look up those values.

Creating the Instance

CEDAR offers several strategies for initiating a metadata form. These are described below according to the needs they satisfy, and ordered from simplest to most complex.

From a Workspace view of the template

This is the most common way to create an instance. If the workspace doesn’t have a view of the template, navigate in the workspace or perform a search to bring the template into view in the List or Cards workspace view.

There are two variants to create a new metadata instance from the Workspace view: either click on the metadata tag to the right side of the template box (Item 1), or click on the dropdown menu (Item 2a, the kebab, :) and select Populate Template (Item 2b).



Via a Web Link (An External IRI)

In this scenario, the template creator has obtained a web link (an IRI) that, when entered into a browser or included clicked on as a link in a web page, will create a metadata instance for that template. (To create such a link for a template, see Building Shareable Metadata Creation IRIs.

For example, clicking on the following link will start the process of creating an instance to be filled out for the Adaptive Immune Receptor Repertoire community’s minimum information model (MiAIRR). The string after ‘templates/’ is the UUID for the MiAIRR template.

https://cedar.metadatacenter.org/instances/create/https://repo.metadatacenter.org/templates/ea716306-5263-4f7a-9155-b7958f566933

A logged-in user will proceed directly to the Metadata Editor with the newly created instance already opened.

If the user activating the link does not have a CEDAR account or is not logged in, CEDAR will redirect the person’s browser to the CEDAR authentication page. At that point the user can log in or register for an account, and will be returned to the Metadata Editor with the newly created instance already opened.

Below is the Metadata Editor opened to the MiAIRR instance requested by the link above.

From an existing instance made from that template

If you will be creating a number of metadata instances with many of the fields populated exactly the same, you can create a instance profile with those fields pre-populated. For example, if your template is called Study Object, you can populate it as an instance profile called “MyLab Study Object Metadata name date”, pre-filling it with all the values that will be the same for every instance.

Before starting to create individual instances, make the instance read-only so that it is not accidentally overwritten. Make sure all the people who will be filling out a copy of it have read permission on the object or its enclosing folder. (You may also wish to add a dedicated folder for all the saved instances, with a title like “MyLab Study Object Completed Metadata”.)

When you or any other user wants to create a new metadata instance, make a copy of the instance profile and replace ‘name’ and ‘date’ in the title with the name of the author and the date of this copy (or a short instance sequence number), or any other appropriate unique labeling. (Note that the intended location to receive the filled-out instances must be writable by all the people who are creating metadata.) See Sharing Your Content for more information on creating writable folders.

The copied instance will have all the information that was in the instance profile, and can be filled out and saved normally.

From an API call to CEDAR

The Template Instance API can be used to create or update an instance:

• PUT of an existing metadata instance
• POST of a new metadata instance

Each requires inclusion of the JSON content to use for that instance.

To copy an existing instance, you would have to first download the instance using a GET, then upload your copy to a new instance (using the POST as above).

---




Filling Out Metadata

Basic Steps

When the metadata instance opens, you can click in any field to start adding metadata.

To move to the next field, you can hit return (once or twice depending on the field type). In a few cases you may have to click in the next field.

In some cases (see the image below), the metadata instance may show elements as an outline, with their content hidden. To view and fill out metadata fields within those elements, click on the element header to show the element’s contents.



Your metadata is not saved until you hit the SAVE button, visible in the image above. You may have to scroll to the end of a long template to see the Save button in the lower right corner. We recommend you save your metadata often, so that little is lost if your browser window is accidentally closed. See Saving and Validating for more details.

Viewing JSON-LD and RDF

You can see the JSON-LD and RDF versions of your metadata by clicking on the appropriate controls at the bottom of your metadata instance. For more information see Viewing Resource as Raw JSON.

Multiple Fields

Most of the field types can be enabled as “multiple” fields by the template creator. If a field is set to multiple, you will see controls that let you add additional values. Internally multiple fields are represented as an array of values.

From any field, you can click on the Copy icon (pointed to by black tip) to create another instance of the field. This instance makes a copy of the field value that was in view when the Copy icon was selected, and inserts that value after the original field.

In our case, this results in a second field (third image), into which you can put the desired value for that field.

The numbers shown in the right-hand multiple fields controls are part of the array navigation controller, which lets the user navigate to any particular field item in the array of fields.

In many cases the field values can be viewed and edited in an array using “spreadsheet view”, by clicking on the Format icon (which shows a 3-item bullet list in its regular view). This results in the display to the right.

If you click on the format icon again (now shown as two opposed arrows), you will return to the list view. Any changes made in one viewing mode will be reflected in the other.

Multiple Elements

CEDAR elements can also be enabled as “multiple” entry items, allowing users to fill out a set of metadata multiple times. A CEDAR element that is enabled for multiple entries looks like the following (note the controls on the right side of the Element header):

The process of filling out multiple elements is the same as described for fields above, with one exception. The format control that enables filling out arrays (“spreadsheet view”) is only visible if the element just contains simple fields. If the element contains other elements or fields that allow MULTIPLE entries, viewing and editing it as an array is not possible. See the Spreadsheet-compatible Elements subsection of Adding Elements to learn how to set up this feature.

CEDAR’s spreadsheet view of arrays automatically performs validation and auto-completion of controlled term lists, and supports cutting and pasting of sub-tables of information anywhere in the spreadsheet.

You can copy and paste from an Excel, Numbers, or Google spreadsheet into the spreadsheet view in CEDAR.

Note that while CEDAR does not support the import of spreadsheet data or direct ingestion of CSV-formatted values, such data could be transformed from its CSV-based form into an array structure within the CEDAR Instance (following the required syntax of an appropriately structured Template), then imported into CEDAR.

Advanced Tips for Fields

For certain types of metadata, some tips may be useful.

Multiple free-text fields

If you are entering multiple free-text fields, these are stored as values in an array. The user interface presents all the entries at once, separated by commas.

To see the exact contents of each field, click on the field to enable editing, which brings up the array navigation controller.

Drop-down fields

Drop-down fields indicate a set of terms, which are often controlled terms from one or more ontologies. In many cases, there are hundred, thousands, or even hundreds of thousands of controlled terms for a field.

The drop-down menu can not display all these terms, so it presents examples from throughout the list of possible terms. To see only those terms that might be relevant, you must begin entering the appropriate term (or some string from within it).

Immediately (within a second or two after you stop typing), you will see a list of term labels that contain the string you’ve entered. (See example at right.) You can either pick the term you want by clicking on it, or return to the field to continue entering a search string.

Note that synonyms are not considered when looking for matches, so it may help to know whether the vocabulary contains, for example, ‘human’ or ‘homo sapiens’ as the label for humans.

Field suggestions

In some cases a field may be enabled for Suggestions. In this case, you may see some entries that appear (out of alphabetic order) at the top of the list, with numbers in the range 50-100. These fields are suggestions, and the numbers represent the strength of the suggestion. (To be explicit, the numbers are not the likelihood of the particular value.) To choose a suggested item, simply click on it.

The suggestions are based on an intelligent authoring algorithm in CEDAR that considers previously entered metadata for the given template, and creates rules based on frequently occurring patterns in that metadata. If there are any patterns in your entered metadata that suggest what answers may be appropriate in the current field, CEDAR will make the most likely answers visible to you as the suggested values we describe here (and show below).

More details about the suggestion system in CEDAR may be found at Understanding the Suggestion System.

Attribute-value fields

Some forms give users the ability to add their own attributes, for example, to add metadata about certain attributes that are not in the form. An attribute-value field looks like the following:

In an attribute-value field, you get to enter both the name of the field, the corresponding value, which is always free text. Often any number of attribute-value fields may be added, but the template creator may limit the maximum number for a given form.

---




Saving and Validating

Saving

To save the instance, click on the Save button at the bottom right of the instance.



While an instance is being edited in the Metadata Editor, it can be saved at any time. If you have made changes and try to leave the instance without saving it, CEDAR will issue a warning. If you click Continue, any changes you made will be lost. Choosing Go Back will return you to the instance, where you can save it.

Because there is no undo, should you need to recover a previous version of the document, you can contact CEDAR staff to restore a version from before the time you started editing. If you plan to make significant changes to a template, especially if you are experimenting with it, we recommend saving a copy before you start changing it.

At the top right of the instance, there are 3 icons that indicate the instance status. The left-most icon (the circle) is filled when the instance is saved, but is a hollow yellow circle when there are unsaved changes.

If the lock is yellow and locked, you will not be able to save your changes, even to a separate file.

Validation

CEDAR is always performing syntactical validation of an edited instance against the template. This checks that the schema conforms to the corresponding schema, which should always be true and yields a white checkmark in the third icon. If the syntactical instance validation fails, there is a problem in the CEDAR system, and the checkmark turns yellow. You may be able to work with the instance, but it is best to contact the CEDAR team to alert them to the problem.

Whenever CEDAR saves an instance with entered content, it attempts to verify the metadata content of the instance satisfies the instructions in the JSON Schema specified by the template. This detects issues with missing fields and malformed fields (e.g., a link field that contains data that is not a link).

On a successful metadata content verification, CEDAR issues a green “Instance saved successfully” notification. If the verification fails due required fields being missing, CEDAR issues a report listing the missing fields. If the verification fails due to a more fundamental error, CEDAR issues a red “Instance not saved” message, along with basic error messages.

In some cases—for example, MiAIRR submissions— CEDAR may even run an external validator on the metadata produced by CEDAR. If this validation fails, CEDAR presents a more detailed error report offering the report from the external validator.

---




Special Case—Submitting Your Metadata

In some cases, it may be possible to submit your data to external repositories using the CEDAR system. The first major instances of this capability are the pipelines for submitting to repositories at the National Center for Biotechnology Information (NCBI), in particular the BioProject, BioSample, and SRA repositories.

Assessing Instance for Submission

To determine if a CEDAR metadata instance can be submitted to an external repository, click on the ‘kebob’ menu (the vertical dots) for that metadata instance. If the menu list shows the Submit menu is enabled (as in the image below), the artifact is capable of being submitted externally.



When you click on the Submit menu, CEDAR will displays a dialog box (shown below) with a list of the repositories to which these metadata can be submitted.



CEDAR Submission Workflows

The submission workflows described above are documented externally in some detail.

CAIRR Pipeline for the MiAIRR Standard

This pipeline accepts metadata for NCBI’s BioProject, BioSample, and SRA repositories in a single template, and distributes the metadata and associated data to the three repositories. It is described in an overview of the CEDAR AIRR (CAIRR) pipeline. Detailed instructions are found in the MiAIRR Submission Manual.

You can read more about this pipeline in the article The CAIRR Pipeline for Submitting Standards-Compliant B and T Cell Receptor Repertoire Sequencing Studies to the National Center for Biotechnology Information Repositories.

CEDAR Pipeline for Human Tissue

The CEDAR-to-NCBI Human data submission pipeline provides an interface to transmit SRA datasets to the NCBI SRA and BioSample repositories from the CEDAR Workbench following the BioSample Human package v1.0. It is described with detailed instructions in this overview of the CEDAR-to-NCBI Human data submission pipeline.

Other Submission Techniques

In other CEDAR integrations, submission to remote repositories is accomplished when the remote repository pulls data from CEDAR. If you are filling out metadata that is destined for a remote repository using this method, you could receive special instructions regarding which template to use and how to indicate when your metadata is ready for ingest by the remote repository.

Further information about these and other CEDAR submission pipelines can be found on the CEDAR GitHub pipelines wiki.

---

Sharing Your Content

Creating Groups

What Are Groups?

CEDAR lets you to define groups of people who can share access privileges for particular content. For example, if you want members of your team to see all of the metadata generated by your team, you could put it all in a folder and share the folder’s permissions with a group containing your team members. Or, you could use a group to make metadata visible to a team of curators when it was ready for review.

Any time you want a set of people to share equal access (read or write!) to CEDAR content, you can use a group.

Using Groups: Share with Everybody

Let’s say you have created an element and you want to let everyone in CEDAR use it. Good news! There’s a group in CEDAR called Everyone, and if you share your content for reading with that group, every CEDAR user can find it and view it.

To begin, open the sharing menu as described in Sharing for Reading and Writing.

Now, start typing in the name of the Everybody group. As you can see, several groups may be shown, and you can select the one you want.

After you’ve selected the Everyone group, you can enter the type of sharing (as described in Sharing for Reading and Writing). We highly recommend leaving this ‘can read’, the default!

To complete the process, you must click on the OK button.

Now you should see the group displayed in the right-hand panel, showing the assigned permission.

If you had wanted to share your artifact with the CEDAR Dev Team so they can all see it, you could choose that group after typing the ‘Ev’ above!

Creating Groups

What if you don’t have a group yet, but want one? Instead of entering an existing group name, enter your new group name in the box labeled ‘enter new group name’. Here we’ve entered ABCD Lab Team for the group name.



As soon as you hit return, the group is created, and you can give it read (or write) access permissions by clicking on the OK button.



Modifying Groups

Presumably you want to add people to your group. To do this, click on the blue Group settings link (pointed to by the green arrow in the screenshot below).



This brings up a window in which you have to re-select the group you want to modify.



Enter the group you want to make changes to, and when you choose the group name, the people in the group will be displayed.

To add someone to the group, start entering their name in the Add people box, select their name from the drop-down list, and click on OK. (To remove someone, click on the X by their name.)

To see more information about the group, click on the Detailed info link under the box on the right side. This will bring up detailed information about the group, some of which you can edit.

Group Administration

You can make multiple people administrators of the group, by checking the appropriate box next to each person’s name in the People list.

---




How Permissions Work

Introduction

You may have some questions about CEDAR’s access privileges, like these:

1. How can I keep my files private (or make them public)?
2. How can someone collaborate with me on a lot of different files?
3. Why can’t I save this metadata where the template is?
4. How can I tell whether other people can see my file?
5. I just logged in for the first time, why can’t see some of the shared files?

In this tutorial we’ll talk about how CEDAR permissions work, and help you answer questions like these.

(You can see answers to the questions at the end of this page.)

Permission types

You want to access individual resources in CEDAR, or keep someone else from accessing them. So what you need to know, for a given node, is whether a particular user:

• can read,
• can write,
• can publish,
• can create a draft version of,
• can change the permissions (sharing) of, or
• can change the owner of the node.

The operations above are evaluated on-the-fly in CEDAR. They are not attached to nodes in the system, but are computed from different graph relationships (like folder hierarchies) and properties when they are needed.

A basic concept that may help you interpret CEDAR permissions is that you only need one permission on a resource to perform that operation.

Permission rules

For simplicity, we refer to the object in each question as a resource (templates, elements, fields, and metadata instances are all resources), but this section also applies to folders.

We should not that for practical reasons, the administrator of the CEDAR system has permission to do all of the actions represented by the 6 permission types above.

Now let’s start with a few easy-to-answer questions.

Who can change the owner of a resource?

Only the owner of a resource can change the owner of a resource. Each resource has only one owner.

Who can change a resource’s permissions?

The resource’s permissions are changed via the Share menu for the resource.

To change a resource’s permissions, the following must be true:

• The user has write access to the resource. (This means they can update the resource. And who can do that? See below.)

Who can read a resource?

For a user to be able to read a resource, at least one of the following must be true:

• The user owns the resource, or a folder that contains the resource
• The user, or any group of which the user is a member, can read or write the resource or any folder containing it (except the root folder ‘/’ and users folder ‘/Users’).

For example, because any user can read the ‘/Shared’ folder, any user can also read any content at any level under the ‘/Shared’ folder. (Unfortunately, this means we can’t give users write permission in this folder, because then they can overwrite any other shared content. We’ll create an exception rule to handle this soon.)

Who can update a resource?

These rules are similar to reading. For a user to be able to update a resource, at least one of the following must be true:

• The user owns the resource, or a folder that contains the resource
• The user, or any group of which the user is a member, can write the resource or any folder containing it

The creation rules are just like the updating rules, except simpler, since the user can’t own or write a resource that doesn’t exist. (To create a resource, use the ‘New +’ icon at the upper left of your workspace.) So one of the following must be true:

• The user must own any containing folder (that is, any single folder higher in the hierarchy than the new resource).
• The user must be able to write any containing folder (that is, any single folder higher in the hierarchy than the new resource). Note that no user can write or create resources directly in the ‘/’, ‘/Users’, or ‘/Shared’ folder.

Copying a folder or resource into a target folder, or moving a resource into a target folder, requires the same permission as creating a resource in the target folder.

Who can create a draft version of a published resource?

A draft version of a resource is a resource that can be overwritten, by editing and saving it. All resources in CEDAR start out as a draft, and must be explicitly published (see next item) before this question applies.

For a user to create a draft from a published resource, the following must be true:

• The user owns the published resource that serves as the original content for the draft.
• The resource is a type that supports versioning (field, element or template).
• The resource is the most recently published in the version history of this resource

The last rule means you can not create a draft from some earlier published version of the resource.

Who can publish a resource?

Publishing a resource is like ‘releasing’ source code or defining a version of a document: a published resource can never be modified. The only types of resource that can be published are templates, elements, and fields, and they must start out in draft state. (The act of publication replaces the ‘draft’ version.)

For a user to publish a resource, the following must all be true:

• The user owns the resource that is to be published.
• The resource is in draft state (all resources start in draft state, and if a draft exists, it is always the most recent resource in a version history)
• The resource is of a versioned type (field, element or template).

Answers

Now we can answer our original questions.

1. How can I keep my files private (or make them public)? Your resources will stay private if they are in your own CEDAR user folder, and you have not shared any of their parent folders with anyone else.

To make your files public, simply share them, or one of their parent folders, with the individuals or groups who should get access. The ‘everybody’ group can be used to share the content with all CEDAR users.

1. How can someone collaborate with me on a lot of different files? Just share the folder containing all of your collaborative files with them. Sharing write privileges on the folder will let them modify all the contained files. (If you want to have a shared folder for your project under /Users/Shared/, just ask us to create it for you. Be aware the contents are readable by all CEDAR users.)

2. Why can’t I save this metadata where the template is? Often templates are in a read-only folder, so that the template can not be changed. CEDAR will automatically save created metadata to your home folder, and then you can move it to any other folder that for which you have write permissions.

3. How can I tell which other people can see my file? Unfortunately there is no simple way to evaluate this, without examining the sharing permissions on the resource, and on every folder above it.

4. I just logged in for the first time, why can’t I see some of the shared files? All CEDAR permissions must be materialized in Elasticsearch, in order to be used directly for search queries. When you first log in, your materializations must be created, which can take some time. In a similar way, a change in the permission of any given node is not propagated instantly into the Elasticsearch index. Depending on the size of the affected subtree (if the node is a folder), materializing this permission can take several seconds.

---




Sharing for Reading and Writing

What it Means

There are two types of sharing: for reading, and for writing. If you allow someone to read your content, they can see it, but they can’t change it. That includes changing the metadata, or its sharing settings, or even removing it—they can’t do it.

If you share something for writing, then the people (or groups) with whom you’ve shared it can make all sorts of changes, including changing its content, its sharing permissions, and even deleting it.

If you share a folder for reading or writing, then the permissions you share apply to everything in that folder, and everything in any folders within that folder. So be sure you want everyone to be able to read, or write, all the folder’s content before doing that!

How to Share

It is simple to enable sharing for your CEDAR artifacts. Simply find the artifact you want to share in your Workspace. Click on the menu selector for the artifact (the small green arrow in the screenshot below). In the resulting menu, click on Share menu item (the larger green arrow in the screenshot).



You can now enter either a person’s name, or a group’s name. As you start typing possible names will appear, and you can select the name you want to share with.

Once you select the name, a sharing choice will appear with the default permission: read. If you want to change the shared permission to enable writing, or (if you are the owner) even reassign someone else as the owner, click on the down arrow and select the permission you want to give.


You must click on the OK button to complete the sharing process.

You should now see the person’s name in the list of shared permissions on the right side.

To share artifacts with groups of people, see the Creating Groups page.

---




Sharing Via the Web

Introduction

With CEDAR OpenView, you can share your CEDAR content via the web. This feature works for templates, elements, fields, and metadata instances. You must be the owner of the content to share it, and if you are sharing a metadata instance, the template for that instance must already be shared. Templates, elements, and fields are displayed as empty metadata instances containing the relevant fields.

Sharing to the Web

To share your CEDAR template, element, or field via the web, simply select Enable OpenView via its drop-down menu. The CEDAR system will display a message indicating the sharing was successful.



To share a CEDAR metadata instance via the web, you must also share the template on which the instance is based. If you are not the owner, contact the owner or the CEDAR team to get help sharing the template. After the template has been shared, you will be able to successfully share the instance. (If you do not share the template, anyone who visits the shared metadata instance will see an error message rather than the actual metadata.)

Viewing the Shared Content on the Web

To view the shared content, select Visit OpenView via the artifacts drop-down menu. This brings up the OpenView, a public view of the shared content, in another web page.
You can copy the URL for the OpenView and share it with anyone else for viewing.

Once at the OpenView page display the content, you can view the metadata for the content by clicking on a downarrow in the title bar. The document metadata includes a link to open the document within CEDAR. This link will only work if the user has a CEDAR account with permissions to view the document.

The OpenView page lists the field type icons at the bottom of the main section. Below that it offers the option to view the ‘raw source’ representations of the content. For a template, element, or field, that will display the JSON Schema for the CEDAR artifact. For a metadata instance, you can view JSON-LD or RDF views of the metadata, as well as the JSON Schema of the template on which the metadata instance is based.

Ending Sharing

The owner of a CEDAR document that has OpenView enabled may choose to disable the OpenView at any time, using the Disable OpenView menu item from the document’s drop-down menu.

---

Description of a Template

Template Overview

Goals for CEDAR’s Metadata Template

The CEDAR Metadata Template (‘template’) serves three goals:

• defining the template questions (including their possible answers and other features);
• documenting the order in which the questions and elements will appear; and
• describing the template artifact: its name, its provenance including creation and update times, and its other characteristics.

We designed the template to meet these goals in a principled and efficient way, so that users could easily create templates that maximized production of effective metadata. We particularly wanted the templates and metadata to be applicable to any discipline or data system, and interoperable across those domains with any other system adopting our template model.

Basic Description of CEDAR’s Metadata Template

The template is in JSON Schema format, and conforms to a higher-level JSON Schema specification. The higher-level JSON Schema can be used to validate the syntax of any CEDAR template at any time; errors in this validation are displayed in the Template Designer user interface, as described in Filling Out (Creating) Metadata: Saving and Validating.

The JSON Schema of a given metadata template similarly validates any Metadata Instance that CEDAR users create with that template, so that the validity of the instance can be easily checked inside or outside the CEDAR system.

You can specify the content and order of questions in the template using the Template Designer. You make up a template from Template Fields and Template Elements. The Template Elements are made up of other Template Elements and Template Fields. The Building Basic Templates chapter describes the template specification process using the Template Designer.

Before reading about the specification process, you may want to review the next section, which more explicitly addresses the organization of the template.

---




Template Organization

Internal Organization

All information for the Metadata Template is stored internally in the JSON Schema format. CEDAR lets you view the template in this format at any time during template creation. See Viewing Resource as Raw JSON to learn how to view the template in its raw form.

The three Metadata Template functions (define questions, order the questions, and describe the template) are roughly organized into three sections in the JSON Schema template artifact.
The details of the template artifact’s format is described in more detail in the CEDAR Template Model.

Logical Organization

As a CEDAR user you will compose Metadata Templates from Template Elements and Template Fields. These three CEDAR resources, which we call templating resources, together establish the
questions for the metadata user to fill out. The actual process is described in the Building Basic Templates chapter.

As you reuse elements that you or others have created, CEDAR copies those elements into the main template, in whatever order you place them. You can reorder the elements and top-level fields in the template, but can not reorder fields within the template’s elements.

Metadata about the template are entered automatically by the system, and manually by you as the template creator. Fields you add include the title and the description of the template.

You may also add metadata fields to the template that are hidden from the end user. (You set the values of those fields using the Default tab for the field.) While these added fields can contain information about the template—or about anything else you want to describe in the final metadata instances—they are stored in the same way as the other metadata fields that you add to the template.

---

Building Basic Templates

First Steps

In the first steps to create a CEDAR Metadata Template resource, you will provide a human-readable label, a unique identifier, and a description of what the Template resource represents (e.g., “Injury-related treatments”).

To create a new template, first click the “New” button on the Desktop’s navigation sidebar (upper left of the Workspace view) and select the “Template” option in the dropdown menu. This step opens the Template Designer as shown below.

Enter the human-readable Name, Identifier and Description of the Template resource using the three text input fields (‘Untitled’, ‘Identifier’, ‘Description’) underlined in the image below. The Name is used as the name of the artifact in the Desktop, and can be changed from the Desktop view.



You can save and close your Template at any time and return to it later. You can open it for viewing or editing (or any other Template for which you have those access privileges) by double-clicking on its icon in the Desktop.

Useful Content Tips

By default CEDAR searches look at the artifact Name, Identifier, Description, and Version fields for matches, so consider what terms will be most important to include for searches to find your template.

Name: The name of the template should fit easily into the Workspace view if possible, keeping in mind that CEDAR names metadata instances by appending ‘metadata’ to the template name. The Name is analogous to the title of a web page. As a rough guideline, allow about 40-50 characters for your label.

You don’t need to append ‘Template’ or ‘Form’ to the end of the label; this will be clear from context.

Identifier: For CEDAR templating artifacts, the Identifier refers to an external identifier of an artifact corresponding to this template, not a CEDAR identifier. You do not have to create an identifier; in fact, typically you will leave this field blank. The attribute is provided for users who want to identify an external entity associated with this template. The Identifier works best when unique identifiers for the external objects can be automatically assigned and persistently maintained. (Please note this Identifier corresponds to the template, not for the metadata instances filled out for this template.)

Description: This description can be any length; a sentence or short paragraph is common. Describe the subject that the template is documenting; since we already know from context this is a CEDAR template, you don’t have to include that in the description.
Of course we also know it describes metadata, but “Metadata describing …” often offers a useful setup for your description.

Because Description is a longer field, it is a good place to include key words or other information you want to be able to search on to find this field.

Next Steps

Now, you can fill in the content of your template by Adding Fields and Adding Elements, or save and close it to return to it later.

---




Adding Fields

Fields can be added to a CEDAR Template in two ways: by importing a stand-alone Field artifact which was created separately, or by defining a field within an Element resource or a Template resource. (We refer to stand-alone CEDAR Field artifacts throughout this User Guide with a capital ‘F’, and refer to field definitions within templating artifacts with a lower-case ‘f’.)

We start this section by describing how a field definition is created directly in a templating resource, then describe how a stand-alone CEDAR Field can be created, and finally how a Field can be found and included in a Template.

Creating Field Content in a Resource

While specifying a field in a templating resource (a Template, Element, or Field), you can customize the Field resource in a number of ways, including constraining the values that metadata editors can input when they enter their metadata for the field. Some customizations apply to almost every field type; others are only allowed for one or two field types.

In Template and Element artifacts, multiple fields can be added; in a Field artifact, only one field can exist, and it must be a data input field.

You organize Fields and Elements in your templating resource by dragging them where you want them. Use the drag handles at the upper left of a Field or Element to grab it, and drag up or down. If you have trouble dragging it to the desired location, try shrinking the view within your browser to put more of the template on the screen. (Note: You can not change or organize content in an imported Field or Element.)

Adding a Field Definition

Choose the type of field to add to your templating resource using the vertical selector at the upper right of your Template Designer window. The first few choices give you simple ways to add simple text, date, email, and numeric fields to your Template resource.

If you want a less common field type—including organizing and documentation fields— click on the ellipsis (three dots) icon to bring up many more field choices. The choices on the left are fields for data entry; the choices in the right column allow the template author to customize presentation of the template to the metadata creator.

The search (magnifying glass) icon brings up a window to find other CEDAR templating resources—Elements or Fields— that can be imported into the resource you are editing. Use of this window is described in Adding Elements

Choosing and Configuring the Field Definition

For each data-entry field type, CEDAR supports certain options. For example, the Required option is offered on every data-entry field type. You can find simple information about a few key field types below, and detailed information about field types and their customizations in the Field Type Reference.

Common Options

In addition to the Required option mentioned above, many fields support the Multiple option.

Required

If this option is set to Yes, the Metadata Editor indicates to the metadata author that the field is required, and issues a warning when the metadata is saved but this field has not been filled out with metadata. The metadata author can choose to ignore the warning and save the metadata even though the required field is not completed.

Multiple

When Multiple is set to Yes, the Template Designer displays a control to define the minimum and maximum number of entries allowed for the field.

If Multiple is set to Yes, then the Metadata Editor provides an interface to fill out the field multiple times. The Metadata Editor requires the minimum number of cells for that field to be present (though they do not have to be filled out with values), and prevents more than the maximum number of entries by making the Copy icon unavailable).

Value Relation

The Value Relation optionally defines for every metadata-entry field the relationship from the field’s parent entity (the Template, or the Element) to the field’s value. For example, when the Value Relation is ‘has study characteristic’ from the Ontology for Clinical Relations (http://purl.org/net/OCRe/OCRe.owl#OCRE406000), the resulting metadata will be readable as <ParentElement> has_study_characteristic <user-selected-value>

To select a Value Relation, click on the RDF icon at the right side of the field. This brings up a search field that allows you to choose an appropriate Value Relation. (If the search brings up Classes instead of Properties, click on the Start Over button to clear the previous search.) Once you select a property, you are returned to the template. The selected property can be viewed by clicking on the drop-down arrow next to the RDF icon. (Clicking on the RDF icon again will clear any existing property and begin a new search.)

Configurations for Basic Text Field

Clicking on the Options tab presents additional features appropriate to the field type.

Options—Default Value

The Default Value option specifies the value for the field if the metadata author does not add a value to that field when filling out the metadata. The value can be either a string or a controlled term (expressed as an IRI).

Options—Minimum/Maximum String Length

With this option you can set a minimum length for the string, a maximum length for the string, or both. Users filling out the metadata will see a warning if the metadata is saved while the value in this field has a text length that does not satisfy the criteria.

Values

The Values tab shows a view of the current value set(s) that the metadata author can use to fill out a text field. If no selections are listed, the metadata author is prompted to enter free text. This ability to choose controlled values for the field is fundamental to CEDAR’s semantic capabilities.

Clicking on the Add button brings up a modal window from which you can select the term, branch, or ontology from which legal values may be chosen by the metadata author. You can repeat this process as often as you want to select additional terms, branches, or ontologies.

Advice about finding and choosing controlled values is available in the Choosing Controlled Terms section.

Suggestions

Set the Suggestions tab to Yes to enable intelligent authoring suggestions for this field from CEDAR. You can read a detailed explanation of the suggestions system at Understanding the Suggestion System.

Options for Numeric Fields

Number Type

CEDAR provides a default numeric field, whose values can be entered as either an integer or floating point number. As a template creator you can also choose a more specific number type for this field.

To select a specific number type for the field, click on the drop-down menu labeled ‘Any numbers’. Select from the list of number formats, including long-integer numbers, integer numbers, double-precision real numbers, and single-precision real numbers. Your choice will be reflected in the JSON value type used to describe the number field in the template (JSON Schema), and to specify the entered value in the metadata (JSON-LD).

Unit of Measure

You can specify the unit of measure as a string. The string will be displayed to viewers and editors of metadata created using this field, both before and after a value is entered for the field.

Minimum/Maximum Value

You can specify a minimum legal value, a maximum legal value, or both. Users entering metadata will be warned in real time if entered values do not meet the field’s value limit specifications.

Decimal Places

You can specify the number of decimal places used to display the value entered by the metadata author.

Creating a Stand-Alone Field

This process begins by creating the Field artifact, which is almost exactly like creating the Template artifact in First Steps. After that, the content of the Field artifact—the field definition— is created following the Adding a Field Definition subsection above.

To create a new stand-alone Field, click the “New” button on the Desktop’s navigation sidebar (upper left of the Workspace view) and select the “Field” option in the dropdown menu. This step opens up the Field creation form as shown below.

Enter the human-readable Name, Identifier and Description of the Field
using the three text input fields (‘Untitled’, ‘Identifier’, ‘Description’) underlined in the image below. Note the Name is used as the name of the artifact in CEDAR, and can also be changed from the Desktop.



Now the content of the Field artifact—the field definition—can be created. Since only one field specification can be in a Field artifact, the Field template opens with a text field type already selected. If you want a different field type, simply select it from the drop-down menu, and the existing field definition will be replaced.

At any time during or following the Field artifact’s creation, you can save the artifact and use the Template Designer’s left-arrow to return to the Desktop. From there, you can modify the name, access permissions, and public visibility of the Field artifact, as described in Managing CEDAR Resources.

Importing a Stand-Alone Field

Once the stand-alone Field artifact has been created, you can import it into other Templates and Elements. As mentioned above, when you are editing a Template or Element, the search (magnifying glass) icon in the Template Designer’s field addition menu brings up a window to find other CEDAR templating resources—Elements or Fields— that can be imported into the Element or Field you are editing. Use of this window is described in Adding Elements.

Next Steps

You can fill in more content of your template by Adding Elements, or save and close it to return to it later.

---




Adding Elements

An Element resource is composed of field definitions (possibly imported within Field artifacts) and other Element resources. (CEDAR does not handle recursion in Element resources.) These Element resources enable Template creators to share, reuse, and extend existing Element resources across different Template resources and across user groups.

This section is divided into two parts. (1) First, we create a new Element resource. (2) We embed the newly created Element resource within our Template resource.

Creating a new Element Resource

To create a new Element resource, return to the Desktop if you are not already there. (Use the “Back” button in the Template Designer—you may be prompted to save the artifact you are currently editing.) Click on the “New” button in the navigation sidebar of the Desktop, and select the “Element” option from the dropdown menu. This action will launch the Element editor view of the Template Designer, as shown below.



Enter the human-readable Name, Identifier and Description of the Field using the three text input fields (‘Untitled’, ‘Identifier’, ‘Description’) underlined in the image below. Note the Name is used as the name of the artifact in CEDAR, and can also be changed from the Desktop.

Now the content of the Element artifact can be created. Field definitions can be added directly, or by importing Field artifacts; instructions for both operations are found in the Adding Fields section.

Element content can also be created by importing existing elements, as described below.

At any time during or following the Field artifact’s creation, you can save the artifact and use the Template Designer’s left-arrow to return to the Desktop. From there, you can modify the name, access permissions, and public visibility of the Field artifact, as described in Managing CEDAR Resources.

Spreadsheet-compatible Elements

If you want users to be able to fill out their metadata using a spreadsheet— especially valuable if there are a lot of fields to be filled out with existing metadata— you must create your element to satisfy a particular requirement.

An element that is to be filled out as a spreadsheet must be ‘flat’, meaning there are no further hierarchies or arrays within the element. Embedding another element, or allowing multiple entries for any of its entries, will prevent the user from displaying the element in spreadsheet mode. Also, the MULTIPLE attribute of the element must be defined to allow multiple entries.

The process of filling out the metadata using spreadsheet mode is described in Spreadsheet entry.

Embedding the Element Resource

When you are editing a Template or Element, the search (magnifying glass) icon in the Template Designer’s field addition menu brings up a window to find other CEDAR templating resources—Elements or Fields—that can be imported into the Element or Field you are editing.

The navigation path in the lower left of the window starts in the current directory (from the last Desktop view), and can be used to navigate to other locations in CEDAR. However, most users will find Elements and Fields by searching for them.

To perform a search, begin entering a search string in the search field of the window. In the image below, ‘Address’ has been added and the search performed when the user hit the return key. You can see that Elements and Fields are visible in the search results.

To investigate a particular discovered Element for suitability, click on the Element to bring up its description, as seen below.

To embed an Element or Field artifact in your templating resource, either double-click on the artifact, or click once on the artifact and then click on the Open button. The Element or Field will be incorporated at the end of your templating resource.

Within the templating resource, you can not edit the core characteristics of imported content (the Element or Field), including the order of components within an imported Element. You will be able to relabel the imported content, and will be able to choose a property that relates the imported artifact to its parent.

You can move an any imported Element or Field in your templating resource by dragging it where you want it. Use the drag handles at the upper left of the Element to grab it, and drag up or down. If you have trouble dragging it to the desired location, try shrinking the view within your browser to put more of the templating resource on the screen. (Note: You can not change or organize content in an imported Field or Element.)

---




Saving and Closing

Saving

To save a templating resource—Template, Element, or Field—click on the Save button at the bottom right of the templating resource. This will be labeled Save Template, Save Element, or Save Field depending on the type of templating resource you are editing.



At the top right of the templating resource, there are 3 icons that indicate the resource status. The left-most icon (the circle) is filled when the instance has no unsaved changes, but is a hollow yellow circle when there are unsaved changes.

If the lock (the middle icon) is yellow and locked, you will not be able to save your changes, even to a separate file. To create an editable version of the resource, you will have to exit the resource, make a copy of it from the Desktop, and edit the copy you made.

Validation

CEDAR performs syntactical validation of a templating resource when it is opened and saved. This checks that the resource conforms to the Template Model schema, which is expressed as JSON Schema. The validation should always succeed and yields a white checkmark in the third icon. If the syntactical validation fails, the checkmark turns yellow, indicating there is a problem in the CEDAR system. Often you still will be able to work with the resource, but it is best to contact the CEDAR team to alert them to the problem.

On a successful verification, CEDAR issues a green “[Artifact] saved successfully” notification, where ‘[Artifact]’ will be replaced by ‘Template’, ‘Element’, or ‘Field’.

Closing

Saving before closing

While a templating resource is being edited in the Template Designer, it can be saved at any time.

If you have made changes and try to leave the resource without saving it by using the CEDAR back button, CEDAR will issue a warning. If you click Continue, any changes you made will be lost and CEDAR will return to the Desktop view. Choosing the Go Back button will return you to the templating resource.

If you have made changes and try to leave the resource without saving it by using the browser back button or closing the browser window, the browser will issue an error message. In Chrome, click on Leave Site (the default) to close the resource, and on Cancel to remain on the page.

Because there might be unusual conditions that cause you to lose your session,
we strongly encourage you to save your work often. 
We are unable to restore work that has been lost when the session is lost.

If you have remained on the page, you can save the resource and then return to the Desktop view or close the window.

Returning to Desktop

When you close the template to return to the CEDAR Desktop view, there are two ‘return left’ buttons—the one in the browser, and the one at the upper left of the CEDAR Template Designer. The CEDAR button remembers the last folder you had open in the Desktop view, ignoring any searches you may have performed since then.

If you launched the Template Designer from a CEDAR search results page, and want to return to that page, use the browser back button, and the same search should be performed. (If you mistakenly chose the CEDAR back button, you can still use the browser button twice to get back to the previous search results.)

Recovering previous version

Because there is no undo, should you need to recover a previous version of the document, you can contact CEDAR staff to restore a version from before the time you started editing. If you plan to make significant changes to a template, especially if you are experimenting with it, we recommend saving a copy before you start changing it.

---




Field Type Reference

Field Type Reference

While specifying a field in a templating resource (a Template, Element, or Field), you can customize the Field resource in a number of ways, including constraining the values that metadata editors can input when they enter their metadata for the field. Some customizations apply to almost every field type; others are only allowed for one or two field types.

All the customizations listed in the Reference tables are described after the Reference Tables subsection.

Reference Tables

The tables in this subsection show the field types that CEDAR offers, and the customizations or purpose supported by that field type.

Data entry fields

All data entry fields support the Required and Value Relation features, and all of them support the Multiple feature except those noted in the next table.

The following table lists CEDAR’s supported customizations unique to each field type for data entry. It also shows the Data Type(s) used by CEDAR for those field types. If the Data Type(s) column is blank, the field type is the default (a text string).

Unique Field Type	Data Type(s)	Unique Supported Customizations
Short Text		Values; Suggestions; Hidden; Default
Paragraph Text
Email
Phone
Link
Numeric	any number (xsd:decimal); integer (xsd:integer); long integer (xsd:long); single-precision real (xsd:float); double-precision real (xsd:double)	Unit of Measure, Minimum Value, Maximum Value, Decimal Places
Date	xsd:date
Multi-Choice		Default; no Multiple
Checkbox		Default; no Multiple
Pick From List		Single Select vs Multi-Select; Default; no Multiple

A special type of data entry field is the Attribute-Value field type, which lets the metadata author name the Attribute and provide the Value when entering the metadata. This field type allows multiple (unlimited) entries by design.

Special field types for presentation

The following special field types do not support data storage for the metadata creator, but allow the template author to customize presentation of the template to the metadata creator.

Special Field Type	Description	Purpose
Section	Creates a section break	Provides a textual separator with optional explanatory text
Page	Creates a page break	Breaks up form into multiple pages (screens) when entering metadata
Rich Text	Support entry of rich text in HTML	Provide a descriptive lead-in to the following field for metadata creators
Image	Specify location of an image to display	Provide a static visual lead-in to the following field for metadata creators
YouTube	Specify location of a YouTube video to display	Provide a video lead-in to the following field for metadata creators

Customization Descriptions

This subsection describes the field customizations, which are presented in alphabetical order by name.

Decimal Places (Numeric field Option)

You can specify the number of decimal places used to constrain and display the value entered by the metadata author.
The metadata author will not be able to enter more decimal places than the value specified by this option (or if more decimal places are entered, the value will be rounded to fit into the specified number of decimal places).

This customization has no impact if the Numeric field type is an integer type.

Default Value (Text field Option)

The Default Value option specifies the value for the field if the metadata author does not add a value to that field when filling out the metadata. The value can be either a string or a controlled term. The controlled term must be expressed as an IRI from BioPortal.

Minimum/Maximum Value (Numeric field Option)

For numeric fields, you can specify a minimum legal value, a maximum legal value, or both. Users entering metadata will be warned in real time if entered values do not meet the field’s value limit specifications.

Minimum/Maximum String Length (Text field Option)

With this option you can set a minimum length for the string, a maximum length for the string, or both. Users filling out the metadata will see a warning if the metadata is saved while the value in this field has a text length that does not satisfy the criteria.

Multiple

When Multiple is set to Yes, the Template Designer displays a control to define the minimum and maximum number of entries allowed for the field.

If Multiple is set to Yes, then the Metadata Editor provides an interface to fill out the field multiple times. The Metadata Editor forces the specified minimum number of fields to be present (though the user is not forced to fill out the fields with values). The Metadata Editor prevents creating more than the maximum number of entries by making the field Copy icon unavailable.

Number Type (Numeric field Option)

CEDAR provides a default numeric field (decimal), whose values can be entered as either an integer or floating point number. (Exponential notation is not supported.) As a template creator you can also choose a more specialized number type for this field.

To select a specialized number type for the field, click on the drop-down menu labeled ‘Any numbers’. Select from the list of number formats, including long-integer numbers, integer numbers, double-precision real numbers, and single-precision real numbers. Your choice will be reflected in the JSON value type used to describe the number field in the template (JSON Schema), and to specify the entered value in the metadata (JSON-LD). The Data entry field table in the Reference Tables section lists the specific JSON value types used for each case.

Required

If this option is set to Yes, the Metadata Editor indicates to the metadata author that the field is required, and issues a warning when the metadata is saved while this field has not been filled out with metadata.

The metadata author can choose to ignore the warning and save the metadata even though the required field is not completed.

Suggestions

Set the Suggestions tab to Yes to enable intelligent authoring suggestions for this field from CEDAR. You can read a detailed explanation of the suggestions system at Understanding the Suggestion System.

Unit of Measure (Numeric field Option)

You can specify a unit of measure for the field as a string. The string will be displayed to viewers and editors of metadata created using this field, both before and after a value is entered for the field.

Value Relation

The Value Relation customization provides a unique capability to the CEDAR metadata model for making metadata more semantic.

For every metadata-entry field, the Value Relation optionally defines the relationship from the field’s immediate parent entity (either the Element containing the field, or if the field is at the top level, the Template containing the field) to the field’s value. For example, when the Value Relation is ‘has study characteristic’ from the Ontology for Clinical Relations (IRI of http://purl.org/net/OCRe/OCRe.owl#OCRE406000), the resulting metadata will be readable as <ParentElement> has_study_characteristic <user-selected-value> where each of the 3 elements is replaced with its corresponding unique identifier (IRI).

To select a Value Relation, click on the RDF icon at the right side of the field. This brings up a search field that allows you to choose an appropriate Value Relation. (If the search brings up Classes instead of Properties, click on the Start Over button to clear the previous search.) Once you select a property, you are returned to the template.

The selected property can be viewed by clicking on the drop-down arrow next to the RDF icon. Do so carefully, as clicking on the RDF icon again will clear any existing property and begin a new search.

Values

The Values tab shows a view of the current value set(s) that the metadata author can use to fill out a text field. If no selections are listed, the metadata author is prompted to enter free text. This ability to choose controlled values for the field is fundamental to CEDAR’s semantic capabilities.

Clicking on the Add button brings up a modal window from which you can select the term, branch, or ontology from which legal values may be chosen by the metadata author. After you’ve made the selection, you will be returned to the view of the field which includes a line describing your selection.

You can repeat this process by (clicking the Add button) as often as you want to select additional terms, branches, or ontologies. You can remove any of the selected terms, branches, or ontologies by clicking on the X to the right of the row you want to delete.

Advice about finding and choosing controlled values is available in the Choosing Controlled Terms section.

---

More FAIR Templates Using Semantics [Partial]

Why Semantics Are Important

Introduction: The Problem

Everyone is familiar with the two challenges of search: not finding everything you want; and finding things you don’t want.

Finding things you don’t want (the problem of precision) almost always comes from the basic truth that words (the usual coin of the realm for searching) have many meanings, some of which may be much more popular than yours. So your search for “python” may not find the horror film, but instead snakes, people of ancient Greece, roller coaster, or (most likely) the programming language. Even adding terms for disambiguation (“python movie”) doesn’t narrow the search much.

And then, you can’t be sure all the relevant things will be found (the problem of recall) . Maybe the person creating the description of their post is a film snob, and never uses the word ‘movie’. Without understanding that ‘film’ is a synonym for ‘movie’, software will not find conceptual matches that aren’t spelled the same way, or that are similar in important ways. For example, a search may be looking for treatments for a disease but not finding drugs for the disease, even though drugs are clearly treatments.

This is especially challenging when you are trying to get precise results as you analyze data, look for similar data sets, or find anything specific in a large set of candidates. You want the system you are using to understand what you mean—in other words, to understand semantics. And you want the understanding, and results, to be as precise as possible.

And yet what happens instead is that the original questions were unclear, the descriptive answers that the users tried to provide— and that you are now working with—are confusing and ambiguous, and now there is no way you can obtain any sort of meaningful result from your efforts. If only people could be more careful when they created an described their results!

Semantics: The Solution

To seriously reduce these problems, we use semantic technologies to give more precise meanings to the words people are using. To increase precision, we can use exact identifiers (identifiers that are unique across the whole internet) to refer to concepts, so the user can enter an unambiguous string that precisely means a python snake. To increase recall, we can help software easily collect and apply precise names— identifiers again—when users are entering descriptions. We can also give the software tools to understand the relationships between those precise identifiers. In this way descriptions collected from different communities can be ‘translated’ from one set of precise terms to another, with some confidence that the original meaning will be preserved.

Semantic standards like OWL, RDF, and SKOS, and semantic tools that understand these standards, provide a baseline for building systems that are semantically interoperable. CEDAR is one such tool— it lets form developers specify questions more thoroughly, and specify answers in semantically precise ways, so end users filling in metadata create well-defined descriptions. And it can use semantic and other insights to understand when questions and even whole questionnaires might be about the same topic, and to suggest relationships between them.

Using Semantics in CEDAR

The following sections in this chapter describe how you can use CEDAR to create more rigorous metadata forms that are easier for users to understand and fill out. This process is rarely perfect, but it can offer much, much more precision and recall for the person finding or re-using the data.
And did we mention it can be easier for the user to use than existing forms? And even easier for you to set up the data collection system.

---




Defining Your Answers with Term Lists

To go to a particular topic, click on that link.

• Introduction
• Basic Interactions
  • Searching for Terms
  • Reviewing Found Terms
  • Selecting Terms, Branches, or Ontologies
  • Searching for Ontologies and Value Sets
• Adding Your Own Terms
  • About Provisional Terms
  • Adding your Own Single Term(s)
  • Adding a New List of Terms
• Customizing What You Have
  • Rejecting Terms
  • Putting Favorites First

Introduction

Now we will show you exactly how to create questions that have very precise answers, using CEDAR’s semantic tools. You don’t have to know semantics to use these tools— we’ll give you some tips (in Choosing Controlled Terms that help you find good answers for your questions, and know they are good enough for your needs.

For you semantic experts, we provide advanced details elsewhere in this User Manual:

• Tips for Template Creation: Term Discovery/Selection
• Advanced Template Topics: More Semantics

In this section we outline the mechanical steps to find, select, and even create terms. The next section will tell how to figure out which terms are good ones to use.

This section (except the Customization subsection at the end) walks you through CEDAR interfaces that work hand-in-hand with the BioPortal ontology repository. This repository contains over 800 public terminologies that offer precise semantic content you can use for your metadata collection process. But if BioPortal does not contain a terminology that you want to use, you can add it! See the subsection called “Adding Content to BioPortal” in the More Semantics section for more information on this process.

All the following sub-sections assume you have created a basic text field, clicked on the Values tab for your field, and clicked on the Add button to bring up the term search dialog box, as described in Adding Fields.

Basic Interactions

You may want to add individual terms or whole collections of them. First we will work at the level of individual terms, and progress to finding and adding collections of terms.

Searching for Terms

In the Template Designer, as soon as you hit the Add button in the Values tab of a CEDAR field, CEDAR opens a new search window, pre-configured with the name in your field, and the search for terms begins immediately. In this case, the name is “Study Type”, and a set of results has been returned. You can see each term in the scrollable list—the most likely terms are listed first.



You can change the search terms by typing in the search field. If you search doesn’t begin immediately, click on the magnifying glass to start it. The results list updates as more results are found, and higher-value results may be inserted in front of results you are looking at. Usually all the results are obtained quite quickly. (A maximum of 500 results may be obtained.)

You may want to refine the search to meet particular needs. By clicking on the settings gear at the right of the search field, you will see a set of Advanced Search Options. The first option, to search for a term anywhere in BioPortal, is pre-selected. (We will discuss the other ‘I want to…” options in later subsections.)



For now, we want to focus on the “Narrow your search to specific ontologies” field. If you know the ontologies in BioPortal that you want to use for your terms, you can enter them into this field. Start typing either the ontology acronym or its full name, and CEDAR will offer a list of the matching ontologies. Click on the one that you want to include as a restriction, and its acronym will appear in the field.

You can begin typing again in the field, and select another ontology, until you have found all the ontologies you want in your restriction list. In this case, we have selected the ontologies with the acronyms CTO and NCIT. This technique can be used to see more terms in the given ontologies, or to exclude any other ontologies from being considered.



Reviewing Found Terms

Now that you have some terms, you may want to examine some terms more closely, to see if they are really what you want. The first thing you may notice is that earlier terms in your list are exact matches of your string, while later terms do not match as closely. This is the first test used to order the terms presented to you.

Clicking on Show Details for a given term (at the right of that term’s row) will unfold a new display underneath the list of terms, which allows you to inspect the term more closely. At the left side of this new display is a list of terms in the ontology, in most cases scrolled to the specific term identified. (Sometimes the term appears multiple places in the ontology, and you will need to explore to find it.)



Whenever you click on a term, its detailed information appears in the Term Details tab on the right. (Click on the Ontology Details tab to see information about the whole ontology.)

You can navigate the tree by using your mouse to scroll up and down, and open and close its branches by clicking on the + and - boxes on the left side. Below we see the details of classes that were hidden under the Study Type branch in the screenshot above.



In this case, we may decide this class is not appropriate, as it contains many Study Types that are particular to plant science. By clicking on the Study type term in the CTO ontology, we can see from examining its branch contents (in the left-hand display under ‘CTO classes’) that it is a much more generic description of study types.



In the next section we’ll discuss how you can choose what you want to include in your list of responses.

Selecting Terms, Branches, or Ontologies

By scrolling down in the Term Finder window, you can see additional controls (below). In particular, note the three tabs TERM, BRANCH, and ONTOLOGY. These control what you can select for your field’s values. (If the term you have selected does not have any subclasses, you will not see the Branch tab, only Term and Ontology.)



In the screen shot, the BRANCH tab is selected; the term identifier and name are shown; and the description says “Click to add all the descendants of the selected term.” If you click on the ADD button, all the classes under “Study Type’ (5 are visible) will be added as acceptable responses for your field.

If you had selected the TERM tab, and then clicked ADD, only the Study Type term itself would be added as an acceptable response. This is a less common choice, as usually you want users to select from a collection of related terms in an ontology.

If you select the ONTOLOGY tab, all the terms in the ontology (PECO in this case) would be added as an accepted response. The only time you’d expect to select this tab is when the entire ontology is devoted to a single concept. For example, the Disease Ontology only contains disease terms, and is sometimes the perfect choice for selecting a disease.

Here we talked about starting a term search, then picking a whole ontology that contained the term. What if you just want to search for ontologies (or its simpler cousins, Value Sets) by name? This takes us back to the control gear in the search box, and is described in the next subsection.

Searching for Ontologies and Value Sets

The two other buttons in the “I want to…” section of the Advanced Search Options let you search explicitly for ontologies or value sets. When you click on one of these buttons, the text in the top search field is used to find the results (by acronym or name). In the following example, a search for a Study Type ontology is being conducted; this will not find any results, since no Study Type ontologies exist in BioPortal.



A Value Set in CEDAR is like a very simple ontology; it consists only of a set of terms that have identifiers and labels. Value Sets tend to be smaller than ontologies as well, and organized around a single topic. (In fact, they are often created to make lists of terms for filling out forms.) In the following screenshot, you can see that there are a number of Value Sets that deal with Study Type. The Source column is the name of the ontology containing the Value Set; in BioPortal Value Sets are typically grouped into organizational ontologies for easier management.



Adding Your Own Terms

You may not be able to find every term you want, or a list of terms that you think makes sense. CEDAR can help you manage the process of adding such terms to use in your fields.

About Provisional Terms

Provisional terms are terms that the user is proposing to be added to an existing resource, or perhaps independently as a stopgap measure. In principal, they are meant to be used only for the time it takes to take action on the proposal: either to accept it and add the term to the existing resource (in which case the provisional term is deprecated in favor of the new term), or to reject it for that purpose or simply declare it is no longer needed (in which case the provisional term is simply deprecated). The provisional term should not be deleted, so that any existing and archived used of it might still need to reference it.

CEDAR lets you create provisional terms, and link them to the resource(s) and even the existing classes that are related. However, it does not provide any mechanism yet for taking action on those terms, like notifying owners of related resources of the proposed term, or annotating deprecations of provisional terms and referencing terms to replace them (if any). These features can not be implemented until there is support in BioPortal for managing provision terms. (Such support has been proposed in an award to be evaluted in 2021.)

Adding your Own Single Term(s)

These screenshots show the process of adding your own individual terms for use in CEDAR. The new terms are created as provisional classes in BioPortal, and can not be modified once they are defined (per above paragraph).

To begin the process of adding a new term, click on the Add New Terms link at the top of the term selection dialog box. The link is highlighted in the image below.



The next two screenshots show the resulting dialog box, and the entry of appropriate text into the fields.





If you click on the “Link to existing terms (optional)” rocker switch, you will be taken through additional dialogs (first one shown) that let you add relationships from your term to existing terms in existing ontologies. In the future, this information may support informing ontology resource authors of your proposed addition to their ontology.



Adding a New List of Terms

The feature to add a new list of terms is not available within CEDAR. To perform this action, you must create or modify an ontology in BioPortal to add your list of terms.

This is particularly straightforward to do as a SKOS vocabulary, if you follow the appropriate BioPortal practices for a SKOS vocabulary . collaborators from our Metadata Center and the FAIR Data Collective have created a tutorial describing a simple way to create such a SKOS vocabulary that can make SKOS vocabularies easy to build, register in BioPortal, and maintain in GitHub.

Customizing What You Have

When you are done adding terms, you may want to eliminate certain terms, or put some terms ahead of others. CEDAR supports these capabilities. Both use the Arrange button on the Values tab of the field in the Template Designer, which brings up the following dialog.



Rejecting Terms

To eliminate a term, move your mouse pointer over the term. Click on the X icon that appears and the term will not be shown to users.

Putting Favorites First

To move a term, click on the up-down arrow icon. You will be shown a dialog box that lets you move the term to the top of the list, or to any particular place in the list. The locations of other terms are adjusted automatically.

---




Choosing Controlled Terms

General Introduction

This page presents a (relatively) brief and simple primer about choosing controlled terms.

A thorough tutorial deserves several chapters, if not a whole book. But you can do a very good job with just the advice offered here.

Let’s start with some general observations.

Perfect terms, or perfect lists of terms, can be elusive, just like perfect software tools. It is often true that you can find many lists on a topic, but none are exactly right for your needs.

CEDAR helps with this—you can add terms to your list, remove terms from your list, or reorder the terms in the list, and you can combine different lists of terms. If you find a list of terms that is almost perfect, we highly recommend using that list and tweaking it with your changes. In this section, we assume you will be doing just that.

It will help if you are familiar with the domain that you want terms for, especially if you already know vocabularies or people you can ask about vocabularies. It can be very hard to find good vocabularies, or to choose the best terms for your needs even if you have options.

The most likely sources for good terms and lists are authoritative sources, for two reasons: (1) The authors thought a lot (usually) about the terms in the list. (2) The terms in those lists are likely used often, so you get good interoperability. So, term lists in popular ontologies, web sites, and reference books or articles (especially heavily cited ones) are often very useful.

And a final observation is that term lists for mundane things— topics that aren’t specialized, like “types of stores” or “types of places for meetings”— these handy types of terms are almost impossible to find. You may well be on your own to create a term list like this. (On the bright side, if a lot of people need your list, it could be very popular.)

Your criteria

There are so many criteria for deciding what term, list, or ontology is better, and the most important one is “does it fit your needs?”. Since only you know what your needs are, we leave it to you to weigh these criteria for yourself.

The list of General Criteria that follows may be helpful in establishing in your own mind what you are looking for in your search.

After that, we’ll talk about how you can find better terms and term lists when using CEDAR.

General Criteria

Whether you are talking about terms, term lists, or whole ontologies of terms, each of the following categories embodies multiple specific evaluation criteria. Many of the criteria are objective, but many others are subjective or hard to measure.

• Popularity
• Reuse of ontologies / terms (ontology as a whole, and individual terms, in either case)
• Community (as in, domain) relevance (usage, standardization, concept applicability)
• Governance (is it well-managed with clear and open policies?)
• Adoption of best practices (including FAIRness criteria and metadata scope)
• Precision of matching to your term needs
  • if multiple terms, match frequency and specialization
• Criteria that cut across the above
  • Level of internationalization
    • how widely used
    • ‘level’ of governing body
    • international re-use
    • use of multiple languages in text labels and definitions
  • Quality
    • by metrics
    • by independent qualitative assessment(s)
• Analytics (ontology content and structure)

Because few of these are readily available in CEDAR, let’s focus more directly in the following section on concrete evaluations that are easy for CEDAR users to do.

What Makes a Term Better?

These are the strategies to see if a particular term is the one you want as a choice for your template. Note that most commonly, you are looking for branches containing lists of terms, so that you can include everything you need at once. But sometimes, choosing those branches requires that you examine a few terms, and other times, you want to include a few specific terms that aren’t in your core list.

Naming

Look at the name—which really means the ‘label’, in semantic talk— for the terms you are comparing. The term name should be clear and aligned with the way your users think of the concept. Names are usually very short, and if the name is longer, consider whether it needs to be.

Sometimes it matters that the term name match exactly what users expect. Taxonomists would not expect to see the common name ‘human’, and lay persons wouldn’t be looking for ‘homo sapiens’. And it will be really awkward if the naming patterns aren’t consistent.

When the name of your field is long, the search executed by CEDAR returns more things, and they often don’t fit quite as well. (There are two reasons for this. Specialized terms are less likely to find matches, and the words you use are less likely to match the words used in the ontologies.) For this reason you’ll want to examine the concepts that are returned, and maybe even change your search phrase to find more options.)

The Order of Things

In CEDAR, the order of the concepts that are listed for a term search is as follows:

• perfect matches for your search phrase;
• close matches for your search phrase (e.g., words that start with your search phrase, but keep going); and
• poorer matches for your search phrase, concepts that include your search phrase in the definition of the concept, or concepts that are synonyms for your search phrase.

Of all the concepts that are equally good syntactic matches, the first ones listed are the ones in ontologies that are the most widely used in BioPortal. Usually these are very common and well-known ontologies that have more credibility. This works surprisingly well to identify ‘better terms’, but make sure the term makes sense for the ontology (you are looking for an ‘eye’ of a hurricane but find it in a biomedical ontology).

Definition and Structure

Yes, but what does that term mean?

You can see the definition of each term in CEDAR in the list of search term results. If your term does not have a definition, it can be hard to know what it means. Not only that, people looking up your term later (by its identifier, say) also won’t know what it means And if (eventually) CEDAR shows the definition to people filling out forms, they won’t know what it means either. So we don’t recommend the use of terms that don’t have definitions.

The other way to understand what your term means is to look at its context. When you click on a term, an option appears on the right side that says “Show Details”. Clicking on this option opens a tree browser, usually highlighting the term in question. (If your term is not highlighted, you have to scroll through the tree to find it. Note the term may be in multiple places, if it has multiple parents in the hierarchy.)

By examining the hierarchy, you can understand the nature of the term. Other terms at the same level and with the same parent tell you about sibling concepts. If the term has a plus sign next to it, clicking on it will find children concepts, which themselves represent a kind of definition of the concept. And browsing up the tree to find the terms parentage tells you what category this concept fits into, which gives you another type of definition.

It may not matter for this use case, but you should know that hierarchies in BioPortal can express ‘subclass’ relations (B is a type of A); ‘part of’ relations (B is a part of A); or for SKOS vocabularies, simple ‘hierarchy’ relations (B is narrower than A, in some undefined way).

To learn more about your term, you’ll need to visit the term in BioPortal to see more details. This is described in the next section.

More Context

If you want to learn more about a term, you can usually get more details about it, but not from within CEDAR.

Often you can get a page describing the term by entering its full identifier. You can find this ‘ID’ by clicking on the term, then look under the ‘Term Details’ tab below the list of responses. Copy the value of the ID and paste it into your browser— often this will open a detailed page about the term.

If it does not, visit BioPortal at https://bioportal.bioontology.org. You can try pasting the ID into the Class Search box on the front page, or go to the class Search page and paste it in there, selecting ‘Exact matches’ under the Advanced Search section, and clicking on the first result of the search.

(As a final resort, navigate to the ontology containing the term by pasting the ontology acronym from the source column into the “Find an ontology” box on the front page, then select that ontology from the list that pops up, then navigate to the Classes tab, then enter the name of the term in the Jump to box and select the term of interest. Whew!)

You should see a Details tab that contains all sorts of information about your term. If it is only 2 or 3 items listed there, your term is not very thoroughly defined— possibly you’d like to look for one with more information.
But if your term is well defined, you will see considerable information about it, and can decide if any of the (inevitable) minor discrepancies would keep you from using it.

BioPortal doesn’t list everything it knows about the term, but most of the information in the source ontology is presented.

Finding a Better Branch

What if you’re looking for a rather specific list of terms, perhaps with just a few words? You won’t often find a whole ontology dedicated to just that list, but you can often find specific branches from hierarchical ontologies that meet your need. In fact most lists of terms used to answer questions are found in ontology branches.

Finding Ontologies with Branches

When you first look at the term, you may not be able to tell if it is the top of a branch. The fastest way to check this is to click on the term, and see if the tab “BRANCH” appears below the found term list (in addition to “TERM” and “ONTOLOGY”). if the selection tabs don’t show the BRANCH option, then your term is not the top of a branch. You can quickly click through the list to see which entries are the top of branches. (If the item on the far right of a selected term says “Hide Details”, choose this option to make the click-through process faster.)

If your term is not the top of a branch, then as described above, after clicking on a term, select the “Show Details” option to show a hierarchical view of the ontology, often with your term highlighted. You may be able to find a good branch by navigating up and down the tree from your term, but just for one or two levels. Hunting around the whole ontology may not be effective, and the strategies below may be better.

Likely Branch Names

Think about whether synonyms of your term may be better branch titles. If you are searching for ‘sex’ but not finding many branches, try ‘gender’ instead; for ‘race’ try looking also for ‘ethnicity’.

Narrowing your search can be useful—for ‘location’ you might try ‘geographic location’ or the specific kind of location, like ‘country’. These refined names will also help eliminate overlapping meanings, like the location on a body. An online synonym list may be valuable.

In general when trying to name a branch, you want to use the most specific category you can think of that includes all your terms. But it’s hard to know what others might have used to categorize your concepts. A good alternative is to ‘start lower down’, searching for things in the category instead of the category itself.

Starting Lower Down

Since category names can be specialized and sometimes rather arbitrary, an effective search strategy can be to search for the entities you want to appears in the drop-down list that users see. So rather than searching for ‘gender’, you can try searching for ‘female’.

Once you find a term that matches, use the Show Details option to bring up the tree view of the ontology containing that term. Ideally your term will be highlighted in the tree; if not you need to find it if possible. Once you find the term, you can navigate up the hierarchy to see its parent category. Examine the terms under that category (and possibly under higher categories) to see if they are the terms you want to display. If they are, select that (parent) term in the hierarchy to give you a good branch containing the terms you want.

Whole Ontologies

Some of the strategies for finding branches can also find good ontologies. For example, if instead of looking for ‘location’ or ‘city’ as an ontology name you search for a typical location with an uncommon name (say “Sacramento”), you can see ontologies containing items with that name. In this case, you may quickly see that BioPortal has only one good location ontology (GAZ) and that it is flat, so you might create your own vocabulary for these purposes.

Serendipity and Reuse

If you keep your eyes open as you are using CEDAR and looking for your concepts, you will start to learn what ontology content is already available in BioPortal, and what ontologies others are using in their templates. Searching for templates like your own in CEDAR may help you find some fields that you could re-use, or whole elements that are useful. CEDAR is actually a responsive tool you can use to browse around a wide range of terms and ontologies.

Browsing (BioPortal)

While CEDAR is fast, BioPortal itself is more thorough and has more features. You can search for terms from the front page, or from the search page, and you can quickly see the context for a large number of terms that match your search pattern.

You can use the BioPortal Annotator to search for a large number of terms at the same time. Be sure to check out the advanced features within the Annotator page to enhance your searching capability.

Finding the Best Ontology: BioPortal’s Recommender

If you really want to find the best ontology for a number of related terms, or even a single ontology, the BioPortal Recommender is an extremely effective tool. It’s use is fairly self-explanatory, but again be sure to check out advanced options, particularly to match you terms with the best combination of ontologies.

Discussing ontology recommendations is too complicated for this document (note the General Criteria above), but the BioPortal Recommender is a good way to narrow your options. You can then use the advanced features of the CEDAR search to narrow your term search to just those good ontologies.

Browsing (Everywhere)

There are other sources for ontology terms, whether they are in formal ontologies or just in published vocabularies. Converting these sources to ontology resources in BioPortal can be tricky, so you might email the BioPortal support list for advice for your specific case.

---




Creating lists in the metadata entry forms for users

There are several ways to present a list of terms for the user to select from in CEDAR. Unfortunately, only one of these (described in previous chapters) is truly semantic. (Eventually we will offer semantic options for all these list types.)

This section serves as a relatively simple review of the types of lists CEDAR supports. In each list type we’ll discuss pros and cons unique to that list type.

In the Field Type Reference, you can find listed the 4 field types that can generate lists of answers: Basic Text; Multi-Choice; Checkbox; and Pick From List.

Basic Text

(Values; Suggestions; Hidden; Default)

Multi-Choice

(Default; no Multiple)

Checkbox

(Default; no Multiple)

Pick From List

(Single Select vs Multi-Select; Default; no Multiple )

Basic Text
Multi-Choice		Default; no Multiple
Checkbox		Default; no Multiple
Pick From List		Single Select vs Multi-Select; Default; no Multiple

---

Advanced Template Topics [Partial]

Extending a Template (adding fields)

We’re sorry, this resource has not yet been developed. You are welcome to contribute to its development at the link below.

Introduction

How to Extend a Template

make a copy

rename appropriately

add a comment (optional)

Letting Users Add Their Own Fields

simple as using the Attribute-Value field type

doesn’t really create a new specification

Creating an Extended Specification

many specifications are extended for additional uses (sometimes called profiling, alas)

after basic steps, add your desired field, at end or (for eximple templates) inline

if you want inline but inside an element are used, they would have to be extended themselves

---




More Semantics

We’re sorry, this resource has not yet been developed. You are welcome to contribute to its development at the link below.

Characterizing your templating artifact

Relating your Element or Field to its parent









Characterizing your field (future)

Versioning vocabularies you use

Adding your terminology to BioPortal

---




Understanding the Suggestion System

CEDAR’s Value Recommender is a metadata recommendation system that helps users to fill out metadata templates with the most appropriate values. The system finds and applies patterns in the previously entered values to generate recommendations for all the recommendation-enabled fields. CEDAR’s Value Recommender is integrated in the CEDAR Workbench [1] and it can also be invoked programmatically through its API [2].

This document describes the steps to enable recommendations for templates and use them to quickly and accurately create new metadata.

Getting started

Metadata suggestions are disabled by default. When creating your template, you can enable suggestions by following these steps:

• Log in to the CEDAR Workbench [1] and create a new template.
• Add a new field to the template and use the “Suggestions” setting to enable recommendations for it. Note that:
  • The “Suggestions” tab is only available for fields of type “text”.
  • You must enable suggestions for a minimum of two fields in the template.

The Value Recommender will make recommendations only when it can see a pattern worth recommending, which means there must be many repeated values in a field. Thus, fields with controlled vocabularies, or with relatively few likely choices, are the best candidates for recommendations.

Save the template and click on the arrow located on the top left corner of the screen to exit the Template Designer.

Once the template has been saved, you can start filling it out with metadata and getting recommendations. At least one saved metadata instance must exist for a template before recommendations are generated. To fill out the metadata for a template with recommendations the user proceeds as for any other template:

• In the listing for the template, click on the ‘metadata’ tag (shown at right). This generates a form to fill out the metadata. Alternatively, select your template and click on the template options menu (displayed as three vertical dots), choosing “Populate” to start entering metadata for the template.
• Click on any field that is configured to support recommendations. You will receive a list of value recommendations presented as a drop-down.
• The numeric percentages indicate the strength of the recommendation (not the percentage of entries that are filled out with that value). See the paper cited below for details about how this strength is calculated.

If you do not see a list of value recommendations when you expect them, it is likely that the metadata filled out so far for that template does not contain any patterns strong enough to recommend.

Example

Suppose we have an “Experiment” template with three fields: (1) an “experiment ID” field that stores the identifier of the experiment; (2) a “tissue” field that captures the type of tissue tested in the experiment, and (3) a “disease” field to enter the disease of interest.

Fig. 1 shows the template in the Template Designer and the “Suggestions” setting for the field “tissue”. The user has clicked on the “tissue” field and enabled metadata recommendations for the field using the “Suggestions” tab.



We will assume the user also enables suggestions for the field “disease”.

Fig. 2 shows a screenshot of the Metadata Editor for a template generated from the Experiment template. The user entered the value “skin” for the field “tissue” and is about to enter a value for the field “disease”. In this case, the editor shows four suggested values: “skin ulcer”, “atopic dermatitis”, “melanoma”, and “psoriasis”. The percentage shown between brackets next to each suggestion represents the strength of the recommendation. The recommendations provided by the system are context-sensitive, meaning that the values predicted for the “disease” field are generated and ranked based on the value entered for the “tissue” field. In this case, the four values suggested by the system are useful, since all of them are diseases that affect the skin.

Frequently Asked Questions

Can I enable suggestions for text fields whose values have been restricted to terms from ontologies?

Yes. CEDAR’s Value Recommender works both for plain text values and ontology terms.

Can I access the source code?

Yes. The source code of CEDAR’s Value Recommender is open source and available on GitHub [3].

How does CEDAR’s Value Recommender work?

The system is based on a well-established data mining method known as association rule mining to generate real-time suggestions based on analyses of previously entered metadata. A paper describing this method in detail will be available soon.

Will recommendations still work if I modify the template after metadata is collected?

No, they will not. To modify a template with existing metadata, you must create a new template version. The recommendations for the previous template version will be applied to any metadata created from that previous template, and metadata for the new template version will be based on metadata created for that version.

Can I use recommendations based on metadata from other CEDAR templates?

Not yet, although we are investigating this as a possible enhancement.

What are the technologies behind CEDAR’s Value Recommender?

CEDAR’s Value Recommender has been implemented in Java. The system uses the Dropwizard framework [4] to provide a REST-based API that is used by the Metadata Editor and can also be used directly by third-party applications. The rule extraction process is performed using the Java API of the WEKA (Waikato Environment for Knowledge Analysis) data mining software [5]. All metadata for a particular template are transformed to WEKA’s ARFF (Attribute-Relation File Format). The association rules are extracted using the Apriori algorithm, which is commonly used in association rule mining.

How should I cite this work?

Please cite the following paper, which describes CEDAR’s Value Recommender in some detail:
Martínez-Romero M, O’Connor MJ, Egyedi AL, Willrett D, Hardi J, Graybeal J, Musen MA. Using association rule mining and ontologies to generate metadata recommendations from multiple biomedical databases. Database. Volume 2019, 10 June 2019. https://doi.org/10.1093/database/baz059.

References

[1] https://cedar.metadatacenter.org/
[2] https://valuerecommender.metadatacenter.org/api
[3] https://github.com/metadatacenter/cedar-valuerecommender-server
[4] https://www.dropwizard.io
[5] https://www.cs.waikato.ac.nz/ml/weka/

---




Updating and Versioning

As you build more complex templates, you will start using elements and want to update these in your template. Doing so can be a little subtle in CEDAR, especially when one wants to use rigorous version control. In this section, we describe working with CEDAR for these use cases.

Updating Fields and Elements

Once you create a template or element that has nested elements, you may find you need to update a lower-level element in your template. Because the elements are imported as static resources, this is a two-step process.

First, you must update the element that needs to be changed. (If it is a versioned resource, follow the instructions in the Creating and Managing Versions topic below.)

After saving your updated element, go to the template that contains it. Import the updated element as described in Adding Elements; the updated element will appear at the bottom of your form.

Move the element to the correct location in your form, and delete the element that is already there.

Repeat this process for each updated element that you want to include in the form. Also be sure to update any other forms that you want to have the updated element.

Updating Nested Elements

Because imported field and elements are static once imported, if you have multiple levels of nested elements and fields, you must start the re-import process with the lowest-level changes, making all changes at the lowest level before re-importing content at the next-highest level. For example, if Template A contains Element B which imported Field C, if you want to change Field C in the parent template you must first modify Field C, import the modified field into Element B, then import the modified element into Template A. If there are multiple items changing at a given level in an element, all those changes must be made before that element is re-imported into the parent element or template.

Creating and Managing Versions

CEDAR assigns a version number of 0.0.1 to every new templating artifact (templates, elements, and fields). You can modify these templating artifacts as often as you want, and the version number will not change. However, you should not modify a CEDAR template that already has instances; you will get a warning message if you try to do this.

Many users want more rigorous control over their artifacts, so that if the artifact is changed, everyone will be able to see the change has occurred. Similarly, users may want to keep older copies of the artifact, so they can compare different versions or look up particular versions that have been used in the past.

CEDAR uses a 3-number versioning system known as “semantic versioning”, in which trivial changes are delineated by the right-most number, minor changes (with relatively small impact on the overall system) are indicated by the middle number, and major changes are shown in the left-hand number. Each time release a new version, you can choose any version representing a higher version number. For instance, updating from version 0.0.1 you could choose 0.0.2 (or any 0.0.x where x is higher than 2), 0.1.y, or 1.y.z as your new version number, where y and z are any number.

Make Your Artifact Version-Controlled

To enable such control, CEDAR provides a versioning system for templating artifacts that is enabled by the Publish version menu item. When you select Publish version from an artifact’s kebob menu, you will be prompted for your desired version number for your versioned artifact.

Once you select the version and click Save, the artifact named by that version will no longer be modifiable, and you will see its version in Desktop resource lists.

Updating Versioned Artifacts

If you want to create a new version of your artifact, you must select Create version from the artifact’s dropdown menu, and a new, editable artifact will be created with the right-hand version number incremented by 1 from the previous artifact. We will call this a draft artifact, and it will automatically include metadata referencing the previous version as its predecessor.

You will be able to edit the draft artifact as much as you want, but when you are ready to put it under version control, you must repeat the Publish version process described above. Again you can set the version number to any larger sequence than the previously published artifact, including the same version as the draft artifact.

As suggested in Updating Nested Elements above, CEDAR templates and elements import lower-level artifacts in their entirety. Thus, later changes to the lower-level artifacts do not change the higher-level artifacts that import them; the lower-level artifacts must be re-imported. When new versions of elements or fields are created, you must follow the instructions in Updating Fields and Elements above.

The act of publishing an artifact does not change its IRI, even if a different version is selected than the draft artifact’s version.

Finding and Viewing Versioned Artifacts

When you create and publish new versions of templating artifacts, the previously published version is kept on the system, and can still be accessed. However, by default the Workspace and search tools will show only the most recent published version of an artifact. (If a draft version exists, that will always be shown.)

This behavior is controlled by the Version drop-down in the Filter section on the left side of the CEDAR Workspace.
In a typical configuration, the Version drop-down is closed, as shown to the right.

If you open the Version drop-down, you will see a Latest indicator, with a darkened checkbox indicating that viewing the Latest version only is enabled. Search results and other listings will not show older versions.

To see all versions, click on the Latest item to disable the Latest filter. Now, all versions will be shown in any search or folder display that contains them.

Seeing and Navigating to All Artifact Versions

The version history for any artifact is shown in the Version tab of the metadata panel (see image on the right). (Click on the ‘i’ icon to make this panel visible; see Viewing Resource Details for more information.)

In the metadata panel example, you can see the three versions of the Version Test artifact. The Version tab shows all the versions available for the selected artifact, no matter the setting of the Version drop-down in the Filter section. The world icon indicates the artifact is published; an artifact without that icon is a draft.

To open any of the versions listed in the metadata panel, click on that version’s title (“Version Test”) in the list. The Template Designer will be opened with the appropriate version of the artifact. There can be only one draft version open for any published artifact, and that draft version is always more current than any of the published versions of that artifact.

---




Working with CDEs

CEDAR contains nearly 60,000 Common Data Elements imported from the National Cancer Institute’s caDSR Data Element repository. These are represented as Fields in CEDAR, as each CDE describes a single question and its possible answers.

Because all of these CDEs are managed by caDSR following the same metadata model, we can offer some tips for working with them efficiently in the CEDAR system.

Finding and Browsing CDEs

The same practices used for finding other CEDAR resources will work with CDEs as well. However, there are a few additional strategies that may be particular helpful for those working with CDEs in CEDAR on a regular basis.

Searching from the CEDAR Desktop

As described in the section Finding Resources you can search for resources by name or description. In the case of CDEs, it is also possible to search by their CDE identifier. This number is shown at the top middle of the CEDAR field in the Template Editor (or between parentheses in a Desktop resource list).

For very short version numbers (like ‘5’ or ‘58’), the indexing does not provide an obvious way to find the whole number, instead finding all the numbers containing that string. As a workaround, you can enter the number surrounded by spaces, and within quotes. This may find other occurrences of the number by itself, for example in the description of the CDE. You can then search within the results set in your browser by scrolling the results until they are all displayed, then enter into your browser your identifier surrounded by parentheses (e.g., (5)).

Another handy attribute for some searches is the version attribute. Entering the exact version number will find all artifacts with that version, most of which will be CDEs. Entering version numbers with wildcards can find many CDEs at once; for example, *0.0 will find all CDEs (and other artifacts) with version numbers ending in 0.0.

Browsing All CDEs

If you search for the string “CDE” from the Desktop, one of the first entries you’ll see is the shared CDE folder. This is the location of all the imported CDEs from caDSR.

Double-click on the CDE folder to open it. You must wait a while (10-15 seconds) before the first screen of CDEs is displayed.



You will quickly discover that navigating through this list isn’t practical, as only a small number can be presented at any one time. Instead, use the search bar to narrow down the list, as described above.

Browsing by CDE Categories

In caDSR, CDEs and forms can be classified using Classifications, more specifically Classification Schemes and Classification Scheme Item. The caDSR classifications have been imported into CEDAR as hierarchical categories under the NCI caDSR category, as shown in the image on the right.

You can find CDEs in a particular category by using the CEDAR categories menu in the left-hand navigation panel. Selecting an item at any level of the category hierarchy will show all the CDEs contained within that level, and all lower levels.

You can view the Category or Categories for any CDE you see in the Desktop by clicking on the CDE, bringing up the information metadata tab, and selecting the Categories tab. CEDAR lists all the Categories to which the selected CDE belongs.

When Creating a Template

On bringing up the search pop-up display, searching results should be the same as when searching from the CEDAR Desktop. The returned results list is somewhat shorter, so searching using the identifier is the best approach.

Advanced: Search for Templates Using A CDE

If you are trying to find all the templates (or instances) that are using a particular CDE, you could try using the field name of the CDE if it is relatively uncommon. By using the Advanced Searching—Field Names strategies, you can search by the name of the field for templates and/or instances containing that field. (You must use the actual name of the field, not the displayed label.)

Obtaining and Maintaining CDEs

By importing the XML-defined CDEs from the caDSR system into JSON Schema-defined fields in CEDAR, we make these specifications available to any CEDAR user. CEDAR imports only the released CDEs, not those in earlier stages of preparation. To date the conversion process is manually initiated, but we plan to run conversions as frequently as nightly to keep the CEDAR CDEs up-to-date with respect to the source content.

When run, the conversion process updates any caDSR-updated CDEs in the CEDAR system, replaces all the CDE Value Sets in BioPortal, and ensures that the Categories in CEDAR are updated to the Classifications provided in the caDSR export.

We do not manage the entire content of the CDE specification. CDEs in caDSR contain a comprehensive implementation of the ISO/IEC 11179 standard, but focus instead on core functionality that relates to the precise specification of questions and the values used to answer those questions.

References

These references provide more information about performing CDE-related activities.

• CEDAR for caDSR Users—a separate section of this manual targeting users of caDSR systems
• CEDAR Announcement of CDE Support—Blog post describing CEDAR’s support for CDEs Unleashing the value of Common Data Elements through the CEDAR Workbench. Published in Proceedings of AMIA 2019 Annual Symposium, 681-690.

---

Tips for Template Creation [Pending]

About Template Compatibility

We’re sorry, this resource has not yet been developed. You are welcome to contribute to its development at the link below.

---




Composition

We’re sorry, this resource has not yet been developed. You are welcome to contribute to its development at the link below.

This will cover the best ways to build composable templates, in which elements can be combined in various combinations in different templates.

---




Recipes for Filling Out Everything (Titles, Field Names, Descriptions, Help Text)

We’re sorry, this resource has not yet been developed. You are welcome to contribute to its development at the link below.

Titles

enough to mostly differentiate, but within small footprint (reference earlier tips)

Field Names and Preferred Labels

internal vs external

Descriptions

enough detail to matter

Help Text

as complete as possible

---




Term Discovery/Selection

We’re sorry, this resource has not yet been developed. You are welcome to contribute to its development at the link below.

Will be just tips, in addition to those already provided in the detailed guide Choosing Controlled Terms

• prefill the label effectively

• look up related terms in BioPortal

• use tree to explore

---

CEDAR Identifiers and IRIs

Browser Address URLs in CEDAR

When you run CEDAR, the first page you see will be your Workspace home page, and the top of your browser may look something like this:



The bar at the top of the browser shows part of the IRI describing CEDAR’s location. Here we describe how to read these IRIs (also known as URLs), so that you can use parts of it in the rest of this section.

Workspace Home Directory IRI

When you log in for the first time or go to your home directory, the URL in the browser will be like the following:

https://cedar.metadatacenter.org/dashboard?folderId=https:%2F%2Frepo.metadatacenter.net%2Ffolders%2F4036e319-5bb7-493f-8fe5-31a004f65a94

The first part of this is straightforward: https is the protocol, cedar.metadatacenter.org is the path for the application, and dashboard is the application type that is presenting the content.

After the dashboard you will usually see the query character ? followed by folderID=. This means that the following string will be the (encoded) unique identifier of the location that the CEDAR Workbench is displaying. If you’ve just logged in, this will identify your own home folder.

You’ll notice that the identifier has a number of escape characters, usually just %2f for a slash in this case. You are seeing an encoded version of the identifier. You can see the actual identifier by passing this string through an encode-decode site (e.g., https://www.url-encode-decode.com) and asking to decode the string. Doing so for this string results in the identifier

https://repo.metadatacenter.net/folders/4036e319-5bb7-493f-8fe5-31a004f65a94

which is the actual unique identifier for the viewed location.

Template Creator or Metadata Editor IRI

If you open an existing template, you’ll see an IRI like

https://cedar.metadatacenter.org/templates/edit/https://repo.metadatacenter.org/templates/4595e3d3-b0c5-467b-a967-fec870801624?folderId=https:%2F%2Frepo.metadatacenter.org%2Ffolders%2Feaa65a39-1706-43b6-b4ca-2bf9d7d1166d

Breaking that down, we’ve replaced dashboard?folderID= in our previous example with template/edit/, which tells us we are in the template editor. (For a metadata instance, we would see instances/edit/, and if we were just creating an instance for the first time, instances/create/.)

Everything that follows the template/edit/ string, until reaching the ?, is a template identifier:

https://repo.metadatacenter.org/templates/4595e3d3-b0c5-467b-a967-fec870801624

That is the unique identifier that you will see inside the template as its own ID.

Then we see the ?folderID= string again. In this case the following string indicates to what page in your Workspace CEDAR will return to after leaving the template editor; it is the (encoded) IRI of the folder to which CEDAR will return. That will usually point to the previous non-search page you saw before entering the template creator. But if someone sent you the IRI from their browser, it will try to return you to the previous non-search page in that session. (If it fails because you don’t have permission to see that page, it will return to your workspace homepage.)

---




Building Shareable Metadata Creation IRIs

Building on the other sections in this chapter, we briefly describe how to create an IRI that will launch a fresh appropriate metadata creation form for your template.

Given a template IRI, you can preface it with the metadata creation IRI base, which is https://cedar.metadatacenter.org/instances/create/. So if your template looks like https://repo.metadatacenter.org/templates/f7d62955-ed10-4912-b4db-1b366ad4ff00 (not a real template!), you would get an IRI (URL) like https://cedar.metadatacenter.org/instances/create/https://repo.metadatacenter.org/templates/f7d62955-ed10-4912-b4db-1b366ad4ff00 (entering this won’t do any good because that wasn’t a real template).

When such an IRI is clicked or put into the browser, it would launch CEDAR, log in (or create account for) the user if necessary, and put the user into a new metadata creation form for that template.

Because there is no ‘return folder’ specified in this URL, when the user saves the created metadata, it will be put into his or her home folder, and the user will be returned to that folder. If the user will have write access to a particular folder where this metadata should go, appending the folderID (with ?folderID=and the encoded ID of the target folder) will result in the saved metadata going into that folder.
(However, in that case the user may not realize how that happened or how to return to it, so this approach should be used with caution.)

---




How CEDAR Defines and Applies IRIs (URIs, URLs)

This page describes the CEDAR unique identifier format. The advanced user may wish to consult the CEDAR Template Model Specification for more information.

A CEDAR artifact has a unique identifier that is of the following form: https://repo.metadatacenter.org / [type] / [UUID]

Here, type can be any of template-instances, template-fields, template-elements, templates, or folders. A UUID is a unique 36-character string with 4 hyphens embedded, as in the following: 4595e3d3-b0c5-467b-a967-fec870801624 .

These IRIs are not directly resolvable, but can be plugged into one of the following forms to try to resolve them:

• Folder: https://cedar.metadatacenter.org/dashboard?folderId= followed by the encoded IRI
• Template: https://cedar.metadatacenter.org/templates/edit/ followed by the IRI
• Element: https://cedar.metadatacenter.org/elements/edit/ followed by the IRI
• Field: https://cedar.metadatacenter.org/fields/edit/ followed by the IRI
• Metadata Instance: https://cedar.metadatacenter.org/instances/edit/ followed by the IRI

CEDAR users also have unique identifiers, which are encoded in any artifact that the user creates or updates. These are of the form https://metadatacenter.org/users / [UUID]

CEDAR metadata instances also create another kind of template-element-instance identifer, but these are not of practical use to anyone using the CEDAR user interface.

---

CEDAR's API

API—About Swagger Documentation

API: About Swagger Documentation

Overview

When you first enter the Swagger API documentation for CEDAR, you will see a list of API interface categories. Some of these categories overlap; in particular the Search interface is similar across multiple resources.

If you click on any category, like Template Instances, you will see all the API methods available for that category. These follow the typical REST pattern:

• DELETE: removes an entity of that type
• GET: retrieves an entity or information about one or more entities
• PUT: updates an existing entity
• POST: creates an entity of that type

There can be multiple interfaces of the same type, for example multiple GET interfaces, but each of these must have a different name. (Interfaces of different types, like a GET and a PUT, can have the same name and even the same signature.)

You can view all the CEDAR documentation in this Swagger page. When you have located the interface you want to use, if its documentation isn’t visible, click on the interface’a header line to expand the documentation for that interface. You will then see the documentation details, including a section called Parameters. If you fill out the parameters in the form and then click on the Try it out! button, the Curl and Request URL patterns will be completed for you to examine and try for yourself.

At this point the API request also will be sent to CEDAR. If you haven’t entered your API key, though, the first meaningful line of the response will say "status": "UNAUTHORIZED", and no useful information will be returned.

Using Swagger to submit CEDAR requests

To use CEDAR’s API resource documentation to make CEDAR requests as we describe in this Guide, you must enter your API key to the documentation interface. To obtain your API key, reference the CEDAR’s API documentation.

In the upper right section of any API’s documentation, just under the summary description of the API method, you will see a red circle with a white exclamation point. This indicates the API key has not been verified.

Click on this red circle and you will be prompted to enter your API key. Use the format described in the written notes (apiKey <yourApiKey>), not the format that you see in the value box (api_key). Then click on the Authorize button. If your API key is authorized, the red circle will turn blue.

Now, clicking on the Try it out! button will actually send the request to CEDAR, and you will be able to see the response in the field under the Response Body section header.

Your API key will continue to be active for any of the other API interface methods in the documentation page, until you close or leave the page.

Now you can use the examples in the next section to begin trying your own CEDAR interface tests.

---




API—Finding and Accessing Metadata Instances

There are several API methods that can find and return metadata instances. Note that in the API, metadata instances are called Template Instances (template_instance in the method names). The API refers to an actual CEDAR template as a Template, though some might call it a ‘template instance’. We apologize for this semantic hiccup.

We cover a few of the most useful API methods for finding and obtaining CEDAR metadata instances in this page. These same patterns and methods will also apply to searching and obtaining metadata templates and elements.

Overview

CEDAR offers a number of search methods that can return metadata instances. Most of these return, for each discovered metadata instance, the description of the instance (in other words, that instance’s metadata). To obtain the actual metadata (values) contained in one of those instances, you need to make a request for the specific instance using its instance identifier.

Search Methods

When performing searches via the API, just like searches in the UI, you will only find artifacts to which you (identified by your API key) have access. You must ensure the metadata artifacts you want searchable are visible to the people or groups you need to find and access them— either by explicitly giving those people or groups access to the artifacts, or by giving Everyone group access to the artifacts, or by putting the artifacts into a folder visible to those people, those groups, or the Everyone group.

CEDAR administrators can arrange for all the artifacts of a particular template to be visible to a particular group, contact us at cedar-support@metadatacenter.org to make that request.

This document describes one example in each section. To learn how to perform more detailed searches or searches for other entities, simply review the appropriate Swagger forms and enter parameters you are interested in. Swagger provides Curl and Request URL equivalents for any given search configuration.

Finding metadata instances in CEDAR

To get a list of the identifiers and metadata of all the metadata instances you have access to, you can use the Search GET method.

To perform this search In the Swagger documentation, simply specify the resource_types as ‘instance’, and click the Try it out! button toward the bottom. With the default settings, you should see the first 100 Instances that you have access to listed in the Response Body in JSON format.

To execute the same search in a curl request from a Unix or Linux command line, your command will look like this, substituting your API key as described in the overview:

curl -X GET --header 'Accept: application/json' --header 'Authorization: apiKey ' 'https://resource.metadatacenter.org/search?version=all&publication_status=all&is_based_on=https%3A%2F%2Frepo.metadatacenter.org%2Ftemplates%2F5bf8d2bf-2f1c-4d77-a399-a2222157d894&sort=name&limit=100&sharing=null&mode=null'

Finding instances of a particular parent template

To find the set of metadata instances that have a particular metadata template as their parent, you will use the Search GET method.

The Search method has many parameters, but the key parameter for this command are is_based_on, which specifies the parent template’s template identifier, and resource_types, which must be left blank. (It is required in every other search request except this one.)

When you put this command and your template identifier into a curl request that you can run from your Unix or Linux command line, and you add a pretty-printing command so that your instances descriptions are easily viewed, you obtain something like the following

curl -X GET --header 'Accept: application/json' --header 'Authorization: apiKey YOUR_API_KEY' 'https://resource.metadatacenter.org/search?version=all&publication_status=all&is_based_on=https%3A%2F%2Frepo.metadatacenter.org%2Ftemplates%2F5bf8d2bf-2f1c-4d77-a399-a2222157d894&sort=name&limit=100' | /usr/local/prettyprint

Retrieval Methods

To retrieve a metadata instance, you will use the Template Instance GET method. This method has two parameters: the template_instance_id (the instance_identifier mentioned earlier), and the desired format.

Getting the template using its instance identifier

The template_instance_id should look very similar to the following: https://repo.metadatacenter.org/template-instance/8bc64ab5-df6b-48c8-8c61-6c016245918e The final 32 characters are the unique part of the string.

When this is put into a curl request that you can run from your Unix command line, and a pretty-printing command is added, you obtain something like the following:

curl -X GET --header 'Accept: application/json' --header 'Authorization: apiKey YOUR_API_KEY' 'https://resource.metadatacenter.org/template-instances/https%3A%2F%2Frepo.metadatacenter.org%2Ftemplate-instances%2Ffb8f0a9c-8ded-4d31-9d92-fb780ff6b4df?format=jsonld' | /usr/local/prettyprint` 

Requesting specific formats

Use the format parameter to request the format you want. CEDAR offers three formats:

• json-ld: JSON-Linked Data, the default internal storage format
• json: Plain JSON, similar content to json-ld but with most of the LD-specific identifiers removed (this specifically removes the semantic identifiers, which is a significant reduces the precision of the metadata)
• rdf: Resource Description Framework, with the same content as the JSON-LD but expressed as RDF n-quads.

The RDF format should be importable by most triple stores and semantic repositories.

An example of the above call with an RDF-formatted instance returned:

curl -X GET --header 'Accept: application/json' --header 'Authorization: apiKey YOUR_API_KEY' 'https://resource.metadatacenter.org/template-instances/https%3A%2F%2Frepo.metadatacenter.org%2Ftemplate-instances%2Ffb8f0a9c-8ded-4d31-9d92-fb780ff6b4df?format=rdf' | /usr/local/prettyprint` 

---




API—Using Google Sheets

API: Using Google Sheets

You can also query CEDAR’s API using a Google sheet library developed by the CEDAR team. As with the other parts of this chapter, to see the library function, you will have to have your CEDAR API key as described in the CEDAR’s API documentation.

Using the Google Sheet

To use the Google sheet library, or even to just inspect it, visit the Example CEDAR Data Lookup in Google Sheets document. This is a publicly viewable Google spreadsheet that contains the libraries that can be used to interrogate CEDAR.

The first tab has README documentation for this spreadsheet, while the second tab has an Example spreadsheet you can inspect. As you will see, this read-only spreadsheet shows #ERROR in two of its cells. Examining the error message in either cell reveals the request failed with status of UNAUTHORIZED. To see the spreadsheet work, you have to make your own copy of it, and modify the script associated with the Example tab to enter your API key.

Instructions for performing these steps are on the README tab of the Google sheet. Once you follow them correctly, you should see the cells change from #ERROR to the creation date and title of the CEDAR instance, because that instance is shared for any CEDAR user to see.

Advanced considerations

Arbitrarily advanced lookups can be performed in CEDAR metadata instances using the XPath-compatible data_path expression in the second parameter. These allow you to access the nested hierarchy in the metadata template, as well as index into multiple entries for a given field or element. (Unfortunately, describing the details of those expressions is beyond the scope of this help text.)

There are two limits to the scope of this capability. First, if you have a lot of requests being made in your spreadsheet, for example because you have lots of rows of instances with many field values being requested in the columns, it will complete the fields rather slowly. You may have to wait for the complete sheet to fill out.

Second, Google limits the number of requests that can be made in a given period of time from their sheets. So large numbers of requests being repeatedly made may create a rate limit error, and you will have to resume your work at some later time or reduce the number of requests in a given sheet.

---