model, validator, vocab, documentor script, stub for loader

docs/index.md

@@ -1,31 +1,32 @@
 ![](assets/prez-logo.png)
 
+This is the namespace web page for Prez.
+
 ## What is Prez?
 
-Prez is an open source web application that delivers "profiles of Knowledge Graph data".
+Prez is an open source web application API that delivers "profiles of Knowledge Graph data".
 
-Prez is used to publish:
+Prez is most commonly used to publish:
 
 * lists of managed vocabularies
-* highly configurable catalogues of digital resources
+* catalogues of semantic resources
 * spatial reference datasets
 
-While being open source, Prez is mostly maintained by [KurrawongAI](https://kurrawong.ai) who provide professional services to assist with its use.
-
-## How can I get Prez?
+In addition to Prez the main API tool, there are a series of smaller tools - scripts - that can be used to prepare [Semantic Web](https://en.wikipedia.org/wiki/Semantic_web) for publication by Prez. These, and the Prez system use the Prez namespace, which is this web address:
 
-You can run Prez yourself by understanding how it works (see below) and running all the parts.
+* `https://prez.dev/`
 
-Or you can contact [KurrawongAI](https://kurrawong.ai) who can assist you.
+## How can I get Prez?
 
-## How does Prez work?
+While being open source, Prez is mostly maintained by [KurrawongAI](https://kurrawong.ai) who provide professional services to assist with its use, see the [Prez Docs](https://docs.kurrawong.ai/prez/Overview)
 
-Prez is available for use as two components:
+You can still run Prez, the API, and any other smaller Prez fools yourself by understanding how it works - see details via the link above.
 
-* [Prez](https://github.com/rdflib/prez/) - an API that 'slices and dices' Knowledge Graph data source according to data structure definitions
-* [Prez UI](https://github.com/RDFLib/prez-ui) - a web user interface that displays data from the Prez API
+If ou need help, you can [contact KurrawongAI](https://kurrawong.ai/contact) who can assist you.
 
-These components require a Knowledge Graph database to store the data Prez uses.
+## Prez tools
 
-Additionally, Prez relies on management of processes to load data into a Knowledge Graph database. These can be implemented in many ways, such s workflows within version control systems. 
+Other than the main Prez (API) itself, the Prez tools are: 
 
+* [Prez Ontology](ont.md)
+* [Prez Manifest Model](manifest.md)

docs/manifest.md

@@ -0,0 +1,127 @@
+# Prez Manifest Model
+
+A Prez Manifest is an RDF file that describes and links to a set of resources that can be loaded into an RDF database for Prez to provide access to.
+
+To support Manifest creation and use, the following tools are provides:
+
+1. [The model](#model)
+2. [Manifest Resource Roles Vocabulary](#roles-vocabulary)
+3. [Validator](#validator)
+4. [Build Scripts](#build-scripts)
+5. [Examples](#examples)
+
+## Model
+
+``` mermaid
+graph LR
+  Manifest --1:1-N--> Resource;
+  Resource --1:1--> artifact;
+  Resource --1:1--> role;
+  Resource --1:0-1--> name;
+  Resource --1:0-1--> decription;
+```
+
+The Manifest Model is simply a Manifest class, `prez:Manifest`, which MUST have 1 or more Resource Descriptors, `prof:ResourceDescriptor` indicated by the `prof:hasResource` predicate. 
+
+Each Resource Descriptor MUST have exactly one `prof:hasArtifact` predicate indicating an RDF literal resource (string) giving a file path or path pattern containing the resource information, relative to the manifest.
+
+Each Resource Descriptor MUST also have exactly one `prof:hasRole` predicate indicating a Concept from the _Manifest Resource Roles Vocabulary_.
+
+Each Resource Descriptor MAY have a `schema:name` and/r a `schema:description` predicate indicating literal resources naming and describing it.
+
+<a id="roles-vocabulary"></a>
+## Manifest Resource Roles Vocabulary
+
+This roles vocabulary contains the allowed roles that a resource can play with respect to a Manifest.
+
+The IRI of this vocabulary is:
+
+* `https://prez.dev/ManifestResourceRoles`
+    * the vocab namespace is `https://prez.dev/ManifestResourceRoles/`
+    * recommended namespace prefix is `mrr`
+
+Human-readable form:
+
+| Concept IRI                               | Label                                   | Definition                                                                                                          | Parent                         |
+|-------------------------------------------|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------------|
+| `mrr:ContainerData`                       | Container Data                          | Data for the container, usually a Catalogue, including the identity of it and each item fo content                  | -                              |
+| `mrr:ContentData`                         | Content Data                            | Data for the content of the container                                                                               | -                              |
+| `mrr:ContainerAndContentModel`            | Container & Content Model               | The default model for the container and the content. Must be a set of SAHCL Shapes                                  | -                              |
+| `mrr:ContainerModel`                      | Container Model                         | The default model for the container. Must be a set of SAHCL Shapes                                                  | `mrr:containerAndContentModel` |
+| `mrr:ContentModel`                        | Content Model                           | The default model for the content. Must be a set of SAHCL Shapes                                                    | `mrr:containerAndContentModel` |
+| `mrr:CompleteContainerAndContentLabels`   | Complete Content and Container Labels   | All the labels - possibly indluding names, descriptions & seeAlso links - for the Container and Content objects     | -                              |
+| `mrr:IncompleteContainerAndContentLabels` | Incomplete Content and Container Labels | Some of the labels - possibly indluding names, descriptions & seeAlso links - for the Container and Content objects | -                              |
+
+Machine-readable form:
+
+```
+--8<-- "manifest/mrr.ttl"
+```
+
+--8<-- "mrr.ttl"
+
+The IRI for automatic retrieval of this vocabulary file is: <https://prez.dev/ManifestResourceRoles>.
+
+
+## Validator
+
+This simple [SHACL](https://www.w3.org/TR/shacl/) validator "Shapes" file can be used by SHACL validation software to test the validity of a Manifest RDF file with respect to this model:
+
+```
+--8<-- "manifest/validator.ttl"
+```
+
+The IRI for automatic retrieval of this Shapes file is: <https://prez.dev/manifest/validator>.
+
+The recommended tools to perform validation using this Shapes file are:
+
+1. [KurrawongAI's Online Validator](https://tools.dev.kurrawong.ai/validate) - this Shapes file is pre-loaded
+2. [pySHACL Python tool](https://pypi.org/project/pyshacl/) - for scripted validation
+
+## Build Scripts
+
+### Documentor
+
+The `documentor.py` Python script in this documentation's repository creates a "Prez Resources" table in either Markdown or ASCIIDOC from a Manifest file which it validates first:
+
+* <https://github.com/Kurrawong/prez.dev/blob/main/manifest/documentation.py>
+
+```
+usage: documentor.py [-h] [-v] [-t {markdown,asciidoc}] input
+
+positional arguments:
+  input                 File, Folder or Sparql Endpoint to read RDF from
+
+options:
+  -h, --help            show this help message and exit
+  -v, --version         show program's version number and exit
+  -t {markdown,asciidoc}, --type {markdown,asciidoc}
+                        The type of markup you want to export: Markdown or ASCCIDOC
+```
+
+### Loader
+
+==_In Progress_==
+
+The `loader.py` Python script in this documentation's repository creates a 
+
+* <https://github.com/Kurrawong/prez.dev/blob/main/manifest/loader.py>
+
+## Examples
+
+See the simple and always up-to-date [KurrawongAI Demo Vocabularies manifest](https://github.com/Kurrawong/demo-vocabs/manifest.ttl):
+
+Full:
+```
+--8<-- "manifest/example01.ttl"
+```
+
+Partial:
+```
+--8<-- "manifest/example02.ttl"
+```
+
+Invalid (second Resource Descriptor does not indicate a role)
+```
+--8<-- "manifest/example03.ttl"
+```

docs/ont.md

@@ -0,0 +1,11 @@
+# Prez Ontology
+
+Here be the ont!
+
+
+Resource | Role | Description
+--- | --- | ---
+Catalogue Definition, [`catalogue.ttl`](catalogue.ttl) | [Container Data](https://prez.dev/ManifestResourceRoles/containerData) | The definition of, and medata for, the container which here is a dcat:Catalog object
+Content, [`vocabs/*.ttl`](vocabs/*.ttl) | [Content Data](https://prez.dev/ManifestResourceRoles/contentData) | skos:ConceptsScheme objects in RDF (Turtle) files in the vocabs/ folder
+[`ogc_records_profile.ttl`](https://github.com/RDFLib/prez/blob/main/prez/reference_data/profiles/ogc_records_profile.ttl) | [Container & Content Model](https://prez.dev/ManifestResourceRoles/containerAndContentModel) | 
+