This is the codeAbility Sharing Platform! Learn more about the codeAbility Sharing Platform.

Skip to content

Changes

Page history
Update Metadata Version 0.5 Documentation authored by Daniel Bastta's avatar Daniel Bastta
Hide whitespace changes
Inline Side-by-side
Metadata/Metadata-Version-0.5-Documentation.md 0 → 100644
View page @ 3d54202d
_Updated for v0.4.2_
_identifier deprecated_
_Updated for v0.5_
This page is intended to convey the meaning of the attributes in the meta data files.
Each repository in the `sharing` group on `sharing-codeability.uibk.ac.at` should have a metadata file. This is a file called `metadata.yaml`, `metadata.yml`, or `metadata.json` in the repository's root directory. `metadata.yaml` and `metadata.yml` must contain valid YAML syntax, `metadata.json` must be valid JSON. The different formats are provided for convenience and support the same functionality.
The encoding of the metadata file should be UTF-8.
Metadata is specified in the form of key-value pairs. Keys may only occur once in a metadata file. The allowed keys are listed below. The type a key's value depends on the key. In some cases it is a single value, in others it is a list. The **following attributes** are **mandatory**:
- [`metadataVersion`](#metadataversion)
- [`title`](#title)
- [`description`](#description)
- [`keyword`](#keyword)
- [`creator`](#creator) on top level of a collection
- [`publisher`](#publisher) on top level of a collection
- [`license`](#license) on top level of a collection
- [`language`](#language) on top level of a collection
- [`format`](#format)
- [`learningResourceType`](#learningresourcetype)
([`teaches/assesses`](#teachesassesses) could be added later on)
Some attributes are only _mandatory on the top level of a collection_, these attributes are inherited down to exercises contained in subfolders, if not overwritten there.
The remaining ones are optional and can be used to provide extra information. It is encouraged to also fill in the optional attributes. For more details, see the description of the individual attributes. For each attribute, an example how it should look in the metadata is provided. The format used in these example is YAML, if you use JSON the syntax is different.
If you have content in a repository which is not easily describable with a single metadata file, [collections](#collections) might be useful.
[[_TOC_]]
# GENERAL INFORMATION
## metadataVersion
A string which is fixed to `0.5` in the current version. (CA)
The version may evolve over time. We will try to provide aids to upgrade the meta data automatically.
- Type of the value is `String`.
- The format of the value is unspecified.
- Example:
```yml
metadataVersion: "0.5"
```
## public visibility
An entry that defines public viewing of parts of the exercise. Contains a sub element {except:} that defines all elements that should not be viewable by the public users. (CA)
- Example:
```yml
publicVisibility:
except:
- "solution"
```
will allow to download all files and folders, except for those which path starts with {solution}.
If the path start with "/", it must start at the root of the exercise (or the git project). Otherwise it can match any path.
An exception path can be also a pattern, see e.g. https://ant.apache.org/manual/dirtasks.html). For example **/solution to exclude all solutions directories.
## title
A name given to the resource. (Dublin Core)
Just a nice title. Will be the most visible attribute of your contribution.
- Type of the value is `String`.
- The format of the value is unspecified.
- Example:
```yml
title: "This is my free title"
```
## description
Description may include but is not limited to: an abstract, a table of contents, a graphical representation, or a free-text account of the resource (Dublin Core).
A one or two sentence synopsis of your contribution. Will be displayed as a summary.
- Type of the value is `String`.
- The format of the value is unspecified.
- Example:
```yml
description: "This is my free description"
```
## keyword
Words or phrases describing the topic of the resource. (IEEE LOM - CA specific)
A list of keywords, helping to find and describe your contribution. It is recommended to choose from the list of suggested keywords, however, you can also describe with any keyword you like.
The list of suggested keywords/tags can be found [here](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/-/wikis/technical/Metadata-Version-0.5-values).
- Type of the value is a `list of Strings`.
- The format of the value is unspecified.
- Example:
```yml
keyword:
- "Arrays"
- "For loops"
```
# INFORMATION REGARDING AUTHOR AND LICENSE
## creator
The author of the resource, the person responsible for the learning resource or the person that put the tasks together (Dublin Core)
- Type of the value is a `list of Mappings`. The Mapping consists of the 3 keys ("name", "affiliation" and "email") and `String` values.
- The format of the values is unspecified.
- Example:
```yml
creator:
- name: "Stefan Podlipnig"
affiliation: "TU Wien"
email: "Stefan.Podlipnig@tuwien.ac.at"
```
## contributor
A person responsible for making contributions to the resource (e.g. content, correction, etc.). (Dublin Core)
- Type of the value is a `list of Mappings`. The Mapping consists of the 3 keys ("name", "affiliation" and "email") and `String` values.
- The format of the value is unspecified.
- Example:
```yml
contributor:
- name: "Daniel Bastta"
affiliation: "TU Wien"
email: "Daniel.Bastta@tuwien.ac.at"
- name: "Andreas Merckel"
affiliation: "TU Wien"
email: "Andreas.Merckel@tuwien.ac.at"
- name: "Kerstin Limbeck"
affiliation: "TU Wien"
email: "Kerstin.Limbeck@tuwien.ac.at"
- name: "Konrad Klier"
affiliation: "TU Wien"
email: "Konrad.Klier@tuwien.ac.at"
```
## publisher
The person who uploaded the resource. (Dublin Core - CA specific)
- Type of the value is a `list of Mappings`. The Mapping consists of the 3 keys ("name", "affiliation" and "email") and `String` values.
- The format of the value is unspecified.
- Example:
```yml
publisher:
- name: "Stefan Podlipnig"
affiliation: "TU Wien"
email: "Stefan.Podlipnig@tuwien.ac.at"
```
## license
The license under which the learning resource is provided. A literal value that identifies the license may be provided. (Dublin Core)
We currently recommend `CC-SA-BY 4.0`.
- Type of the value is `String`.
- The format of the value is unspecified.
- Example:
```yml
license: "CC BY-SA 4.0"
```
# INFORMATION REGARDING THE LEARNING RESOURCE
## subject
University module/school subject, for which the resource is intended. (Dublin Core - CA specific)
- Type of the value is a `list of Strings`.
- The format of the value is unspecified.
- Example:
```yml
subject:
- "TU Wien: Introduction to Programming 1"
```
## language
The language of the resource. (Dublin Core)
- Type of the value is a `list of Strings`.
- The format of an entry is an ISO 639-1 code.
- Example:
```yml
language:
- "en"
```
## programmingLanguage
For programming exercises, the language used in the learning resource must be specified here. (CA)
- Type of the value is a `list of Strings`.
- The format of the value is unspecified.
- Example:
```yml
programmingLanguage:
- "Java"
```
## difficulty
The difficulty level of the exercise/learning resource for the intended target [`audience`](#audience). (IEEE LOM - CA specific)
- Type of the value is `String`.
- The format of the value is unspecified.
- Example:
```yml
difficulty: "easy"
```
## timeRequired
Approximate or typical timerange it takes to work with or through this learning resource for the intended target [`audience`](#audience). (LRMI)
- Type of the value is `String`.
- The format of the value is unspecified.
- Example:
```yml
timeRequired: "15-30 min"
```
## format
The file format of the resource. (Dublin Core)
- Type of the value is `List of String`.
- The format of the value is the file extension without a leading dot. This can also be used for other technical formats, such as marking an exercise which can be imported into Artemis by adding the list entry "artemis". Do not use this to specify programming languages used in the content, use [programmingLanguage](#programminglanguage) instead.
- Example:
```yml
format:
- "md"
- "artemis"
```
## requires
A related resource that is required by the described resource to support its function, delivery, or coherence. (Dublin Core)
- Type of the value is a `list of String`.
- The format of the value is unspecified.
- Example:
```yml
requires:
- "Java12"
```
## learningResourceType
The predominant learningResourceType or kind characterizing the learning resource. For example, 'Presentation/lecture', 'Handout'. (LRMI)
- Type of the value is `String`.
- The format of the value is unspecified.
- Example:
```yml
learningResourceType: "Educational video"
```
## audience
The education level of the students, e.g. "Advanced Beginner", "Expert", etc. (Dublin Core - CA-specific)
- Type of the value is `String`.
- The format of the value is unspecified.
- Example:
```yml
audience: "Expert"
```
## teaches/assesses
The item being described is intended to help a person **learn** the competency or learning outcome defined by the referenced term. (LRMI)
- Type of the value is a `list of Strings`.
- The format of the value is work in progress.
- Example:
```yml
teaches/assesses:
- "Object oriented programming/Interfaces"
```
## isBasedOn
A resource from which this work is derived or from which it is a modification or adaption. (LRMI)
- Type of the value is a `list of Strings`.
- The format of the value is unspecified.
- Example:
```yml
isBasedOn:
- "If001"
```
## structure
WARNING: This field is ignored.
Intended to describe the structure of the content. Repositories which are not [collections](#collections) should be marked `atomic`.
For collections, there are three valid options:
- `linear` exercises are organized in a sequential structure with previous and next exercise
- `hierarchical` exercises are organized in a tree structure
- `networked` exercises are linked in a graph like structure
However, specifying this attribute has no effect on how the repository is handled. At the moment, all collections have a tree structure. (CA)
- Type of the value is `String`.
- The format of the value is one of `[atomic, linear, hierarchical, networked]`.
- Example:
```yml
structure: "atomic"
```
## collectionContent
This attribute allows specifying [collections](#collections). It is used to specify the children of this node. These children are metadata files according to the specification on this page.
Children must be located in sub-directories of the directory where the metadata file specifying them as `collectionContent` is located.
Paths need to be written in a format resembling UNIX file paths. Without a leading `/` they are relative to the directory of the current metadata file, with a leading `/` they are absolute within the repository. (CA)
- Type of the value is a `list of Strings`.
- The format of the value is unspecified.
- Example:
```yml
collectionContent:
- "src/if-001/if-001.yml"
- "src/if-002/if-002.yml"
- "src/if-003/if-003.yml"
```
## image
Path to an image location (either in the repository or a general URL). This image will be used as the content's icon on the Sharing Platform. (CA)
- Type of the value is `String`.
- The format of the value is a picture.
- Example:
```yml
image: "img/icon.svg"
```
# Collections
By default, one repository has one metadata file describing one item. One might like to have a repository containing a collection of resources, each of which is described by its own metadata file. For example, a repository could contain an exercise sheet consisting of multiple exercises, or a repository for an entire course containing lecture slides, example code, and programming exercises.
In such cases a single metadata file is not well suited to describe the entire repository. Instead, a collection can be defined. This is a tree structure of metadata files. Internal nodes describe collections (nested collections are possible), and leaf nodes are normal metadata files describing a single item. The structure of an introductory programming course might look like this:
```
course
|
-----------------------------------------------------------------------------
/ | \
variables loops functions
| | |
------------------------ ------------------------ ------------------------
/ | \ / | \ / | \
slides example code exercise sheet slides example code exercise sheet slides example code exercise sheet
|
---------------------
/ | \
exercise 1 exercise 2 exercise 3
```
Having a tree structure like this allows describing each item with its own metadata. The metadata files in a collection are the same as any other metadata files, with the addition of the field [collectionContent](#collectioncontent). This field contains a list of file names of the metadata files describing the children of that node. These metadata files need to be located in a sub-directory of the directory where the collection is defined.
In the above example the top level metadata file would contain:
```yaml
collectionContent:
- variables/metadata.yaml
- loops/metadata.yaml
- functions/metadata.yaml
```
## Extensions for referencing other git-repositories
It is also allowed to reference other sharing objects in other git project.
This especially allows for the definition of selected study plans. e.g from the example above
```
selected exercises
|
-----------------------------------------------------------------------------
/ \
exercise sheet functions
| |
--------------------- ...
/ | \
exercise 1 exercise 2 exercise 3
```
### Referencing a project in the same sharing gitlab installation
A project in the same repository is referenced by its project id in brackets. E.g
```yaml
collectionContent:
- [10] # references the project with id 10 in the sharing git project
- [10]loops/metadata.yaml # references the exercise with in a project
```
### Referencing a project in any git project
Another sharing object can be referenced by its gitlab URL, optionally followed by an empty pair of square brackets, and its subpath.
```yaml
collectionContent:
- https://sharing.codeability-austria.uibk.ac.at/sharing/health-check-tests/collection_tests/collectionstests1.git[]loops/metadata.yaml
```
## Inheritance
Specifying collections can be repetitive in some cases. If children should have the same values for some entries as their parent, it is sufficient to specify the entry in the parent. If the entry is not specified in a child, it will inherit the value of its parent's for this entry.
Required fields still have to be specified, but inheritance works for almost all other fields:
- `audience`
- `difficulty`
- `image`
- `typicalAgeRange`
- `teaches/assesses`
- `contributor`
- `isBasedOn`
- `programmingLanguage`
- `requires`
- `subject`
- `creator`
- `publisher`
- `language`
- `license`