Documentation

Author: nichtich

README.md

@@ -13,6 +13,7 @@ This web service implements a **[Data Validation API](#API)** being specified as
   - [From sources](#from-sources)
   - [With Docker](#with-docker)
 - [Configuration](#configuration)
+  - [Service settings](#service-settings)
   - [Profiles](#profiles)
   - [Checks](#checks)
 - [API](#api)
@@ -33,7 +34,7 @@ Requires basic development toolchain (`sudo apt install build-essential`) and Py
 
 1. clone repository: `git clone https://github.com/gbv/validation-api-ws.git && cd validation-api-ws`
 2. run `make deps` to install dependencies
-3. optionally [Configure](#configuration] the instance with 
+3. optionally [Configure](#configuration) the instance
 3. `make start` 
 
 ### Via Docker
@@ -44,7 +45,7 @@ A Docker image is automatically build [and published](https://github.com/orgs/gb
 docker run --rm -p 7007:7007 ghcr.io/gbv/validation-api-ws:main
 ~~~
 
-A [configuration] directory or file must exist and be mounted:
+A [configuration](#configuration) directory or file must exist and be mounted:
 
 ~~~sh
 test -f data/config.json && docker run --rm -p 7007:7007 --volume config:/app/config ghcr.io/gbv/validation-api-ws:main
@@ -53,7 +54,7 @@ test -f config.json && docker run --rm -p 7007:7007 --volume ./config.json:/app/
 
 ## Configuration
 
-The [default configuration](config.default.json) contains some base formats. To defined the application profiles to be checked against, create a configuration file in JSON format at `config.json` in the current directory or in the local subdirectory `config`. It is also possible to pass the location of config file or directory with argument `--config` at startup. The configuration file must contain field `profiles` with a list of [profile objects](#profiles) and it can contain additional service settings.
+The [default configuration](config.default.json) contains some base formats. To defined application profiles to be checked against, create a configuration file in JSON format at `config.json` in the current directory or in the local subdirectory `config`. It is also possible to pass the location of config file or directory with argument `--config` at startup. The configuration file must contain field `profiles` with a list of [profile objects](#profiles) and it can contain additional service settings.
 
 ### Service settings
 
@@ -95,9 +96,11 @@ Validate data against an application profile and return a list of errors in [Dat
 - `url` to be downloaded from an URL (if the service is configured with `downloads` directory)
 - `file` to be read from a local file in the stage directory of the server (if the service is configured with `stage` directory)
 
-Status code is always 200 if validation could be executed, no matter whether errors have been found or not.
+Status code is always 200 if validation could be executed, no matter whether errors have been found or not. For example validating the string `[1,2` at default profile `json` results in the following validation response. The error position (after the fourth character on line 1) is referenced with multiple dimensions. Dimension values are always strings.
 
-For example validating the string `[1,2` at default profile `json` (`curl http://localhost:7007/json/validate -d '[1,2'`) results in the following validation response. The error position (after the fourth character on line 1) is referenced with multiple dimensions. Dimension values are always strings.
+~~~sh
+curl http://localhost:7007/json/validate -d '[1,2'
+~~~
 
 ~~~json
 [
@@ -138,10 +141,10 @@ test -f config.json && docker run --rm -p 7007:7007 --volume ./config.json:/app/
 
 See also <https://github.com/gbv/validation-server> for a previous implementation in NodeJS. Both implementations may converge
 
-This work is [funded by DFG (project "AQinDa")](https://gepris.dfg.de/gepris/projekt/521659096)
-
 ## License
 
 MIT © 2025- Verbundzentrale des GBV (VZG)
 
+This work has been [funded by DFG in project *AQinDa*](https://gepris.dfg.de/gepris/projekt/521659096)
+
 [Data Validation Error Format]: https://gbv.github.io/validation-error-format/

config.default.json

@@ -6,10 +6,13 @@
   "profiles": [
     {
       "id": "json",
+      "url": "https://json.org/",
+      "description": "Check data to be JSON",
       "checks": ["json"]
     },
     {
       "id": "xml",
+      "description": "Check data to be well-formed XML",
       "checks": ["xml"]
     }
   ]

lib/validate/profiles-schema.json

@@ -13,11 +13,8 @@
         "type": "string"
       },
       "description": {
-        "description": "Short description(s) of the profile, indexed by language tag (e.g. 'en')",
-        "type": "object",
-        "propertyNames": {
-          "pattern": "^[a-z]{2,}$"
-        }
+        "description": "Short description of the profile",
+        "type": "string"
       },
       "url": {
         "description": "URL of a document about the profile",

templates/index.html

@@ -9,23 +9,18 @@
       margin: 20px;
       font-family: sans-serif;
     }
-    ul {
-      list-style-type: none;
-      padding: 0 1em;
-    }
-    li {
-      text-indent: -2.5em;
-      padding-left: 2.5em;
-      margin-bottom: 0.2em;
-    }
     a {
       text-decoration: none;
       color: rgb(96, 143, 219);
     }
     a:hover, a:active {
       text-decoration: underline;
     }
+    dt {
+      font-weight: bold;
+    }
     footer {
+      padding-top: 1em;
       color: #999;
     }
     </style>
@@ -39,11 +34,47 @@ <h2>API Endpoints</h2>
     <dl>
       <dt><a href="profiles">GET profiles</a></dt>
       <dd>
+        Return a list of supported application profiles
           ⇒ <a href="https://github.com/gbv/validation-api-ws#get-profiles">help</a>
       </dd>
+      <dt>GET {profile}/validate</dt>
+      <dd>
+        Validate data against an application profile
+          ⇒ <a href="https://github.com/gbv/validation-api-ws#get-profilevalidate">help</a>
+      </dd>
+      <dt>POST {profile}/validate</dt>
+      <dd>
+        Validate data against an application profile
+          ⇒ <a href="https://github.com/gbv/validation-api-ws#post-profilevalidate">help</a>
+      </dd>
     </p>
+    <h2>Profiles</h2>
+    <ul id="profiles">
+    </ul>
     <footer>
       powered by <a href="https://github.com/gbv/validation-api-ws">validation-service</a>
     </footer>
   </body>
-</html> 
+</html>
+<script>
+fetch("profiles").then(res => res.json()).then(profiles => {
+  const ul = document.getElementById("profiles")
+  profiles.forEach(({ id, url, description }) => {
+    const li = document.createElement('li')
+    if (url) {
+      const a = document.createElement('a')
+      a.href = url
+      a.textContent = id
+      li.appendChild(a)
+    } else {
+      li.textContent = id
+    }
+    if (description) {
+      const span = document.createElement('span')
+      span.textContent = ": " + description
+      li.appendChild(span)
+    }
+    ul.appendChild(li)
+  })
+})
+</script>