Merge pull request #28 from fairdataihub/validator

feat: ✨ Validator Documentation for Dev + Staging site mention for Zenodo Sandbox API

Author: slugb0t

docs/.vitepress/config.js

@@ -144,6 +144,7 @@ function appSidebarGuide() {
       items: [
         { text: 'Bot Feature', link: '/dev/bot.md' },
         { text: 'UI Page', link: '/dev/ui.md' },
+        { text: 'Validation Feature', link: '/dev/validator.md' },
       ],
     },
   ];

docs/dev/bot.md

@@ -12,7 +12,7 @@ head:
 
 The best way to learn how to add a new feature to Codefair is to complete our step-by-step tutorial below:
 
-The Codefair repository is split into three main subfolders: `ui`, `bot` and `validator`. This tutorial will guide you through the process of adding a new check feature to Codefair bot. Codefair is modularized in a way to try and make it easy for anyone to plug in a new check with how our code structure is created. We have a main function that calls all the available checks `checkForCompliance()` and within there you will call your new feature. The example feature will below will guide you through the standard we have for creating a new feature to check if a `expecto_patronum.md` file exists. This feature will create append the detailed results to a string that will then be used for the GitHub issue body. A clickable badge to direct a user to the Codefair UI to add the file.
+The Codefair repository is split into three main subfolders: `ui`, `bot` and `validator`. This tutorial will guide you through the process of adding a new check feature to Codefair bot. Codefair is modularized in a way to try and make it easy for anyone to plug in a new check with how our code structure is created. We have a main function that calls all the available checks `checkForCompliance()` and within there you will call your new feature. The example feature will below will guide you through the standard we have for creating a new feature to check if a `expecto_patronum.md` file exists. This feature will append the detailed results to an object that will then be used for the GitHub issue renderer. A clickable badge to direct a user to the Codefair UI to add the file is created for each compliance check to allow users to quickly handle a FAIR compliance check.
 
 This page will focus on the steps required to add the new feature to the Codefair bot. To learn how to add a UI feature, you can refer to the [UI documentation](./ui.md).
 
@@ -74,7 +74,7 @@ const issueBody = await renderIssues(
 );
 ```
 
-> **Note**
+> :bulb: **Note**
 > The event listeners we have can be found in the `bot/index.js` file. If you need an event listener not already available you can add it in this file. A list of GitHub event listeners is available [here](https://docs.github.com/en/webhooks/webhook-events-and-payloads).
 
 ## **Step 3**: Create schema for the new check

docs/dev/validator.md

@@ -0,0 +1,118 @@
+---
+lang: en-US
+title: Validation Usage
+description: Adding a validation feature to Codefair
+head:
+  - - meta
+    - name: og:image
+      content: https://kalai.fairdataihub.org/api/generate?title=Codefair%20Documentation&description=Adding%20a%20validation%20feature%20to%20Codefair&app=codefair&org=fairdataihub
+---
+
+# :hammer_and_wrench: Adding a Validation Endpoint
+
+Extend Codefair’s **Validator Microservice** (Flask + Flask-RESTX) by adding custom HTTP endpoints under `validator/apis`. Follow the sections below to seamlessly integrate your new validation logic.
+
+## :sparkles: Overview
+
+This guide walks through creating a new validation route, securing inputs, updating dependencies, and testing your endpoint locally.
+
+## :bookmark: Prerequisites
+
+- A Python 3.8+ environment
+- Familiarity with Flask and RESTful APIs
+
+## :rocket: Register a New API Route
+
+Create a new route in `validator/apis/__init__.py`:
+
+```python
+@api.route('/validate-json', endpoint='validate-json')
+class ValidateJSON(Resource):
+    """Validate a JSON file at given path or URL"""
+
+    @api.response(200, 'Success')
+    @api.response(400, 'Validation Error')
+    @api.expect(
+        api.parser()
+           .add_argument(
+               'file_path', type=str,
+               help='The path or URL of the JSON file',
+               required=True,
+           )
+    )
+    def post(self):
+        """Validate a JSON file"""
+        args = api.payload or {}
+        file_path = args.get('file_path')
+
+        # Input validation
+        if not file_path:
+            return {'message': 'Validation Error', 'error': 'file_path is required'}, 400
+
+        # Instantiate and run your custom validator
+        validator = JsonValidator()
+        result = validator.validate(file_path)
+
+        if result.get('valid'):
+            return {'message': 'valid', 'details': result['message']}, 200
+        else:
+            return {'message': 'invalid', 'error': result['message']}, 400
+```
+
+> 📌 You can base this on existing validators like `ValidateCWL` for consistent style.
+
+## :lock: Input Sanitization & Security
+
+Ensure robust input handling to prevent attacks:
+
+- **Path traversal:** Reject `..` or leading `/` in `file_path`.
+- **Command injection:** Forbid characters like `;`, `&`, `|` or use `shlex.quote()` if invoking subprocesses.
+- **Remote URLs:** Allow only `http://` and `https://` when downloading content.
+
+Reuse helper functions (e.g., `clean_output`) from other endpoints to sanitize and parse external tool outputs.
+
+## :package: Update Dependencies & Entrypoint
+
+1. **Dependencies:** If your validator relies on new libraries (e.g., `jsonschema`), add them to `validator/requirements.txt`.
+2. **Entrypoint:** No changes required in `validator/app.py`—all `@api.route` decorators are auto-registered via `api.init_app(app)`.
+
+> 🔄 Remember to import your new validator module in `validator/app.py` if it’s not picked up automatically:
+>
+> ```python
+> import validators.json_validator
+> ```
+
+## :white_check_mark: Testing Your Endpoint
+
+1. **Activate your environment:**
+
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   pip install -r validator/requirements.txt
+   ```
+
+3. **Run the service:**
+
+   ```bash
+   python validator/app.py --host $HOST --port $PORT
+   ```
+
+4. **Test via `curl` or Postman:**
+
+   ```bash
+   curl -X POST http://localhost:5000/validate-json \
+       -H 'Content-Type: application/json' \
+       -d '{"file_path": "path/to/file.json"}'
+   ```
+
+Look for a JSON response indicating `valid` or `invalid` along with details or error messages.
+
+---
+
+Happy validating with Codefair! 🚀

docs/docs/archive.md

@@ -12,6 +12,10 @@ head:
 
 In the [FAIR4RS Principles](https://doi.org/10.1038/s41597-022-01710-x), many of the principles aimed at making research software **Findable** and **Accessible** can be fulfilled by archiving the software in a suitable archival repository. This is critical to ensure the long-term preservation and accessibility of the software. One recommended approach, as prescribed by the [FAIR-BioRS guidelines](https://doi.org/10.1038/s41597-023-02463-x), is to archive each release of your software on Zenodo.
 
+::: tip
+Our staging site at <https://staging.codefair.io/> uses the Zenodo Sandbox API rather than the production Zenodo API. You can test the full FAIR release workflow here before archiving your software on the live Zenodo platform.
+:::
+
 ::: warning
 There is a webhook method that allows you to [automatically archive each GitHub release on Zenodo](https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content). However, please note that this method does not provide the DOI before the software is archived on Zenodo, meaning the DOI cannot be included in the software's metadata on GitHub beforehand. This does not align with the FAIR4RS Principle F3, which states: "Metadata should clearly and explicitly include the identifier of the software they describe."
 :::