Merge pull request #104 from buildingSMART/doc_update

Update API description for new release
buildingSMART · Sep 25, 2024 · 9969e13 · 9969e13
2 parents a2560a9 + d54c3aa
commit 9969e13
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 23 deletions.
diff --git a/Documentation/API version history.md b/Documentation/API version history.md
@@ -12,6 +12,15 @@ A new version will only be created if it 'breaks' the current version. For examp
 
 If there is a new version of an API the previous version will be supported for at least 6 months after releasing the new version. 
 
+## 2024-09-23
+
+Changed API methods:
+ * api/Dictionary/v1/Classes:
+    - Option "RelatedIfcEntity" added
+ * api/TextSearch/v2:
+    - Field "code" added to output of the Dictionaries list
+
+
 ## 2024-08-16
 
 New API methods:

diff --git a/Documentation/bSDD JSON import model.md b/Documentation/bSDD JSON import model.md
@@ -379,7 +379,7 @@ It is possible to reference other resources from the same dictionary using doubl
 
 **2023-07 - Important notification:**
 
-> As we're continuously improving bSDD, we've updated all identifiers: the dash between dictionary code and dictionary version has been replaced by a dash, e.g.:
+> As we're continuously improving bSDD, we've updated all identifiers: the dash between dictionary code and dictionary version has been replaced by a slash, e.g.:
 >  https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0.0/class/apple will now be https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs/1.0.0/class/apple
 > 
 > We will support supplying and retrieving data using the dash between dictionary code and version for (at least) 4 months. But please do note that only identifiers in the new format are returned by the bSDD APIs.

diff --git a/Documentation/bSDD OpenAPI.yaml b/Documentation/bSDD OpenAPI.yaml
@@ -353,7 +353,7 @@ paths:
     get:
       tags:
         - Dictionary
-      summary: "Get Dictionary with tree of classes.\r\nThis one replaces /api/Domain. See https://github.com/buildingSMART/bSDD/blob/master/Documentation/API%20version%20history.md for changes."
+      summary: Get Dictionary with (tree of) classes
       parameters:
         - name: Uri
           in: query
@@ -377,7 +377,12 @@ paths:
             type: string
         - name: SearchText
           in: query
-          description: "Optional filter text.\r\nNot supported when UseNestedClasses = true"
+          description: "Optional filter text.\r\nIgnored when UseNestedClasses = true"
+          schema:
+            type: string
+        - name: RelatedIfcEntity
+          in: query
+          description: "Optional filter on related IFC entity. It accepts an IFC entity code (e.g. IfcWall) or uri (e.g. https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3/class/IfcWall).\r\nWhen a code is supplied, finding matching classes ignores the IFC version.\r\nIgnored when UseNestedClasses = true"
           schema:
             type: string
         - name: Offset
@@ -409,31 +414,40 @@ paths:
           content:
             text/plain:
               schema:
-                $ref: '#/components/schemas/DictionaryClassesResponseContract.v1'
+                $ref: >-
+                  #/components/schemas/DictionaryClassesResponseContract.v1.Classes
             application/json:
               schema:
-                $ref: '#/components/schemas/DictionaryClassesResponseContract.v1'
+                $ref: >-
+                  #/components/schemas/DictionaryClassesResponseContract.v1.Classes
             text/json:
               schema:
-                $ref: '#/components/schemas/DictionaryClassesResponseContract.v1'
+                $ref: >-
+                  #/components/schemas/DictionaryClassesResponseContract.v1.Classes
             application/xml:
               schema:
-                $ref: '#/components/schemas/DictionaryClassesResponseContract.v1'
+                $ref: >-
+                  #/components/schemas/DictionaryClassesResponseContract.v1.Classes
             text/xml:
               schema:
-                $ref: '#/components/schemas/DictionaryClassesResponseContract.v1'
+                $ref: >-
+                  #/components/schemas/DictionaryClassesResponseContract.v1.Classes
             text/html:
               schema:
-                $ref: '#/components/schemas/DictionaryClassesResponseContract.v1'
+                $ref: >-
+                  #/components/schemas/DictionaryClassesResponseContract.v1.Classes
             text/turtle:
               schema:
