tuple fixes

Signed-off-by: Clemens Vasters <clemens@vasters.com>

Author: clemensv

json-structure-primer.md

@@ -99,6 +99,10 @@ updated to conform to the new rules.
       declared type. It's a more compact alternative to objects where the
       property names are replaced by the position in the tuple. Arrays or maps
       of tuples are especially useful for time-series data.
+    - **Choice:** A discriminated union of types, where one of the types is
+      selected based on a discriminator property. The `choice` keyword is used
+      to define the union and the `selector` property is used to specify the
+      discriminator property.
 - **Namespaces:** Namespaces are a formal part of the schema language, allowing
   for more modular and deterministic schema definitions. Namespaces are used to
   scope type definitions.
@@ -610,6 +614,107 @@ elements. The schema above would match the following instance data:
 ["apple", "banana", "cherry"]
 ```
 
+### 4.6. Example: Declaring Tuples
+
+Tuples are fixed-length arrays with named elements, declared via the `tuple` keyword.
+
+```json
+{
+    "$schema": "https://json-structure.org/meta/core/v0/#",
+    "type": "tuple",
+    "name": "PersonTuple",
+    "properties": {
+        "firstName": { "type": "string" },
+        "age":       { "type": "int32" }
+    },
+    "tuple": ["firstName", "age"]
+}
+```
+
+An instance of this tuple type:
+
+```json
+["Alice", 30]
+```
+
+### 4.7. Example: Declaring Choice Types
+
+Choice types define discriminated unions via the `choice` keyword. Two forms are supported:
+
+#### Tagged Unions
+
+Tagged unions represent the selected type as a single-property object:
+
+```json
+{
+    "$schema": "https://json-structure.org/meta/core/v0/#",
+    "type": "choice",
+    "name": "StringOrNumber",
+    "choices": {
+        "string": { "type": "string" },
+        "int32":  { "type": "int32" }
+    }
+}
+```
+
+Valid instances:
+
+```json
+{ "string": "Hello" }
+{ "int32":  42 }
+```
+
+#### Inline Unions
+
+Inline unions extend a common abstract base type and use a selector property:
+
+```json
+{
+    "$schema": "https://json-structure.org/meta/core/v0/#",
+    "type": "choice",
+    "name": "AddressChoice",
+    "$extends": "#/definitions/Address",
+    "selector": "addressType",
+    "choices": {
+        "StreetAddress":     { "$ref": "#/definitions/StreetAddress" },
+        "PostOfficeBoxAddress": { "$ref": "#/definitions/PostOfficeBoxAddress" }
+    },
+    "definitions": {
+        "Address": {
+            "abstract": true,
+            "type": "object",
+            "properties": {
+                "city": { "type": "string" },
+                "state":{ "type": "string" },
+                "zip":  { "type": "string" }
+            }
+        },
+        "StreetAddress": {
+            "type": "object",
+            "$extends": "#/definitions/Address",
+            "properties": { "street": { "type": "string" } }
+        },
+        "PostOfficeBoxAddress": {
+            "type": "object",
+            "$extends": "#/definitions/Address",
+            "properties": { "poBox": { "type": "string" } }
+        }
+    }
+}
+```
+
+Instance of this inline union:
+
+```json
+{
+    "addressType": "StreetAddress",
+    "street":      "123 Main St",
+    "city":        "AnyCity",
+    "state":       "AS",
+    "zip":         "11111"
+}
+```
+
 ## 5. Using Companion Specifications
 
 The JSON Structure Core specification is designed to be extensible through

samples/py/json_structure_instance_validator.py

@@ -353,13 +353,25 @@ def validate_instance(self, instance, schema=None, path="#", meta=None):
             if not isinstance(instance, list):
                 self.errors.append(f"Expected tuple (array) at {path}, got {type(instance).__name__}")
             else:
+                # Retrieve the tuple ordering
+                order = schema.get("tuple")
                 props = schema.get("properties", {})
-                expected_len = len(props)
-                if len(instance) != expected_len:
-                    self.errors.append(f"Tuple at {path} length {len(instance)} does not equal expected {expected_len}")
+                if order is None:
+                    self.errors.append(f"Tuple schema at {path} is missing the required 'tuple' keyword for ordering")
+                elif not isinstance(order, list):
+                    self.errors.append(f"'tuple' keyword at {path} must be an array of property names")
                 else:
-                    for (prop, prop_schema), item in zip(props.items(), instance):
-                        self.validate_instance(item, prop_schema, f"{path}/{prop}")
+                    # Verify each name in order exists in properties
+                    for prop_name in order:
+                        if prop_name not in props:
+                            self.errors.append(f"Tuple order key '{prop_name}' at {path} not defined in properties")
+                    expected_len = len(order)
+                    if len(instance) != expected_len:
+                        self.errors.append(f"Tuple at {path} length {len(instance)} does not equal expected {expected_len}")
+                    else:
+                        for idx, prop_name in enumerate(order):
+                            prop_schema = props[prop_name]
+                            self.validate_instance(instance[idx], prop_schema, f"{path}/{prop_name}")
         elif schema_type == "choice":
             if not isinstance(instance, dict):
                 self.errors.append(f"Expected choice object at {path}, got {type(instance).__name__}")

samples/py/json_structure_schema_validator.py

@@ -421,7 +421,17 @@ def _check_map_schema(self, obj, path):
     def _check_tuple_schema(self, obj, path):
         """
         Checks constraints for a 'tuple' type.
-        """
+        A valid tuple schema must:
+          - Include a 'name' attribute.
+          - Have a 'properties' object where each key is a valid identifier.
+          - Include a 'tuple' keyword that is an array of strings defining the order.
+          - Ensure that every element in the 'tuple' array corresponds to a property in 'properties'.
+        """
+        # Check that 'name' is present.
+        if "name" not in obj:
+            self._err("Tuple type must include a 'name' attribute.", path + "/name")
+        
+        # Validate properties.
         if "properties" not in obj:
             self._err("Tuple type must have 'properties'.", path + "/properties")
         else:
@@ -436,6 +446,20 @@ def _check_tuple_schema(self, obj, path):
                         self._validate_schema(prop_schema, is_root=False, path=f"{path}/properties/{prop_name}")
                     else:
                         self._err(f"Tuple property '{prop_name}' must be an object (a schema).", path + f"/properties/{prop_name}")
+        
+        # Check that the 'tuple' keyword is present.
+        if "tuple" not in obj:
+            self._err("Tuple type must include the 'tuple' keyword defining the order of elements.", path + "/tuple")
+        else:
+            tuple_order = obj["tuple"]
+            if not isinstance(tuple_order, list):
+                self._err("'tuple' keyword must be an array of strings.", path + "/tuple")
+            else:
+                for idx, element in enumerate(tuple_order):
+                    if not isinstance(element, str):
+                        self._err(f"Element at index {idx} in 'tuple' array must be a string.", path + f"/tuple[{idx}]")
+                    elif "properties" in obj and isinstance(obj["properties"], dict) and element not in obj["properties"]:
+                        self._err(f"Element '{element}' in 'tuple' does not correspond to any property in 'properties'.", path + f"/tuple[{idx}]")
 
     def _check_choice_schema(self, obj, path):
         """

samples/py/test_json_structure_instance_validator.py

@@ -556,7 +556,8 @@ def test_tuple_valid():
         "properties": {
             "first": {"type": "string"},
             "second": {"type": "number"}
-        }
+        },
+        "tuple": ["first", "second"]
     }
     instance = ["hello", 42]
     validator = JSONStructureInstanceValidator(schema)
@@ -573,7 +574,8 @@ def test_tuple_wrong_length():
         "properties": {
             "first": {"type": "string"},
             "second": {"type": "number"}
-        }
+        },
+        "tuple": ["first", "second"]
     }
     instance = ["only one"]
     validator = JSONStructureInstanceValidator(schema)

samples/py/test_json_structure_schema_validator.py

@@ -101,6 +101,19 @@
     "name": "EmptyNamespace"
 }
 
+# Case 8: Valid tuple type with implicit required properties and tuple order
+VALID_TUPLE = {
+    "$schema": "https://json-structure.org/meta/core/v0/#",
+    "$id": "https://example.com/schema/tuple",
+    "name": "PersonTuple",
+    "type": "tuple",
+    "properties": {
+        "name": {"type": "string"},
+        "age": {"type": "int32"}
+    },
+    "tuple": ["name", "age"]
+}
+
 VALID_SCHEMAS = [
     VALID_MINIMAL,
     VALID_OBJECT,
@@ -109,6 +122,7 @@
     VALID_EXTENDS,
     VALID_ALLOW_DOLLAR,  # must be validated with allow_dollar=True
     VALID_NAMESPACE_EMPTY,
+    VALID_TUPLE,
 ]
 
 # =============================================================================
@@ -332,6 +346,44 @@
     "$schema": 123,
 }
 
+# Case 26: Tuple type missing 'tuple' keyword.
+INVALID_TUPLE_MISSING_KEYWORD = {
+    "$schema": "https://json-structure.org/meta/core/v0/#",
+    "$id": "https://example.com/schema/invalid_tuple_missing",
+    "name": "MissingTupleKeyword",
+    "type": "tuple",
+    "properties": {
+        "name": {"type": "string"},
+        "age": {"type": "int32"}
+    }
+}
+
+# Case 27: 'tuple' keyword is not an array of strings.
+INVALID_TUPLE_NOT_ARRAY = {
+    "$schema": "https://json-structure.org/meta/core/v0/#",
+    "$id": "https://example.com/schema/invalid_tuple_not_array",
+    "name": "TupleNotArray",
+    "type": "tuple",
+    "properties": {
+        "name": {"type": "string"},
+        "age": {"type": "int32"}
+    },
+    "tuple": "name,age"
+}
+
+# Case 28: 'tuple' contains non-string elements.
+INVALID_TUPLE_NONSTRING_ITEM = {
+    "$schema": "https://json-structure.org/meta/core/v0/#",
+    "$id": "https://example.com/schema/invalid_tuple_nonstring",
+    "name": "TupleNonString",
+    "type": "tuple",
+    "properties": {
+        "name": {"type": "string"},
+        "age": {"type": "int32"}
+    },
+    "tuple": ["name", 42]
+}
+
 INVALID_SCHEMAS = [
     INVALID_MISSING_SCHEMA,
     INVALID_MISSING_ID,
@@ -357,7 +409,10 @@
     INVALID_DEFS_ROOT_TYPE,
     INVALID_NOT_OBJECT,
     INVALID_NOT_ABSOLUTE_URI,
-    INVALID_NOT_STRING
+    INVALID_NOT_STRING,
+    INVALID_TUPLE_MISSING_KEYWORD,
+    INVALID_TUPLE_NOT_ARRAY,
+    INVALID_TUPLE_NONSTRING_ITEM
 ]
 
 # =============================================================================