Archive/MetaData-Version-0.2-Documentation.md

+# Metadata Version 0.2 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.
+
+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. Most attributes are optional and can be used to provide extra information. This is encouraged. Other attributes are used to implement specific functionalities. For more details, see the description of the individual attributes. For each attribute, an example how it could look in the metadata is provided. The format used in these example is YAML, if you use JSON the syntax is different.
+
+[[_TOC_]]
+
+## Required Attributes
+
+### metadataVersion
+
+A string which is fixed to `0.2` in the current version.
+
+```yaml
+metadataVersion: "0.2"
+```
+
+### type
+
+Enumeration. Can be one of
+- `programming exercise`
+- `exercise`
+- `collection`
+- `other`
+
+The type is used to classify data in a repository. Repositories containing only a single exercise should use `programming exercise` or, if the exercise is not an exercise, `exercise`. If the content is not an exercise the type `other` can be used.
+
+`collection` is used for repositories which contain more than one exercise. Such repositories must have a metadata file in the root directory which specifies the `type` as `collection`. Each exercise should have a dedicated directory containing a metadata file for the exercise. The root-metadata file should specify where the per-exercise-metadata is located. If no additional metadata files are specified, the directory tree will be searched for files called `metadata.yaml`, `metadata.yml`, and `metadata.json`. These files' content will be treated as metadata for the directory in which they are stored.
+
+```yaml
+type: programming exercise
+```
+
+### title
+
+A title for the provided material.
+
+```yaml
+title: Example exercise
+```
+
+### license
+
+The name of the license of the material provided in the repository. 
+
+```yaml
+license: MIT
+```
+
+### keyword
+
+A list of keywords for the provided material. At least one keyword must be specified.
+
+```yaml
+keyword:
+  - a keyword
+  - another keyword 
+```
+
+## Optional Attributes
+
+### format
+
+Indicates the file type, e.g. latex, ms word, pdf. Might be used for plugins in the future. Multiple file types can be specified. The value of the attribute is a list.
+
+```yaml
+format:
+  - latex
+  - pdf
+```
+
+### identifier
+
+An identifier for the exercise. For the time being it can be freely chosen.
+
+```yaml
+identifier: at.ac.example.foo.bar
+```
+
+### structure
+
+Describes how exercises are related. Default is `atomic`. 
+
+
+If the `type` is not `collection`, the value for `structure` must be `atomic` (or `structure` is does not get  specified at all). If the `type` is `collection`, the value of `structure` may be one of:
+- `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 (Currently `networked` structures are not supported and are treated as `hierarchical` exercises).
+
+(Functionality for collections is not implemented yet.)
+
+```yaml
+structure: atomic
+```
+
+### collectionContent
+
+If the material's `type` is `collection`, this attribute allows specifying where other metadata files are located. They are specified as a list of strings which must be paths within the same repository or URLs of any metadata file on the Sharing Platform. Do not specify cyclic references.
+
+```yaml
+collectionContent: 
+  - src/if-001/if-001.yml
+  - src/if-002/if-002.yml
+  - src/if-003/if-003.yml
+```
+
+### version
+
+The version of the content. Up to the content creators. Can be an arbitrary string, that tags a certain version. It has currently no further semantics. 
+
+```yaml
+version: "4.2"
+```
+
+### status
+
+Status of the content. Arbitrary string which is up to the creators.
+
+```yaml
+status: work in progress
+```
+
+### description
+
+A brief description of the provided material.
+
+```yaml
+description: "In this exercise, selection sort should be implemented in C."
+```
+
+### programmingLanguage
+
+A list of programming languages which are covered/used in the material. Typically only one
+
+```yaml
+programmingLanguage:
+  - Java
+  - HTML
+  - JavaScript
+```
+
+### language
+
+A list of ISO 639-1 natural language codes specifying the natural language of the provided material.
+
+```yaml
+language:
+  - de
+  - en
+```
+
+### educationLevel
+
+The required level of education to work on the exercise. Currently a free-form string.
+
+```yaml
+educationLevel: high school
+```
+
+### audience
+
+Description of the people for whom the content is intended. Currently a free-form string.
+
+```yaml
+audience: "first-semester computer science students"
+```
+
+### timeRequired
+
+The time it typically takes to solve the exercise / work on the content.
+
+Format: `hh:mm` or `hh:mm:ss`. The number of digits for the hours must be at least one, minutes (and seconds, if specified) must have exactly two digits (i.e. numbers from `00` to `59`.
+
+```yaml
+timeRequired: "1:30"
+```
+
+### creator
+
+A list of [people](#person) who create(d) the provided content.
+
+```yaml
+creator:
+  - name: John Doe
+    affiliation: University of Foo
+    email: "john.doe@foo.ac.at"
+  - name: Jane Smith
+    affiliation: Example College
+    email: "jane.smith@example.edu"
+```
+
+### publisher
+
+The maintainers of the material. List of [people](#person).
+
+```yaml
+publisher:
+  - name: John Doe
+    affiliation: University of Foo
+    email: "john.doe@foo.ac.at"
+  - name: Jane Smith
+    affiliation: Example College
+    email: "jane.smith@example.edu"
+```
+
+### deprecated
+
+Is the repository content deprecated? A boolean value.
+
+```yaml
+deprecated: false
+```
+
+### difficulty
+
+The difficulty of the topics covered in the material. One of `simple`, `medium`, `advanced`
+
+```yaml
+difficulty: medium
+```
+
+### source
+
+Sources for this content. A list of free-form strings.
+
+```yaml
+source:
+  - "https://example.com/path/to/a/source"
+  - "Someone, A. (2014). An awesome book. Foobar Publisher. (pp. 42-45)"
+```
+
+### contributor
+
+A list of [people](#person) who contributed to the project.
+
+```yaml
+contributor:
+  - name: John Doe
+    affiliation: University of Foo
+    email: "john.doe@foo.ac.at"
+  - name: Jane Smith
+    affiliation: Example College
+    email: "jane.smith@example.edu"
+```
+
+### valid
+
+The dates between which the exercise is valid. Has the two subproperties `start` and `end`.
+
+A date is a string in the format `YYYY-MM-DD`, `YYYY-MM`, or `YYYY`
+
+```yaml
+valid:
+  start: "2020-12-01"
+  end: "2021-04"
+```
+
+### requires
+
+List of required skills for solving the exercise. Items are free-form strings.
+
+```yaml
+requires:
+  - "Basic knowledge of Haskell"
+  - "Understanding the concept of runtime-complexity"
+```
+
+### image
+
+Path to an image location (either in the repository or a general URL). This image will be as the material's icon on the Sharing Platform.
+
+```yaml
+image: "img/icon.svg"
+```
+
+## Additional information
+
+### person
+
+The value of several attributes is a list of people. `person` is a custom type to identify someone. `person` has three sub-properties:
+- `name`
+- `affiliation`
+- `email`
+
+All of the are free-form strings.
+
+```yaml
+name: John Doe
+affiliation: University of Foo
+email: "john.doe@foo.ac.at"
+```
\ No newline at end of file