Merge pull request #20 from RKrahl/doc-data

Document the data model
panosc-eu · Feb 5, 2020 · 0086817 · 0086817
2 parents f8b7dea + 047f4b0
commit 0086817
Showing 1 changed file with 216 additions and 51 deletions.
diff --git a/doc/data-model.md b/doc/data-model.md
@@ -1,4 +1,6 @@
-The data model consists of ten models
+# The data model
+
+The data model consists of ten classes
 * `Affiliation` - information about which facility a member is located at
 * `Dataset` - information about an experimental run, including optional File, Sample, Instrument and Technique
 * `Document` - proposal which includes the dataset or published paper which references the dataset
@@ -7,86 +9,249 @@ The data model consists of ten models
 * `Member` - proposal team member or paper co-author
 * `Parameter` - scalar measurement with value and units
 * `Person` - human who carried out experiment
-* `Role` - operator, author
 * `Sample` - extract of material used in the experiment
 * `Technique` - common name of scientific method used
 
-
 https://confluence.panosc.eu/display/wp3/Data+Model
+
+## General remarks
+
++ Classes that may be returned by API calls have a `id` property
+  allowing to refer to them in subsequent calls like `GET /datasets/{id}`.
+  This id is a purely internal identifier of the local metadata
+  catalogue.  It is considered ephemeral and should not be retained by
+  the client beyond the current session.  The value should be
+  restricted to the characters `0-9A-Za-z_.~-`.
+
++ Some classes have a `pid` property.  This is a persistent identifier
+  that is supposed to be stable and may be stored in the client for
+  later referal.  It also allows cross references to objects in remote
+  repositories.  The value should be a well established persistent
+  identifier such as a DOI, a Handle, an ORCID-iD, or a ROR.  If such
+  a PID is not available for the object, a locally assigned identifier
+  in the metadata catalogue is acceptable, as long as it is guaranteed
+  to be stable.
+
+---
+
 ## Affiliation
 
-The `Affiliation` model has five optional fields
-* Id (string)
-* Name (string)
-* Address (string)
-* City (string)
-* Country (string)
+Information about which facility a member is located at.
+
+### Relationships
+
+| Card | Class  | Field |
+| ---- | ------ | ----- |
+| 1,1  | Member |       |
+
+### Properties
+
+| Field   | Type   | Mandatory | Comment |
+| ------- | ------ | --------- | ------- |
+| name    | String | yes       |         |
+| pid     | String | no        |         |
+| address | String | no        |         |
+| city    | String | no        |         |
+| country | String | no        |         |
+
+---
 
 ## Dataset
-The `Dataset` model consists of 4 mandatory fields
-* Persistent Identifier or PID (string)
-* Title (string)
-* creation date (date)
-* isPublic (boolean)
 
-and an optional field
-* size (measurement with units(bytes))
+Information about an experimental run, including optional File,
+Sample, Instrument and Technique.
+
+### Relationships
+
+| Card | Class      | Field      |
+| ---- | ---------- | ---------- |
+| 1,1  | Document   | document   |
+| 0,1  | Instrument | instrument |
+| 0,*  | File       | files      |
+| 0,*  | Parameter  | parameters |
+| 0,*  | Sample     | samples    |
+| 0,*  | Technique  | techniques |
 
-The `Dataset` can have one `Instrument` only and several `Techniques`, `Parameters`, `Files` and `Samples`
+### Properties
+
+| Field        | Type    | Mandatory | Comment                      |
+| ------------ | ------- | --------- | ---------------------------- |
+| id           | String  | yes       |                              |
+| title        | String  | yes       |                              |
+| creationDate | Date    | yes       |                              |
+| isPublic     | Boolean | yes       |                              |
+| pid          | String  | no        |                              |
+| size         | Integer | no        | Size of the dataset in bytes |
+
+---
 
 ## Document
