Archive/MetaData-V0.2:-Extensions-for-Collections.md

+# Handling of Collections
+
+[[_TOC_]]
+
+[MetaData V0.2 documentation](../MetaData V0.2 documentation) defines the meta data for atomic exercises.
+
+## Type collection
+
+If you choose type collection
+```yaml
+type: "collection"
+```
+
+The value for structure must be one of 
+- `linear`: exercises are organized in a sequential structure with previous and next exercise
+- `hierarchical`: exercises are organized in a tree like structure
+- `networked`: exercises are linked in a graph like structure
+
+In this three cases a further attribute `collectionContent` can be given, which is a list of links to contained exercises (or collections). Links can be relative links w.r.t. the current meta data file, or complete URLs to other exercises.
+
+## Attribute `collectionContent`
+```yaml
+collectionContent: 
+  - src/if-001/if-001.yml
+  - src/if-002/if-002.yml
+  - src/if-003/if-003.yml
+```
+
+This list containes links to further metadata-files containing the definition of exercises (or collections) in this link.
+
+**Remark:** We assume that the exercises are contained in the parent directory of the respective meta data file.
+
+The contents of `collectionContent` is logically considered as a link, that can be either relative to the current metadata (e.g. `src/if-001/if-001.yml`), or absolute to the current root (e.g. the git repository) (e.g. `/src/if-001/if-001.yml`) or could be an (absolute URL as e.g `https://www.tu-wien.ac.at/src/if-001/if-001.yml`) pointing to somewhere else.
+
+If the structure is `linear` the sequence of exercises is defined by the list in `collectionContent`.
+If the structure is `hierarchical` the links can themselves point to other collections.
+**Remark:** Cyclic dependencies are not allowed.
+
+`networked` structures are not yet specially supported, and considered as synonym for `hierarchical`.
+
+Currently only gitlab repository local exercises are supported.
+
+## the exercise id
+
+The exercise id is either 
+ - the gitlab project id, if the metadata is on top of the git repository hierarchy: e.g. "10"
+ - the gitlab project id, followed by the path to the metadata file, if it is a sub exercise/collection of a collection (e.g. "10:src/if-003") without starting or trailing slashes.
+   - an exception is, if the project_id would exceed the length of 512 characters. In this case the path is shortened to the tail, so that it fits exactly into 512 characters. I.e.
+     - `10:extremly/long/.../path` is shortened to `10:y/long/.../path` 
+
+## Inheritance
+
+Some attributes are inherited top down, if not provided downward:
+
+- `metadataVersion` no inheritance, 
+
+- `type` no inheritance
+
+- `title` no inheritance
+
+- `license` is a required field, so it needs to be specified in each metadata file. 
+
+- `keyword` no inheritance
+
+- `format` inherited, if not explicitely specified
+
+- `identifier` no inheritance
+
+- `structure` no inheritance
+
+- `collectionContent` no inheritance
+
+- `version` no inheritance
+
+- `status` inherited, if not explicitely specified
+
+- `description` no inheritance
+
+- `programmingLanguge` inherited if none specified
+
+- `language` inherited if none specified
+
+- `educationLevel` inherited if none specified
+
+- `audience` inherited if none specified`
+
+- `timeRequired` no inheritance
+
+- `creator` inherited if none specified
+
+- `contributor` inherited if none specified
+
+- `publisher` inherited if none specified
+
+- `deprecated` inherited if none specified
+
+- `difficulty` inherited if none specified
+
+- `source` no inheritance.
+
+- `valid` inherited if none specified
+
+- `requires` inherited if none specified
+
+- `image` inherited if none specified
+
+## Default for collectionContent
+If no `collectionContent` is given, the folder hierarchy is searched for metadata files (i.e. metadata.yml, metadata.yaml, or metadata.json). These are interpreted as content of the attribute `collectionContent`. The order is defined as the alphanumeric order of the folder structure.
\ No newline at end of file