Merge pull request #106 from atlanticwave-sdx/105.schema-updates

Validate and document schemas
atlanticwave-sdx · Aug 18, 2023 · 29c46bf · 29c46bf
2 parents 2548a8e + 0a372df
commit 29c46bf
Show file tree

Hide file tree

Showing 12 changed files with 216 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -64,16 +64,27 @@ supposed to generated and pass on to the SDX controller.
 
 ## Topology description schemas
 
-There are defined in the `schema` subfolder. Some attributes of each
-objects are requied (Can be found in the API definition) while some
-are optional. Two attributes are worth of mentioning: 
+There are some JSON schemas defined in the [schemas] subfolder. These
+are meant to guide and validate model development.
+
+Some attributes of each objects are requied (can be found in the API
+definition) while some are optional. Two attributes are worth
+mentioning:
 
 1. In the `service` object, there is a `vendor` attribute for the
 domain to list device vendors that are NOT in its domain.
 
 2. In topology, link, node, and port objects, there is a `private`
 attibute for the domain to list attributes that need to kept private.
 
+There are some unit tests to validate JSON blobs we have against their
+corresponding schemas.  Another nifty tool is [check-jsonschema]:
+
+```console
+$ check-jsonschema --schemafile schemas/Topology.json \
+    src/sdx_datamodel/data/topologies/amlight.json
+```
+
 
 ## Developing the library
 
@@ -118,3 +129,8 @@ $ python -m unittest -v tests.test_topology_validator
 
 [datamodel-cov-badge]: https://coveralls.io/repos/github/atlanticwave-sdx/datamodel/badge.svg?branch=main (Coverage Status)
 [datamodel-cov]: https://coveralls.io/github/atlanticwave-sdx/datamodel?branch=main
+
+[check-jsonschema]: https://pypi.org/project/check-jsonschema/
+
+[schemas]: ./schemas
+
diff --git a/pyproject.toml b/pyproject.toml
@@ -31,6 +31,8 @@ Issues = "https://github.com/atlanticwave-sdx/datamodel/issues"
 test = [
     "pytest >= 7.1.2",
     "pytest-cov >= 3.0.0",
+    "jsonschema >= 4.19.0",
+    "jsonref >= 1.1.0",
 ]
 
 [options.packages.find]

diff --git a/schemas/Connection.json b/schemas/Connection.json
@@ -15,10 +15,10 @@
             "maximum": 7
         },
         "ingress_port": {
-            "$ref": "Port"
+            "$ref": "Port.json"
         },
         "egress_port": {
-            "$ref": "Port"
+            "$ref": "Port.json"
         },
         "end_time": {
             "type": "string",
@@ -47,14 +47,14 @@
             "type": "array",
             "items": [
                 {
-                    "$ref": "Link"
+                    "$ref": "Link.json"
                 }
             ]
         },
         "inclusive_links": {
             "type": "array",
             "items": {
-                "$ref": "Link"
+                "$ref": "Link.json"
             }
         },
         "bandwidth_required": {
@@ -101,7 +101,7 @@
             "type": "array",
             "items": [
                 {
-                    "$ref": "Path"
+                    "$ref": "Path.json"
                 }
             ]
         },
@@ -114,5 +114,10 @@
             ]
         }
     },
-    "required": ["id", "name", "ingress_port", "egress_port"]
-}
+    "required": [
+        "id",
+        "name",
+        "ingress_port",
+        "egress_port"
+    ]
+}
diff --git a/schemas/Link.json b/schemas/Link.json
@@ -19,7 +19,7 @@
             "uniqueItems": true,
             "items": [
                 {
-                    "$ref": "Port"
+                    "$ref": "Port.json"
                 }
             ]
         },
@@ -88,5 +88,9 @@
             }
         }
     },
-    "required": ["id", "name", "ports"]
-}
+    "required": [
+        "id",
+        "name",
+        "ports"
+    ]
+}
diff --git a/schemas/Location.json b/schemas/Location.json
@@ -18,4 +18,4 @@
         }
     },
     "required": []
-}
+}
diff --git a/schemas/Node.json b/schemas/Node.json
@@ -13,16 +13,21 @@
             "type": "string"
         },
         "location": {
-            "$ref": "location.json"
+            "$ref": "Location.json"
         },
         "ports": {
             "type": "array",
             "items": [
                 {
-                    "$ref": "port.json"
+                    "$ref": "Port.json"
                 }
             ]
         }
     },
-    "required": ["id", "location", "name", "ports"]
-}
+    "required": [
+        "id",
+        "location",
+        "name",
+        "ports"
+    ]
+}
diff --git a/schemas/Path.json b/schemas/Path.json
@@ -43,10 +43,14 @@
             "type": "array",
             "items": [
                 {
-                    "$ref": "Link"
+                    "$ref": "Link.json"
                 }
             ]
         }
     },
-    "required": ["id", "name", "links"]
-}
+    "required": [
+        "id",
+        "name",
+        "links"
+    ]
+}
diff --git a/schemas/Port.json b/schemas/Port.json
@@ -57,7 +57,7 @@
         "label_range": {
             "type": "array",
             "items": {
-                "type": "array",
+                "type": "string",
                 "minItems": 1,
                 "maxItems": 4096,
                 "uniqueItems": true,
@@ -94,5 +94,10 @@
             }
         }
     },
-    "required": ["id", "name", "node", "status"]
+    "required": [
+        "id",
+        "name",
+        "node",
+        "status"
+    ]
 }
diff --git a/schemas/Service.json b/schemas/Service.json
@@ -13,14 +13,16 @@
             "type": "string"
         },
         "vendor": {
-            "not": [
-                {
-                    "type": "array",
-                    "items": {
-                        "type": "string"
+            "not": {
+                "anyOf": [
+                    {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
                     }
-                }
-            ]
+                ]
+            }
         },
         "monitoring_capability": {
             "anyOf": [
@@ -35,4 +37,4 @@
         }
     },
     "required": []
-}
+}
diff --git a/schemas/Topology.json b/schemas/Topology.json
@@ -26,24 +26,32 @@
             "minimum": 0
         },
         "domain_service": {
-            "$ref": "Service"
+            "$ref": "Service.json"
         },
         "nodes": {
             "type": "array",
             "items": [
                 {
-                    "$ref": "Node"
+                    "$ref": "Node.json"
                 }
             ]
         },
         "links": {
             "type": "array",
             "items": [
                 {
-                    "$ref": "Link"
+                    "$ref": "Link.json"
                 }
             ]
         }
     },
-    "required": ["id", "name", "version","model_version","time_stamp","nodes", "links"]
-}
+    "required": [
+        "id",
+        "name",
+        "version",
+        "model_version",
+        "time_stamp",
+        "nodes",
+        "links"
+    ]
+}
diff --git a/tests/__init__.py b/tests/__init__.py
@@ -16,6 +16,7 @@ class TestData:
     TOPOLOGY_FILE_AMLIGHT = TOPOLOGY_DIR / "amlight.json"
     TOPOLOGY_FILE_AMPATH = TOPOLOGY_DIR / "ampath.json"
     TOPOLOGY_FILE_SAX = TOPOLOGY_DIR / "sax.json"
+    TOPOLOGY_FILE_SDX = TOPOLOGY_DIR / "sdx.json"
     TOPOLOGY_FILE_ZAOXI = TOPOLOGY_DIR / "zaoxi.json"
 
     REQUESTS_DIR = PACKAGE_DATA_DIR / "requests"