Add test and update documentation and existing code

eiffel-syntax-and-usage/event-schemas.md

@@ -1,5 +1,5 @@
 <!---
-   Copyright 2022-2023 Axis Communications AB and others.
+   Copyright 2022-2024 Axis Communications AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -25,6 +25,8 @@ Both schemas and documentation files are generated from _schema definition files
 
 | Key             | Description             |
 | --------------- | ----------------------- |
+| `_name`         | The name of the type, e.g. "EiffelCompositionDefinedEvent". This string must match the name of the parent directory. |
+| `_version`      | The version of the event or other type, e.g. "3.1.0". This string must match the name of the definition file, except for the filename suffix. |
 | `_abbrev`       | The abbreviation of the event name, e.g. "CD" for EiffelCompositionDefinedEvent. |
 | `_description`  | An overall description of the event. |
 | `_links`        | An object describing the valid link types for the event. |
@@ -66,6 +68,8 @@ Here's a minimal example of a schema definition file:
 
 ```yaml
 $schema: http://json-schema.org/draft-04/schema#
+_name: EiffelSomethingHappenedEvent
+_version: 1.0.0
 _abbrev: SH
 _description: The EiffelSomethingHappenedEvent declares that something happened.
 type: object

generate_docs.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright 2022 Axis Communications AB.
+# Copyright 2022-2024 Axis Communications AB.
 # For a full list of individual contributors, please see the commit history.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -142,10 +142,10 @@ def _main():
         print(filename)
         input_path = Path(filename)
         schema = definition_loader.load(input_path)
-        output_path = (_OUTPUT_ROOT_PATH / input_path.parent.name).with_suffix(".md")
+        output_path = _OUTPUT_ROOT_PATH / (schema["_name"] + ".md")
         context = {
-            "type": input_path.parent.name,
-            "version": input_path.stem,
+            "type": schema["_name"],
+            "version": schema["_version"],
             "description": schema.get("_description", ""),
             "abbrev": schema.get("_abbrev", ""),
             "links": schema.get("_links", {}),

generate_schemas.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright 2022 Axis Communications AB.
+# Copyright 2022-2024 Axis Communications AB.
 # For a full list of individual contributors, please see the commit history.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -53,18 +53,16 @@ def _main():
         # the generic meta definition from one of the files in
         # definitions/EiffelMetaProperty. Patch the definitions of
         # meta.type and meta.version based on the event type and version.
-        meta_type = input_path.parent.name
-        meta_version = input_path.stem
+        meta_type = event_def["_name"]
+        meta_version = event_def["_version"]
         meta_properties = event_def["properties"]["meta"]["properties"]
         meta_properties["type"]["enum"] = [meta_type]
         meta_properties["version"]["enum"] = [meta_version]
         meta_properties["version"]["default"] = meta_version
 
         _strip_extra_keys(event_def)
 
-        output_path = (
-            _OUTPUT_ROOT_PATH / input_path.parent.name / input_path.name
-        ).with_suffix(".json")
+        output_path = _OUTPUT_ROOT_PATH / meta_type / (meta_version + ".json")
         with output_path.open(mode="w") as output_file:
             json.dump(event_def, output_file, indent=2)
             output_file.write("\n")

test_definitions.py

@@ -29,14 +29,19 @@ class DefinitionFile:
     def __init__(self, path: Path):
         self.path = path
         self.definition = definition_loader.load(path)
-        self.id = str(Path(path.parent.name) / path.stem)
+        self.id = f"{self.definition['_name']}/{self.definition['_version']}"
 
 
 # Preloaded type definitions for reuse in each parametrized testcase.
+DEFINITION_FILES = [p for p in Path(".").glob("definitions/*/*.yml")]
 EVENT_DEFINITIONS = [
-    DefinitionFile(p) for p in Path(".").glob("definitions/Eiffel*Event/*.yml")
+    DefinitionFile(p) for p in DEFINITION_FILES if p.parent.name.endswith("Event")
 ]
 EVENT_DEFINITION_IDS = [d.id for d in EVENT_DEFINITIONS]
+OTHER_DEFINITIONS = [
+    DefinitionFile(p) for p in DEFINITION_FILES if not p.parent.name.endswith("Event")
+]
+OTHER_DEFINITION_IDS = [d.id for d in OTHER_DEFINITIONS]
 
 
 @pytest.fixture(scope="session")
@@ -78,11 +83,26 @@ def test_history_table_contains_valid_release(definition_file, manifest):
     ids=EVENT_DEFINITION_IDS,
 )
 def test_history_table_matches_manifest(definition_file, manifest):
-    event_type = definition_file.path.parent.name
+    event_type = definition_file.definition["_name"]
     for entry in definition_file.definition.get("_history", []):
         edition = entry.get("introduced_in", None)
         event_version_of_edition = entry.get("version")
         if edition is not None:
             assert manifest.is_in_edition(
                 edition, event_type, event_version_of_edition
             ), f"{event_version_of_edition} not part of '{edition}' as described in history table"
+
+
+@pytest.mark.parametrize(
+    "definition_file",
+    EVENT_DEFINITIONS + OTHER_DEFINITIONS,
+    ids=EVENT_DEFINITION_IDS + OTHER_DEFINITION_IDS,
+)
+def test_filename_matches_type_version_fields(definition_file):
+    # Compute the expected type name and version based on the filename.
+    type = definition_file.path.parent.name
+    version = definition_file.path.stem
+
+    # Do they match what's in the definition?
+    assert type == definition_file.definition["_name"]
+    assert version == definition_file.definition["_version"]