Dataset Schema Concepts - dsriseah/ursys GitHub Wiki

Work in Progress

The upcoming property editor work required refactoring NetCreate's template-schema code into distinct concerns.

I've defined a YAML-based file structure that declares:

  • a base schema, declaring types and enums and named groups of named properties
  • an auxiliary base schema that declares collections of the same type of object with named properties
  • UI/layout metadata that describes how to render a particular property or collection object

The actual values are stored in separate files that use the above schema to validate them.

  • values of named properties in a group, using base property schema to validate
  • values of UI layout metadata, using layout metadata schema to validate
  • values of collection objects, using base type schema to validate
'base-types-comment',    # type declarations for comments
'base-values',           # dicts of support types
'base-controls',         # dicts of supported ui controls
'props-proj-meta',       # prop declarations
'props-proj-pacl',       
'props-proj-settings',
'props-citation',

# derived from base, props
'layout-edge',           # ui layout metatdata
'layout-node',
'layout-proj',           
    
# derived from base, props
'values-comment-prompts' # stored values

Only the values files are managed by the property editor, and these values are stored separately from programmatically-defined defaults.

Property Examples

Not shown: The TypeDefs and UI_* dictionaries are developer-defined base types. The following are app- and project-specific files that are intended for customization by end users. Developers will have to set up the customization by modifying the schema and implementing the code to use it.

Property Definition Example

These files are stored in the app-templates or similar folder. They define groups and the types of properties in them, but do not store the runtime values that are modified on a per-project basis.

# metadata
_schemaVersion: '2.0'
_key: PropertyDefs

# Defaults for project metadata
projectMeta:    # the top level key is the group name
  description:  # the 'description' prop just has a type and default value
    type: string
    default: 'Project Description'

# Global default permissions for the running application
permissions:
  requireLogin:
    type: boolean
    default: false
  hideDeleteNodeButton:
    type: boolean
    default: false
  allowLoggedInUserToImport:
    type: boolean
    default: false

Property Settings Example

These would be stored in the runtime datasetURI directory for a particular project instance. They just need to contain the actual values, which are validated by the property definitions.

# metadata
_schemaVersion: '2.0'

projectMeta: 
  description: "This is a frog simulation"

# note a user project doesn't get to set the permissions properties
# so they aren't here

Collections of Objects Examples

This is a WIP

Collection Object Definition Example

# metadata
_schemaVersion: '2.0'
_key: TypeDefs

# this declares the data structure of a "comment type"
# the actual stored values are in 'set-ui-comment-types.yaml'

# declare complex types (PascalCase)
CommentType:
  type: object
  slug.type: id
  label.type: string
  prompts:
    type: object
    format.type: string
    prompt.type:: string
    help.type: string
    feedback.type: string

Comment Object Collection Example

The actual values that are loaded at runtime

# metadata
_schemaVersion: '2.0'

# Default comment types made available in the comment manager
# The intent of this seems to be a collection of prompts used
# to provide a commenting template for students in the dialog box

# this is a list of two objects of type CommentType, which is
# declared in 'declare-ui-comment-types.yaml'
commentPrompts:
  - slug: 'cmt'
    label: 'Comment'
    prompts:
      - format: 'text'
        prompt: 'Comment'
        help: 'Use this for any general comment.'
        feedback: ''
  - slug: 'tellmemore'
    label: 'Evidence Critique or Suggestion'
    prompts:
      - format: 'text'
        prompt: 'Tell me more'
        help: 'Can you tell me more about ... '
        feedback: ''

Extensions

There are special metaproperty keys that begin with an underscore:

  • _schemaVersion specifies a string that all files must match
  • Optional _key specifies that the following properties are all to be stored in this key. The values currently specified are TypeDefs, PropertyDefs, and LayoutDefs.
  • _groupMeta is used when the collection itself needs description independent of its properties

IN THE FUTURE:

  • It may be necessary to add annotations like _typeof inside values dictionaries