-                $ref: '#/components/schemas/DictionaryClassesResponseContract.v1'
+                $ref: >-
+                  #/components/schemas/DictionaryClassesResponseContract.v1.Classes
             application/x-turtle:
               schema:
-                $ref: '#/components/schemas/DictionaryClassesResponseContract.v1'
+                $ref: >-
+                  #/components/schemas/DictionaryClassesResponseContract.v1.Classes
             application/rdf+xml:
               schema:
-                $ref: '#/components/schemas/DictionaryClassesResponseContract.v1'
+                $ref: >-
+                  #/components/schemas/DictionaryClassesResponseContract.v1.Classes
   /api/Dictionary/v1/Properties:
     get:
       tags:
@@ -3051,7 +3065,7 @@ components:
           description: List of parents of this class till root
           nullable: true
       additionalProperties: false
-    ClassListItemContract.v1:
+    ClassListItemContract.v1.Classes:
       type: object
       properties:
         uri:
@@ -3079,7 +3093,7 @@ components:
         children:
           type: array
           items:
-            $ref: '#/components/schemas/ClassListItemContract.v1'
+            $ref: '#/components/schemas/ClassListItemContract.v1.Classes'
           nullable: true
       additionalProperties: false
     ClassPropertiesContract.v1:
@@ -4672,7 +4686,7 @@ components:
           type: string
           nullable: true
       additionalProperties: false
-    DictionaryClassesResponseContract.v1:
+    DictionaryClassesResponseContract.v1.Classes:
       required:
         - code
         - defaultLanguageCode
@@ -4719,7 +4733,9 @@ components:
           nullable: true
         licenseUrl:
           type: string
-          description: URL where you can find more details about the license
+          description: >-
+            URL where you can find more details about the license or default
+            link to info about licensing
           nullable: true
         qualityAssuranceProcedure:
           type: string
@@ -4755,7 +4771,7 @@ components:
         classes:
           type: array
           items:
-            $ref: '#/components/schemas/ClassListItemContract.v1'
+            $ref: '#/components/schemas/ClassListItemContract.v1.Classes'
           nullable: true
         classesTotalCount:
           type: integer
@@ -4819,7 +4835,9 @@ components:
           nullable: true
         licenseUrl:
           type: string
-          description: URL where you can find more details about the license
+          description: >-
+            URL where you can find more details about the license or default
+            link to info about licensing
           nullable: true
         qualityAssuranceProcedure:
           type: string
@@ -4906,7 +4924,9 @@ components:
           nullable: true
         licenseUrl:
           type: string
-          description: URL where you can find more details about the license
+          description: >-
+            URL where you can find more details about the license or default
+            link to info about licensing
           nullable: true
         qualityAssuranceProcedure:
           type: string
@@ -5021,7 +5041,9 @@ components:
           nullable: true
         licenseUrl:
           type: string
-          description: URL where you can find more details about the license
+          description: >-
+            URL where you can find more details about the license or default
+            link to info about licensing
           nullable: true
         qualityAssuranceProcedure:
           type: string
@@ -5091,7 +5113,9 @@ components:
           nullable: true
         licenseUrl:
           type: string
-          description: URL where you can find more details about the license
+          description: >-
+            URL where you can find more details about the license or default
+            link to info about licensing
           nullable: true
         qualityAssuranceProcedure:
           type: string
@@ -5187,7 +5211,9 @@ components:
           nullable: true
         licenseUrl:
           type: string
-          description: URL where you can find more details about the license
+          description: >-
+            URL where you can find more details about the license or default
+            link to info about licensing
           nullable: true
         qualityAssuranceProcedure:
           type: string
@@ -5262,7 +5288,9 @@ components:
           nullable: true
         licenseUrl:
           type: string
-          description: URL where you can find more details about the license
+          description: >-
+            URL where you can find more details about the license or default
+            link to info about licensing
           nullable: true
         qualityAssuranceProcedure:
           type: string
@@ -7568,6 +7596,7 @@ components:
       additionalProperties: false
     TextSearchResponseDictionaryContract.v2:
       required:
+        - code
         - isLatestVersion
         - isVerified
         - languages
@@ -7584,6 +7613,9 @@ components:
         organizationName:
           minLength: 1
           type: string
+        code:
+          minLength: 1
+          type: string
         name:
           minLength: 1
           type: string