Merge pull request #312 from buildingSMART/IVS-796-allowlisting-doc

Allowlisting docs (IVS-796)

Author: Ghesselink

.github/workflows/build-and-deploy-docs.yml

@@ -1,8 +1,12 @@
 name: "Build docs with Sphinx and deploy to Github Pages"
 
-on: 
+on:
   push:
-    branches: docs/gh-pages
+    branches:
+      - development
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
 
 jobs:
   build_and_deploy:

.github/workflows/build-docs.yml

@@ -1,8 +1,11 @@
 name: "Build docs with Sphinx"
 
-on: 
+on:
   pull_request:
-    branches: docs/gh-pages
+    branches:
+      - development
+    paths:
+      - 'docs/**'
 
 jobs:
   build_and_deploy:

docs/dev/api_quickstart.md

@@ -6,9 +6,9 @@ The preview of the Validation Service API is available at `https://dev.validate.
 ## Documentation
 
 Auto-generated documentation is available in both
-[Swagger](https://dev.validate.buildingsmart.org/api/swagger-ui)
+[Swagger](https://dev.validate.buildingsmart.org/api/v1/swagger-ui)
 and
-[Redocly](https://dev.validate.buildingsmart.org/api/redoc)
+[Redocly](https://dev.validate.buildingsmart.org/api/v1/redoc)
 formats.
 
 ## Auth token
@@ -23,21 +23,21 @@ You can use this token either as a Bearer token or use it as the password in com
 1. Sample to show difference between Token vs. Basic authentication
 
     ``` shell
-     curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' --header 'Authorization: Token <TOKEN>'
+     curl -X GET --location 'https://dev.validate.buildingsmart.org/api/v1/validationrequest' --header 'Authorization: Token <TOKEN>'
     ```
 
    -or-
 
     ```shell
-    curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' --header 'Authorization: Basic <HASH>'
+    curl -X GET --location 'https://dev.validate.buildingsmart.org/api/v1/validationrequest' --header 'Authorization: Basic <HASH>'
     ```
 
    where `<HASH>` is the Base64-encoded email and token as password, separated by a colon, eg. base64(johndoe@gmail.com:abcdefgh12345)
 
 2. Submit a POST request to the `/validationrequest` endpoint to initiate a new Validation Request (requires a file name and the file contents):
 
    ```shell
-      curl -X POST --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' \
+      curl -X POST --location 'https://dev.validate.buildingsmart.org/api/v1/validationrequest' \
 
       --header 'Authorization: Token <TOKEN>' \
 
@@ -51,23 +51,23 @@ You can use this token either as a Bearer token or use it as the password in com
 3. Fetch details of a single ValidationRequest via a GET request to the `/validationrequest` endpoint
 
    ```shell
-      curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/r767775526' --header 'Authorization: Token <TOKEN>'
+      curl -X GET --location 'https://dev.validate.buildingsmart.org/api/v1/validationrequest/r767775526' --header 'Authorization: Token <TOKEN>'
    ```
 
 4. Fetch details of all ValidationRequests via a GET request to the `/validationrequest` endpoint
 
    ```shell
-   curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' --header 'Authorization: Token <TOKEN>'
+   curl -X GET --location 'https://dev.validate.buildingsmart.org/api/v1/validationrequest' --header 'Authorization: Token <TOKEN>'
    ```
 
 5. Fetch all ValidationTasks for two ValidationRequests via a GET request to the `/validationtask` endpoint
 
    ```shell
-   curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationtask/?request_public_id=r75257132,r383446691' --header 'Authorization: Token <TOKEN>'
+   curl -X GET --location 'https://dev.validate.buildingsmart.org/api/v1/validationtask?request_public_id=r75257132,r383446691' --header 'Authorization: Token <TOKEN>'
    ```
 
 6. Fetch all the outcomes of a single ValidationRequest via a GET request to the `/validationoutcome` endpoint
 
    ```shell
-   curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationoutcome/?request_public_id=r75257132' --header 'Authorization: Token <TOKEN>'
+   curl -X GET --location 'https://dev.validate.buildingsmart.org/api/v1/validationoutcome?request_public_id=r75257132' --header 'Authorization: Token <TOKEN>'
    ```

docs/dev/validate_readme.md

@@ -1,4 +1,3 @@
-
 # Application Structure
 
 ## System Architecture

docs/ref/index.md

@@ -20,6 +20,21 @@ Typically, this audience is interested in software certification as well.
 :relative-images:
 ```
 
+## Allowlisting
+
+IFC schema definitions occasionally include typos or other minor incorrections.
+For example, if a vendor has implemented IFC export capabilities using the correct spelling,
+the strict checking of the Validation Service will return an error because there is not an exact match with the schema definition.
+
+For this reason, an allowlist capability has been built in to the platform so that
+implementers are not unfairly penalized for an error that originates in the schema definition,
+not their implementation.
+
+This capability runs as a post-processing step after the validation process has completed.
+For validation outcomes returning more than 10 instances, the allowlisting is only applied to the first 10.
+This is considered acceptable as it can only ever result in a false positive (green result displayed on the scoreboard)
+and never a false negative (unfair red result displayed on the scoreboard).
+
 ## Additional Information for Normative Rules
 
 Occasionally, the Validation Service team will receive inquiries regarding a specific rule that requires