-The `Document` model represents a scientific proposal or publication. It can include `Datasets`, `Parameters` and `Members`.
-It has three mandatory fields
-* PID
-* Type
-* title
-
-and seven optional fields
-* internal (Boolean)
-* summary (String)
-* DOI (string)
-* Start date (date)
-* end date (date)
-* release date (date)
-* license (string, e.g. CC-BY-4.0)
+
+Represents a scientific proposal or publication.
+
+### Relationships
+
+| Card | Class     | Field      |
+| ---- | --------- | ---------- |
+| 0,*  | Dataset   | datasets   |
+| 0,*  | Member    | members    |
+| 0,*  | Parameter | parameters |
+
+### Properties
+
+| Field       | Type    | Mandatory | Comment        |
+| ----------- | ------- | --------- | -------------- |
+| id          | String  | yes       |                |
+| type        | String  | yes       |                |
+| title       | String  | yes       |                |
+| pid         | String  | no        |                |
+| internal    | Boolean | no        |                |
+| summary     | String  | no        |                |
+| startDate   | Date    | no        |                |
+| endDate     | Date    | no        |                |
+| releaseDate | Date    | no        | Date when this document will become openly accessible |
+| license     | String  | no        | Use [SPDX license identifier](http://www.spdx.org/licenses) if applicable, e.g. CC0-1.0 or CC-BY-4.0 |
+
+---
 
 ## File
 
-The `File` model has two mandatory fields,
-* Id
-* name
+Name of file and optionally location.
+
+### Relationships
+
+| Card | Class   | Field |
+| ---- | ------- | ----- |
+| 1,1  | Dataset |       |
+
+### Properties
 
-and two optional
-* path 
-* size
+| Field   | Type    | Mandatory | Comment         |
+| ------- | ------- | --------- | --------------- |
+| name    | String  | yes       |                 |
+| path    | String  | no        |                 |
+| size    | Integer | no        | Number of bytes |
+
+---
 
 ## Instrument
 
-The `Instrument` model has three mandatory fields, 
-* ID (string, e.g. a DOI)
-* Name (String, e.g. Loki)
-* Facility (string e.g. ESS)
+Beam line where experiment took place.
+
+### Relationships
+
+| Card | Class   | Field    |
+| ---- | ------- | -------- |
+| 0,*  | Dataset | datasets |
+
+### Properties
+
+| Field    | Type    | Mandatory | Comment    |
+| -------- | ------- | --------- | ---------- |
+| id       | String  | yes       |            |
+| name     | String  | yes       | e.g. Loki  |
+| facility | String  | yes       | e.g. ESS   |
+| pid      | String  | no        |            |
+
+---
 
 ## Member
 
+Proposal team member or paper co-author.
+
+### Relationships
+
+| Card | Class       | Field        |
+| ---- | ----------- | ------------ |
+| 1,1  | Document    |              |
+| 1,1  | Person      | person       |
+| 0.*  | Affiliation | affiliations |
+
+### Properties
+
+| Field    | Type    | Mandatory | Comment |
+| -------- | ------- | --------- | ------- |
+| role     | String  | yes       |         |
+
+---
+
 ## Parameter
 
-The `Parameter` model is intended for scientific measurements. It has two mandatory fields
-* name (string, e.g. sample_pressure)
-* value (number e.g 22)
+### Relationships
+
+| Card | Class       | Field |
+| ---- | ----------- | ----- |
+| 0,1  | Dataset     |       |
+| 0,1  | Document    |       |
+
+Note: a parameter is either related to a dataset or a document, but
+not both.
 
-and one mandatory where applicable field
-* units (string e.g. bar)
+### Properties
+
+| Field    | Type    | Mandatory        | Comment              |
+| -------- | ------- | ---------------- | -------------------- |
+| name     | String  | yes              |                      |
+| value    | Number  | yes              | e.g. 22              |
+| units    | String  | where applicable | e.g. bar             |
+
+---
 
 ## Person
 
-## Role
+Human who carried out experiment.
+
+### Relationships
 
+| Card | Class  | Field |
+| ---- | ------ | ----- |
+| 0,*  | Member |       |
+
+### Properties
+
+| Field        | Type    | Mandatory | Comment  |
+| ------------ | ------- | --------- | -------- |
+| givenName    | String  | yes       |          |
+| familyName   | String  | yes       |          |
+| pid          | String  | no        |          |
+| publication  | String  | no        |          |
+
+---
+
+## Sample
+
+Extract of material used in the experiment.
+
+### Relationships
+
+| Card | Class   | Field    |
+| ---- | ------- | -------- |
+| 0,*  | Dataset | datasets |
+
+### Properties
+
+| Field       | Type    | Mandatory | Comment  |
+| ----------- | ------- | --------- | -------- |
+| id          | String  | yes       |          |
+| name        | String  | yes       |          |
+| pid         | String  | no        |          |
+| description | String  | no        |          |
+
+---
 
 ## Technique
-The `Technique` model has two mandatory fields
-* PID (string)
-* name (string) 
 
+Common name of scientific method used.
+
+### Relationships
+
+| Card | Class   | Field |
+| ---- | ------- | ----- |
+| 0,*  | Dataset |       |
+
+### Properties
 
-In general the API is readonly with no DELETE, POST/PUT or PATCH requests.
+| Field | Type    | Mandatory | Comment  |
+| ----- | ------- | --------- | -------- |
+| name  | String  | yes       |          |
+| pid   | String  | no        |          |