docs: 🏗️ explain using check-datapackage

docs/design/architecture.qmd

@@ -245,13 +245,15 @@ flowchart
         end
 
         read_config["read_config()<br>[function]"]
-        read_json["read_json()<br>[function]"]
+        read_properties["read_properties()<br>[function]"]
+        properties["PackageProperties<br>[class]"]
         build("build()<br>[function]")
 
         section --"Lists metadata<br>items to include"--> config
         config_file -- "Provides build<br>configurations" --> read_config
 
-        read_json --"Provides properties<br>as dict"--> build
+        read_properties --> properties
+        properties --> build
         read_config -- "Adds build<br>configurations" --> build
         config --"Adds build<br>configurations"--> build
     end
@@ -261,7 +263,7 @@ flowchart
     output("Output<br>[files and<br>folders]")
 
     templates --"Provides output<br>structure and layout"--> config
-    user --"Provides datapackage.json<br>to build"--> read_json
+    user --"Provides datapackage.json<br>to build"--> read_properties
     user --"Provides configurations,<br>as file or Python class<br>(optional)"--> config_file
     user --"Provides templates<br>in folder<br>(optional)"--> templates
     build --"Populates template(s)<br>with metadata items"--> output

docs/design/interface/cli.qmd

@@ -179,6 +179,15 @@ The reason we use a URI is to allow flexibility in specifying the
 location of the Data Package file and to allow us to extend to other
 locations in the future, e.g. remote files.
 
+::: callout-note
+Flower reads the `datapackage.json` file with the
+[Sprout](https://sprout.seedcase-project.org) function
+`read_properties()`. This function will check whether the properties
+comply with the Data Package specification and will output an error if
+there are any issues using
+[`check-datapackage`](https://check-datapackage.seedcase-project.org).
+:::
+
 <!-- TODO: Maybe also at some point allow using `doi:` URI? -->
 
 If you want to customise the output, you need to create a `_flower.toml`
@@ -229,14 +238,6 @@ This overriding behaviour also applies to the other CLI options,
 `--output-dir` and `--verbose`; if they are used on the CLI, they
 override the corresponding settings in the configuration file.
 
-::: callout-important
-Flower does not check whether the `datapackage.json` file is correct or
-not, it will only read and parse it. If an error happens during reading
-or parsing, it might not be very informative. Use
-[`check-datapackage`](https://check-datapackage.seedcase-project.org)
-first to check that the `datapackage.json` is correct.
-:::
-
 ## {{< var planned >}} `view`
 
 The `view` command has the following base signature:

docs/design/interface/python.qmd

@@ -37,6 +37,27 @@ described on the [CLI design page](cli.qmd): `build()` and `view()`.
 This page focuses on the Python design and decisions made to avoid too
 much overlap with the content of the CLI design page.
 
+Both the `build()` and `view()` functions read in the `datapackage.json`
+file through the `read_properties()` function from [Sprout](https://sprout.seedcase-project.org)
+, which returns a `PackageProperties` object. This is a Python
+[data class](https://docs.python.org/3/library/dataclasses.html) that represents the Data Package properties, and is used as
+the main input for the non-CLI functions that build the output files.
+This class is used instead of a dictionary for a few reasons:
+
+-   Provides a clear and structured way of representing the properties of a
+    Data Package with defined attributes and types.
+-   Allows for better type checking of the properties to ensure the
+    properties are in the expected format.
+-   Provides a clearer and documented interface for accessing the
+    properties.
+-   Includes better integrated documentation of the properties via
+    developer tools and IDEs.
+-   Allows for the use of dataclass features, such as default values and
+    immutability.
+-   Makes it easier to extend the properties to accommodate version
+    updates of the Data Package specification, by creating new versions
+    of the `PackageProperties` class.
+
 ### {{< var planned >}} `build()`
 
 As already described in the CLI design page, this function has four
@@ -61,8 +82,8 @@ flowchart TD
     uri:::input --> resolve_uri{{"resolve_uri()"}} --> path
     path --> load_config{{"load_config()"}} --> Config
     style_cfg[style]:::input --> load_config
-    path --> read_dp{{"read_datapackage()"}} --> metadata
-    metadata & Config --> build_sections{{"build_sections()"}} --> output["list[BuiltSection]"]
+    path --> read_properties{{"read_properties()"}} --> properties
+    properties & Config --> build_sections{{"build_sections()"}} --> output["list[BuiltSection]"]
     output --> write_sections{{"write_sections()"}}
     output_dir:::input --> write_sections
     write_sections --> files["list[Path]"]
@@ -78,6 +99,7 @@ flowchart TD
 ``` {.python filename="src/seedcase_flower/cli.py"}
 from typing import Optional
 from seedcase_flower.config import Style
+from seedcase_sprout import read_properties, PackageProperties
 from pathlib import Path
 from dataclasses import dataclass
 
@@ -92,6 +114,7 @@ class BuiltSection:
 # and https://typer.tiangolo.com/tutorial/commands/help/#rich-markdown-and-markup
 # CLI functions don't need a return type.
 def build(
+    # TODO: This could also be a URI object instead of a string.
     uri: str = "datapackage.json",
     style: Optional[Style] = None,
     output_dir: Path = Path("."),
@@ -129,7 +152,8 @@ def build(
     config: Config = load_config(style, path)
 
     # Able to read from URI, e.g. `https` or `file` or `gh`
-    properties: dict = read_datapackage(path)
+    # Will need to customise read function to fit needs of Flower.
+    properties: PackageProperties = read_properties(path)
 
     # One item per section, rendered from template.
     # Internally uses Jinja2 to render templates with metadata