© 2020 Center for Expanded Data Annotation and Retrieval
CEDAR was supported by the National Institutes of Health through Big Data to Knowledge Grant Number 1U54AI117925.
Website developed by Maulik R. Kamdar || Designed using a Minimalistic Ed Jekyll Theme





Accounts and Logging In

Last updated

This first chapter in the CEDAR manual provides a basic understanding to the reader regarding how to create a user account on the CEDAR Workbench, how to access the account, and how to access the different resources in the CEDAR Workbench.


    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.

    alt text



    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

Last updated

This chapter of the CEDAR manual describes how to find different resources—any template, element, field, instance, or folder) in the CEDAR Workbench. It also includes descriptions of filtering and sorting the retrieved results, and formulating advanced queries.


    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 vey 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.

    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

Last updated

This chapter describes how you can examine and understand resources in the CEDAR system. CEDAR resources can be viewed within the user interfaces you use to work with them, but also in their raw format, as well as on the web when shared in OpenView.


    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

Last updated

These sections describe how you can move around the CEDAR system, particularly moving among the different tools and Desktop display modes.


    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.

    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

Last updated

While CEDAR is intended to be used without any special knowledge, this chapter provides details about creating metadata using CEDAR processes. In each section the information includes both basic instructions, and more detailed information for advanced users.


    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).

    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:

    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 the Format icon (that shows a 3-item list). 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 is only visible if the element just contains fields. If the element contains other elements, viewing and editing it as an array is not possible.

    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 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

Last updated

CEDAR provides multiple content-sharing techniques, with advanced group and permission management for its artifacts, as well as a web sharing service called OpenView. This section describes how to use these features to make your CEDAR information available to the people you want to access it.


    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

CEDAR’s Metadata Template

In CEDAR, forms are created as what we call Metadata Templates, or just ‘templates’. The templates contain individual questions—what we call Metadata Fields, or ‘fields’—and collections of those fields called Metadata Elements (‘elements’).

In this chapter we provide a basic information about CEDAR Metadata Templates, including what they contain and how they are organized.


    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

In this chapter, we show you how to build a basic Metadata Template by combining other templating resources (Fields and Elements) within the CEDAR Workbench.

The component templating resources can be shared with other users, published on the Web as JSON Schema, and reused within other Metadata Templates and Elements.

And of course, the completed Template generates the metadata form interfaces for metadata authors to fill out with rigorous semantic metadata.


    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.

    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]

The principles of FAIR metadata—Findability, Accessibility, Interoperability, and Reusability— are useful to understand metadata good practices. We made semantics a key technology in the CEDAR system, because semantics support all of the principles that make up FAIR metadata.

In this chapter we describe how the semantics in CEDAR make its templating resources more FAIR, and thereby make CEDAR metadata more FAIR. By understanding how CEDAR’s semantics contribute to FAIR metadata, you will learn how to make metadata based on your templates more findable, accessible, interoperable, and reusable.


    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 - Dynamic Lists

    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:

    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. Even the addition of Values and Value Sets uses BioPortal to store those concepts. 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

    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 and Value Sets

    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

    Adding your Own Single Term(s)

    Composing a List of Terms

    Customizing What You Have

    Rejecting Terms

    Putting Favorites First



    Choosing Controlled Terms

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

    General Introduction

    familiarity helps

    perfect terms or lists, like perfect software tools, can be elusive

    What Makes a Term Better?

    Naming

    The Order of Things

    Structure and Definition

    Parentage

    Finding a Better Branch

    Finding Branches Fast

    Likely Branch Names

    Starting Lower Down

    Whole Ontologies

    Serendipity

    Browsing (BioPortal)

    Finding the Best Ontology: BioPortal’s Recommender

    Browsing (Everywhere)



    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]

CEDAR Metadata Templates—all CEDAR templating resources—are really modeling tools. These tools define what information is important to collect, what that information means (in terms a computer can understand and analyze), and how that information is organized and internally connected.

In this chapter we describe how you can use CEDAR to achieve common design goals. We review common patterns like metadata profiling and extensions, versioning your metadata models, and versioning the vocabularies you want to use. And we present details about our value suggestion (“Intelligent Authoring”) system so that you can decide exactly where suggestions are most appropriate in your forms.


    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)Metadata Tag. 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.







Tips for Template Creation [Pending]

In this final chapter on building templates, we offer handy tips to make your Metadata Templates easier to build, work with, and understand. If you are building templates to collect important metadata, lots of metadata, or metadata that will be heavily analyzed, you’ll want to master the tips in this section!


    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

In this advanced topic we cover everything you might want to know about the unique identifiers used in CEDAR. The first section provides an introduction to the CEDAR-specific terms and concepts used throughout the chapter. In the overview below we introduce you to a few key terms.

Introduction to IRIs, URLs, and similar identifiers

Most people are familiar with the term URL, for Uniform Resource Locator. These are the web page identifiers you put into the browser to arrive at a web page. Sometimes we would use the term URI, which referred to any Uniform Resource Identifier—some of them weren’t URLs, but even the URLs did not strictly have to be resolvable and could be used as identifiers.

The URL has been replaced by a newer standard, called an IRI, for Internationalized Resource Identifier. These can contain international characters and often resolve to web pages (when they begin https://) but like URLs, they do not have to be resolvable to serve as a unique identifier.

Throughout our manual, we usually refer to our CEDAR identifiers as IRIs, and will typically use URL to refer to a web address you’d put in your browser. But it’s useful to understand that all of the identifiers and locators we are referring to are both IRIs and URLs.


    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

    
    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.

    When this 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, (though the user may not realize how that happened or how to return to it).



    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.




-->