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 Michael Breu's avatar Michael Breu
Hide whitespace changes
Inline Side-by-side
Metadata/Metadata-Version-0.5-Documentation.md
View page @ 8661aed9
_Updated for v0.4.2_
_identifier deprecated_
_Updated for v0.5_
_This page describes the meta data format v0.5.x. If you are looking for v0.4.x follow_ [this link](https://sharing-codeability.uibk.ac.at/development/sharing/codeability-sharing-platform/-/wikis/Metadata/Metadata-Version-0.4-Documentation)
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.
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**:
......@@ -32,7 +27,6 @@ If you have content in a repository which is not easily describable with a singl
[[_TOC_]]
# GENERAL INFORMATION
## metadataVersion
......@@ -44,22 +38,24 @@ The version may evolve over time. We will try to provide aids to upgrade the met
- 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.
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
......@@ -70,6 +66,7 @@ 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"
```
......@@ -83,6 +80,7 @@ A one or two sentence synopsis of your contribution. Will be displayed as a summ
- Type of the value is `String`.
- The format of the value is unspecified.
- Example:
```yml
description: "This is my free description"
```
......@@ -93,11 +91,12 @@ 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).
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"
......@@ -113,6 +112,7 @@ The author of the resource, the person responsible for the learning resource or
- 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"
......@@ -127,6 +127,7 @@ A person responsible for making contributions to the resource (e.g. content, cor
- 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"
......@@ -150,6 +151,7 @@ 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"
......@@ -166,6 +168,7 @@ 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"
```
......@@ -179,6 +182,7 @@ University module/school subject, for which the resource is intended. (Dublin Co
- 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"
......@@ -191,49 +195,57 @@ 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
## 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
## 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
## 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
## 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"
......@@ -247,6 +259,7 @@ A related resource that is required by the described resource to support its fun
- Type of the value is a `list of String`.
- The format of the value is unspecified.
- Example:
```yml
requires:
- "Java12"
......@@ -259,37 +272,44 @@ The predominant learningResourceType or kind characterizing the learning resourc
- 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"
......@@ -299,8 +319,7 @@ isBasedOn:
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:
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
......@@ -311,6 +330,7 @@ However, specifying this attribute has no effect on how the repository is handle
- Type of the value is `String`.
- The format of the value is one of `[atomic, linear, hierarchical, networked]`.
- Example:
```yml
structure: "atomic"
```
......@@ -326,6 +346,7 @@ Paths need to be written in a format resembling UNIX file paths. Without a leadi
- 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"
......@@ -340,6 +361,7 @@ Path to an image location (either in the repository or a general URL). This imag
- Type of the value is `String`.
- The format of the value is a picture.
- Example:
```yml
image: "img/icon.svg"
```
......@@ -349,6 +371,7 @@ image: "img/icon.svg"
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
|
......@@ -363,11 +386,12 @@ 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
......@@ -377,8 +401,8 @@ collectionContent:
## 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
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
|
......@@ -389,19 +413,22 @@ This especially allows for the definition of selected study plans. e.g from the
--------------------- ...
/ | \
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
......@@ -412,6 +439,7 @@ collectionContent:
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`
......@@ -425,6 +453,4 @@ Required fields still have to be specified, but inheritance works for almost all
- `creator`
- `publisher`
- `language`
- `license`
- `license`
\ No newline at end of file