From fa5a645c948aabbf30749a68dcf0b2583466cf25 Mon Sep 17 00:00:00 2001 From: Scott Lecher Date: Tue, 15 Jul 2025 12:13:43 -0400 Subject: [PATCH 1/2] update docs (cherry pick from IVS-319) - add API quick start - update copyright year and version number - add link to python behave - remove error codes in Appendix --- docs/dev/api_quickstart.md | 73 ++++++++++++++++++++++++++++ docs/dev/ifc_gherkin_rules_readme.md | 2 +- docs/dev/index.md | 4 ++ 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 docs/dev/api_quickstart.md diff --git a/docs/dev/api_quickstart.md b/docs/dev/api_quickstart.md new file mode 100644 index 00000000..6bf4d1bf --- /dev/null +++ b/docs/dev/api_quickstart.md @@ -0,0 +1,73 @@ +# API Quick Start + + +The preview of the Validation Service API is available at `https://dev.validate.buildingsmart.org/api`. + +## Documentation + +Auto-generated documentation is available in both +[Swagger](https://dev.validate.buildingsmart.org/api/swagger-ui) +and +[Redocly](https://dev.validate.buildingsmart.org/api/redoc) +formats. + +## Auth token + +You will need an Authentication token before making calls to the API, +which can be obtained by emailing [validate@buildingsmart.org](mailto:validate@buildingsmart.org). + +You can use this token either as a Bearer token or use it as the password in combination with your username/email for basic authentication. + +## Example usage + +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 ' + ``` + + -or- + + ```shell + curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' --header 'Authorization: Basic ' + ``` + + where `` 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/' \ + + --header 'Authorization: Token ' \ + + --form 'file_name="valid_file.ifc"' \ + + --form 'file=@"/.../buildingSMART/sample_files/valid_file.ifc"' + ``` + + It will return a JSON object that includes the id (public_id) you can use for future GET requests. + +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 ' + ``` + +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 ' + ``` + +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 ' + ``` + +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 ' + ``` diff --git a/docs/dev/ifc_gherkin_rules_readme.md b/docs/dev/ifc_gherkin_rules_readme.md index b4f42f09..244ed755 100644 --- a/docs/dev/ifc_gherkin_rules_readme.md +++ b/docs/dev/ifc_gherkin_rules_readme.md @@ -9,7 +9,7 @@ An overview of the implemented rules and python step implementation functions is ## Making changes -The rules developed in this repository follow the general ideas of Gherkin and its python implementation behave. +The rules developed in this repository follow the general ideas of Gherkin and its python implementation [behave](https://behave.readthedocs.io/en/stable/). This means there are human-readable definitions of rules and Python implementations. diff --git a/docs/dev/index.md b/docs/dev/index.md index 3e3e42b5..c0c01d41 100644 --- a/docs/dev/index.md +++ b/docs/dev/index.md @@ -4,6 +4,10 @@ :heading-offset: 1 ``` +```{include} api_quickstart.md +:heading-offset: 1 +``` + ```{include} ifc_gherkin_rules_readme.md :heading-offset: 1 ``` From 4df38f6b51c495d1e0a2039693d816fe69d1ac39 Mon Sep 17 00:00:00 2001 From: Scott Lecher Date: Mon, 20 Apr 2026 18:07:17 -0400 Subject: [PATCH 2/2] add reference information for BRP003 (IVS-842) --- docs/dev/api_quickstart.md | 10 +++++----- docs/ref/index.md | 5 +++++ docs/ref/normative-rules/BRP003.md | 13 +++++++++++++ 3 files changed, 23 insertions(+), 5 deletions(-) create mode 100644 docs/ref/normative-rules/BRP003.md diff --git a/docs/dev/api_quickstart.md b/docs/dev/api_quickstart.md index 6bf4d1bf..7b33a1ab 100644 --- a/docs/dev/api_quickstart.md +++ b/docs/dev/api_quickstart.md @@ -6,14 +6,14 @@ 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/swagger-ui) and [Redocly](https://dev.validate.buildingsmart.org/api/redoc) formats. ## Auth token -You will need an Authentication token before making calls to the API, +You will need an Authentication token before making calls to the API, which can be obtained by emailing [validate@buildingsmart.org](mailto:validate@buildingsmart.org). You can use this token either as a Bearer token or use it as the password in combination with your username/email for basic authentication. @@ -26,13 +26,13 @@ You can use this token either as a Bearer token or use it as the password in com curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' --header 'Authorization: Token ' ``` - -or- + -or- ```shell curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' --header 'Authorization: Basic ' ``` - where `` is the Base64-encoded email and token as password, separated by a colon, eg. base64(johndoe@gmail.com:abcdefgh12345) + where `` 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): @@ -65,7 +65,7 @@ You can use this token either as a Bearer token or use it as the password in com ```shell curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationtask/?request_public_id=r75257132,r383446691' --header 'Authorization: Token ' ``` - + 6. Fetch all the outcomes of a single ValidationRequest via a GET request to the `/validationoutcome` endpoint ```shell diff --git a/docs/ref/index.md b/docs/ref/index.md index 9c4e7b25..35ebc2d7 100644 --- a/docs/ref/index.md +++ b/docs/ref/index.md @@ -35,3 +35,8 @@ The responses to these inquiries are provided here for the benefit of the entire :heading-offset: 1 :relative-images: ``` + +```{include} ./normative-rules/BRP003.md +:heading-offset: 1 +:relative-images: +``` diff --git a/docs/ref/normative-rules/BRP003.md b/docs/ref/normative-rules/BRP003.md new file mode 100644 index 00000000..d6c2748b --- /dev/null +++ b/docs/ref/normative-rules/BRP003.md @@ -0,0 +1,13 @@ +# BRP003 + +This rule confirms that geometric faces indicated as being planar +do actually lie on the same plane. + +## Approach + +1. Derive the plane from the outer boundary; uses Newell’s method for the normal and compute d from the average of the input points. +2. Validate outer and inner boundaries by projecting their points onto that plane and checking that each projection distance is within the representation context precision. + +```{note} +All calculations are performed in 128-bit floating point. +```