Merge branch 'next' into docs/technical_interoperability_testing

documentation/docs/introduction/index.md

@@ -22,7 +22,7 @@ The Test Suite comprises four primary components:
 This component tests the technical interoperability of implementations based on the UNTP specification. It ensures that the technical aspects of the implementation align with the protocol's requirements.
 
 ## Semantic Interoperability
-The Semantic Interoperability tests focus on verifying that the credentials produced by an implementation are semantically consistent with the UNTP specification. This allows implementors to be conformant with the core specification while allowing for extensions.
+The [Semantic Interoperability test](/docs/test-suites/semantic-interoperability) focus on verifying that the credentials produced by an implementation are semantically consistent with the UNTP specification. This allows implementors to be conformant with the core specification while allowing for extensions.
 
 ## Graph Validation
 This component tests the entire trust graph produced by an implementation against the UNTP specification, ensuring the integrity and validity of the trust relationships within the system.
@@ -35,7 +35,7 @@ The UNTP Test Suite follows a tiered approach, with each tier building upon the
 
 **Tier 1**: Focuses on technical interoperability.
 
-**Tier 2**: Adds semantic interoperability testing.
+[**Tier 2**](/docs/test-suites/semantic-interoperability): Adds semantic interoperability testing.
 
 **Tier 3**: Incorporates graph validation.
 

documentation/docs/test-suites/index.md

@@ -3,7 +3,7 @@ sidebar_position: 1
 title: Test Suites
 ---
 
-import Disclaimer from '../\_disclaimer.mdx';
+import Disclaimer from './../\_disclaimer.mdx';
 
 <Disclaimer />
 

documentation/docs/test-suites/semantic-interoperability/cli/configuration.md

