Browse Source

Fix typos; add paragraph about validation.

scossu 1 week ago
parent
commit
d8328eaddc
3 changed files with 29 additions and 20 deletions
  1. 1 1
      doc/bricks03.graphml
  2. BIN
      doc/bricks03.png
  3. 28 19
      doc/content_model_primer.md

+ 1 - 1
doc/bricks03.graphml

@@ -277,7 +277,7 @@
           <y:Fill color="#CAEC64" color2="#99CC00" transparent="false"/>
           <y:BorderStyle color="#3F5400" type="line" width="1.0"/>
           <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="36.688228607177734" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="65.60842895507812" x="12.195785522460938" y="6.155885696411133">book01_p3
-[Bricj]<y:LabelModel>
+[Brick]<y:LabelModel>
               <y:SmartNodeLabelModel distance="4.0"/>
             </y:LabelModel>
             <y:ModelParameter>

BIN
doc/bricks03.png


+ 28 - 19
doc/content_model_primer.md

@@ -128,8 +128,8 @@ other collections. The resources in the collection cannot have an ordering
 number of their own if they are owned by multiple collections, and for this
 reason, bricks are used to provide ordered stand-ins.
 
-Bricks can be used for this purpose in a variety of way. A very simple use case
-is illustrated below:
+Bricks can be used for this purpose in a variety of ways. A very simple use
+case is illustrated below:
 
 ![Ordering of pages in a book using Bricks.](bricks01.png)
 
@@ -147,12 +147,12 @@ file to the next. But, what if we have multiple files per page:
 ![Ordering of multi-file pages in a book using Bricks.](bricks02.png)
 
 In this case, closer to a real archival scenario, we have an **archival
-master** file, a **production master** file, and a transcript text file. A
-single-file ordering wouldn't work here, so, a sub-type of Brick is used to
-represent a page. Each Page resource can contain metadata about its content and
-position in the book, and groups all the files related to a page, each with a
-specific relationship (`has_pres`, `has_prod`, `has_tx`) so that they can be
-clearly tracked.
+master** file, a **production master** file, and a transcript text file for
+each page of the book. A single-file ordering wouldn't work here, so, a
+sub-type of Brick is used to represent a page. Each Page resource can contain
+metadata about its content and position in the book, and groups all the files
+related to a page, each with a specific relationship (`has_pres`, `has_prod`,
+`has_tx`) so that they can be clearly tracked.
 
 A more complex example, less common because it is more laborious to set up,
 but entirely possible, involves an Artifact resource that has multiple
@@ -245,8 +245,8 @@ Properties can be wide open, i.e. they accept any (or no) values, or they can
 be more or less strictly constrained. The advantage of constraining properties
 is that increases relevance and accuracy of search results: for example, by
 defining `image_height` as a number rather than a generic string, it is
-possible to find all images with a height of less than 1000 pixels. Or, by
-constraining the allowed values to a **controlled vocabulary** prevents
+possible to find all images with a height of less than 1000 pixels. Also,
+constraining the allowed values to a **controlled vocabulary** may prevent
 confusion. For example, if the `is_published` property is meant to be a
 true/false value, by constraining the range of values to `true` and `false` we
 can avoid having `yes`, `Yes`, `YES`, `y`, `Y`, `1`, `t`, `TRUE`, `published`,
@@ -262,21 +262,21 @@ submission undergoes **validation** (explained further below), errors may show
 that require adjusting the metadata according to the defined constraints.
 Understanding the constraints may help fixing the errors. Details on how to
 define these constraints are in the [Content modeling
-manual](./content_model_manual.md)
+manual](./content_model_manual.md).
 
 #### Type
 
-This constraint defines what kind of data may be entered for a property. It
-can be a string (pretty much any text is fine); a number; a date (which is a
-string formatted in a particular way); a relationship; or a URL. More types may be
-added at later stages of Pocket Archive development.
+This constraint defines what kind of data may be entered for a property. It can
+be a string (pretty much any text is fine); a number; a date or date and time;
+a relationship; or a URL. More types may be added at later stages of Pocket
+Archive development.
 
 The URL type is regarded as a string for constraint purposes, but it is treated
 especially in the presentation, where it will show as a hyperlink. The
 archivist is responsible for ensuring that the hyperlink points to a valid
 location. A good archival practice is to point to a [Wayback
 Machine](https://web.archive.org/) URL if available, which allows the archivist
-to display the page "frozen" at the time of the submission, before it might
+to display the page "frozen" at the time of the submission, before it might be
 altered or taken down altogether.
 
 The property type also results in a hyperlink, but it is used only for
@@ -300,6 +300,15 @@ cardinality of 1 means that the property is *single-valued*; etc.
 [NOTE: not yet implemented]
 
 The range of a property depends on its data type: for a number or a date, it
-can be a minimum and/or maximum value; for a string, a specific pattern can be
-defined; for a resource type, the content type(s) of the resources pointed to
-can be restricted.
+can be a minimum and/or maximum value range; for a string, a specific pattern
+can be defined; for a resource type, the content type(s) of the resources
+pointed to can be restricted.
+
+## Validation
+
+Validation is an automatic action performed by the submission process that
+verifies that all the input data of the SIP are conforming to their schema.
+If validation passes, the submission process continues as expected; if it
+fails, the whole submission fails and the process stops. In both cases, a
+report is generated, so that in case of failure, the depositor can inspect the
+validation results and adjust the metadata before re-submitting the SIP.