@@ -0,0 +1,169 @@
+---
+sidebar_position: 5
+title: Configuration
+---
+
+import Disclaimer from './../../../\_disclaimer.mdx';
+
+<Disclaimer />
+
+Before proceeding, we need to create the configuration file. The Tier 2 test suite config file defines the credentials being tested, the schema version to test against, and the location of the credential being tested.
+
+## Generating the configuration file
+
+To generate the configuration file, run the following command:
+
+```bash
+yarn run untp config
+```
+
+This will create a base configuration file named `credentials.json` in the base directory of the Tier 2 test suite folder: `tests-untp/packages/untp-test-suite/credentials.json`.
+
+## Structure of the configuration file
+
+The generated configuration file will have the following structure:
+
+```json
+{
+  "credentials": [
+    {
+      "type": "aggregationEvent",
+      "version": "v0.0.1",
+      "dataPath": ""
+    },
+    {
+      "type": "conformityCredential",
+      "version": "v0.0.1",
+      "dataPath": ""
+    },
+    {
+      "type": "objectEvent",
+      "version": "v0.0.1",
+      "dataPath": ""
+    },
+    {
+      "type": "productPassport",
+      "version": "v0.0.1",
+      "dataPath": ""
+    },
+    {
+      "type": "transactionEvent",
+      "version": "v0.0.1",
+      "dataPath": ""
+    },
+    {
+      "type": "transformationEvent",
+      "version": "v0.0.1",
+      "dataPath": ""
+    }
+  ]
+}
+```
+
+### Credentials
+The value of the credentials property is an array of objects containing information about the credential type (corresponding to a schema), the credential schema version, and the location of the credential to be tested.
+
+### Schema and version structure
+
+The schemas used in the test suite are located in the following directory structure:
+
+```
+packages/
+└── untp-test-suite/
+    └── src/
+        └── schemas/
+            ├── aggregationEvent/
+            │   └── v0.0.1/
+            │       └── schema.json
+            ├── conformityCredential/
+            │   └── v0.0.1/
+            │       └── schema.json
+            ├── objectEvent/
+            │   └── v0.0.1/
+            │       └── schema.json
+            ├── productPassport/
+            │   └── v0.0.1/
+            │       └── schema.json
+            ├── transactionEvent/
+            │   └── v0.0.1/
+            │       └── schema.json
+            └── transformationEvent/
+                └── v0.0.1/
+                    └── schema.json
+```
+
+### Type
+The `type` property value corresponds to the folder name within the `src/schemas` directory of the test suite. This allows logical grouping of schema versions. For example, `"type": "aggregationEvent"` corresponds to the `aggregationEvent` folder.
+
+### Version
+The `version` property value corresponds to the folder name within the respective credential type folder. For example, `"version": "v0.0.1"` corresponds to the `v0.0.1` folder within the credential type folder.
+
+### Data Path
+
+The `dataPath` value is the relative location of the credential you want to test against the schema type and version.
+
+## Adding test credentials
+
+To test credentials developed or produced by a UNTP implementation against the core UNTP data model:
+
+1. Create a directory to store the credentials you want to test:
+
+```bash
+cd packages/untp-test-suite
+mkdir credentials
+```
+
+2. Add the credentials you want to test to the directory created in the previous step. The files should have unique names and be in JSON format:
+
+```
+packages/
+└── untp-test-suite/
+    ├── credentials/
+        ├── aggregationEvent-sample.json
+        ├── conformityCredential-sample.json
+        ├── objectEvent-sample.json
+        ├── productPassport-sample.json
+        ├── transactionEvent-sample.json
+        └── transformationEvent-sample.json
+```
+
+3. Update the config file to point to the location of the credential you want to test within the corresponding object and save the file:
+
+```json
+{
+  "credentials": [
+    {
+      "type": "aggregationEvent",
+      "version": "v0.0.1",
+      "dataPath": "credentials/aggregationEvent-sample.json"
+    },
+    {
+      "type": "conformityCredential",
+      "version": "v0.0.1",
+      "dataPath": "credentials/conformityCredential-sample.json"
+    },
+    {
+      "type": "objectEvent",
+      "version": "v0.0.1",
+      "dataPath": "credentials/objectEvent-sample.json"
+    },
+    {
+      "type": "productPassport",
+      "version": "v0.0.1",
+      "dataPath": "credentials/productPassport-sample.json"
+    },
+    {
+      "type": "transactionEvent",
+      "version": "v0.0.1",
+      "dataPath": "credentials/transactionEvent-sample.json"
+    },
+    {
+      "type": "transformationEvent",
+      "version": "v0.0.1",
+      "dataPath": "credentials/transformationEvent-sample.json"
+    }
+  ]
+}
+```
+
+You have now successfully configured the Tier 2 test suite to test your credentials against the core UNTP data model.

documentation/docs/test-suites/semantic-interoperability/cli/extensions.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 7
+title: Extensions
+---
+
+import Disclaimer from './../../../_disclaimer.mdx';
+
+<Disclaimer />
+
+The [United Nations Transparency Protocol (UNTP)](https://uncefact.github.io/spec-untp/) allows for extensions to its core data model. The UNTP Semantic Interoperability Test Suite can validate these extensions, ensuring they remain compliant with the core UNTP data model. This enables implementors to prototype and test custom credential types or additional properties while maintaining conformance with the UNTP protocol.
+
+## Adding a Custom Schema
+
+1. Create a new directory for your schema:
+
+```
+packages/
+└── untp-test-suite/
+    └── src/
+        └── schemas/
+            └── myCustomCredential/
+                └── v0.0.1/
+                    └── schema.json
+```
+
+2. Define your schema in `schema.json`, extending the core UNTP model as needed.
+
+3. Update `credentials.json` to include your new credential type:
+
+```json
+{
+  "credentials": [
+    // ... existing credentials
+    {
+      "type": "myCustomCredential",
+      "version": "v0.0.1",
+      "dataPath": "credentials/myCustomCredential-sample.json"
+    }
+  ]
+}
+```
+
+4. Create a sample credential file matching your schema.
+
+5. Run the test suite to validate your extended credential:
+
+```bash
+yarn run untp test
+```
+
+By following these steps, you can prototype extensions to the UNTP data model while ensuring compatibility with the core specification.
+
+Remember to thoroughly test your extensions and consider submitting valuable additions to the [UNTP community](https://github.com/uncefact/tests-untp) for potential inclusion in future versions of the protocol or submit your extension to the [extensions register](https://uncefact.github.io/spec-untp/docs/extensions).

documentation/docs/test-suites/semantic-interoperability/cli/index.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 3
+title: CLI
+---
+
+import Disclaimer from './../../../\_disclaimer.mdx';
+
+<Disclaimer />
+
+The [United Nations Transparency Protocol (UNTP)](https://uncefact.github.io/spec-untp/) Semantic Interoperability Test Suite CLI is a powerful tool designed for rapid validation of credentials produced by UNTP implementers and implementations. This suite ensures that the credentials comply with the core UNTP data model, making it an essential resource for developers, organisations and communities working with the UNTP protocol.
+
+## Key Features
+
+- **Rapid Validation**: Quickly verify the compliance of UNTP credentials with the core data model.
+- **Prototype Testing**: Ideal for credential development, allowing you to prototype and test extensions to the UNTP protocol.
+- **Flexibility**: Suitable for both implementation testing and exploratory development.
+
+By the end of this section, you will have a solid understanding of how to install, configure and use the CLI to validate UNTP credentials. You will be familiar with the configuration file structure, available commands and how to test your extensions against the core UNTP data model.

documentation/docs/test-suites/semantic-interoperability/cli/installation.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 4
+title: Installation
+---
+
+import Disclaimer from './../../../\_disclaimer.mdx';
+
+<Disclaimer />
+
+Before you begin installing the Tier 2 test suite CLI, ensure that you have the following prerequisites in place:
+
+### Prerequisites
+
+1. Clone the repository: 
+   ```
+   git clone https://github.com/uncefact/tests-untp.git
+   ```
+
+2. Node.js version 20.12.2: Make sure you have Node.js version 20.12.2 installed on your system. You can download it from the official Node.js website: [https://nodejs.org](https://nodejs.org)
+
+3. Yarn version 1.22.17: Ensure that you have Yarn version 1.22.17 installed. You can install it by running the following command:
+   ```
+   npm install -g yarn@1.22.17
+   ```
+
+### Installation Steps
+
+Once you have met the prerequisites, follow these steps to install the dependencies:
+
+1. Navigate to the cloned repository directory:
+   ```
+   cd tests-untp/packages/untp-test-suite
+   ```
+
+2. Install the dependencies using Yarn:
+   ```
+   yarn install
+   ```
+
+3. Build the test suite:
+   ```
+   yarn build
+   ```
+
+After completing these steps, you will have all the necessary dependencies installed.
+
+In the next section, we will initialise and explore the configuration file for the test suite.

documentation/docs/test-suites/semantic-interoperability/cli/usage.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 6  
+title: Usage
+---
+
+import Disclaimer from './../../../_disclaimer.mdx';
+
+<Disclaimer />
+
+Once you have configured the test suite, you can run it to validate your UNTP credentials.
+
+## Running the Test Suite
+
+To run the test suite with the configuration defined in the [Configuration section](/docs/test-suites/semantic-interoperability/cli/configuration):
+
+```bash
+yarn run untp test
+```
+
+To use a specific configuration file:
+
+```bash 
+yarn run untp test --config path/to/credentials.json
+```
+
+## Test Results
+
+The test suite validates each credential against its corresponding schema and provides a summary of results.
+
+### Result Overview
+
+For each tested credential, you will see:
+- Credential type
+- Version tested
+- Test result status
+
+### Result Categories
+
+1. **Pass**: The credential fully conforms to the core UNTP data model without extensions.
+
+2. **Warn**: The credential conforms to the core UNTP data model but includes extensions.
+   - Review your extensions to ensure they are intentional.
+
+3. **Fail**: The credential does not conform to the core UNTP data model.
+   - Review and address each error to ensure compliance.
+
+### Detailed Feedback
+
+For warnings and failures, you will receive:
+- Specific properties causing issues
+- Brief descriptions of each problem
+- Suggestions for resolution (where applicable)
+
+## Next Steps
+
+After successfully validating your credentials, you may want to explore extending the UNTP data model for your specific use case in the next section.