Generate docs and schemas from common schema definition format

.github/workflows/test.yml

@@ -31,3 +31,21 @@ jobs:
 
       - name: Run tox
         run: tox
+
+  check-consistency:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Generate all files
+        run: make
+
+      - name: Check if workspace contains dirty files
+        run: git diff --exit-code || ( echo "::error ::Workspace contained dirty files (see log for details)" ; exit 1)
+
+      - name: Check if workspace contains untracked files
+        run: export FILES="$(git ls-files -o --exclude-standard)" ; test -z "$FILES" || ( echo "$FILES" ; echo "::error ::Workspace contained untracked files (see log for details)" ; exit 1 )

Makefile

@@ -0,0 +1,28 @@
+# Copyright 2022 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");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+.PHONY: all
+all: generate_docs generate_schemas
+
+# The generate_docs and generate_schemas goals assume that all Python
+# package dependencies are available, e.g. via a virtualenv.
+
+.PHONY: generate_docs
+generate_docs:
+	./generate_docs.py definitions/Eiffel*Event/*.yml
+
+.PHONY: generate_schemas
+generate_schemas:
+	./generate_schemas.py definitions/Eiffel*Event/*.yml

README.md

@@ -46,6 +46,7 @@ Visit [Eiffel Community](https://eiffel-community.github.io) to get started and
    1. [Compositions and Validity Checking](./eiffel-syntax-and-usage/compositions-and-validity-checking.md)
    1. [Security](./eiffel-syntax-and-usage/security.md)
    1. [Activity Linking](./eiffel-syntax-and-usage/activity-linking.md)
+   1. [Event Schemas](./eiffel-syntax-and-usage/event-schemas.md)
 1. The Eiffel Vocabulary
    1. [EiffelActivityTriggeredEvent (ActT)](./eiffel-vocabulary/EiffelActivityTriggeredEvent.md)
    1. [EiffelActivityCanceledEvent (ActC)](./eiffel-vocabulary/EiffelActivityCanceledEvent.md)

definition_loader.py

@@ -0,0 +1,51 @@
+# Copyright 2022 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");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The definition_loader module loads the YAML definition of an event
+from a file and resolves any JSON references."""
+
+from pathlib import Path
+from typing import Dict
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+from jsonref import JsonRef
+from ruamel import yaml
+
+
+def load(input_path: Path) -> Dict:
+    """Loads a schema definition file and returns it as a dictionary with
+    all references resolved.
+    """
+    with input_path.open() as input_file:
+        return JsonRef.replace_refs(
+            yaml.YAML().load(input_file),
+            base_uri=input_path.resolve().as_uri(),
+            loader=_yaml_loader,
+        )
+
+
+def _yaml_loader(uri: str) -> Dict:
+    parsed_uri = urlparse(uri)
+    input_path = Path(url2pathname(parsed_uri.path))
+    with input_path.open() as input_file:
+        # Maybe JsonRef fixes recursion on its own?
+        schema = JsonRef.replace_refs(
+            yaml.YAML().load(input_file),
+            base_uri=input_path.resolve().as_uri(),
+            loader=_yaml_loader,
+        )
+        del schema["$schema"]
+        return schema

definitions/EiffelActivityCanceledEvent/1.0.0.yml

@@ -0,0 +1,102 @@
+# Copyright 2017-2022 Ericsson 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");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+---
+$schema: http://json-schema.org/draft-04/schema#
+_abbrev: ActC
+_description: The EiffelActivityCanceledEvent signals that a previously
+  triggered activity execution has been canceled _before it has started_.
+  This is typically used in queuing situations where a queued execution
+  is dequeued. It is recommended that __CAUSE__ links be used to indicate
+  the reason.
+type: object
+properties:
+  meta:
+    $ref: ../EiffelMetaProperty/1.0.0.yml
+  data:
+    type: object
+    properties:
+      reason:
+        _description: Any human readable information as to the reason
+          for dequeueing.
+        type: string
+      customData:
+        type: array
+        items:
+          $ref: ../EiffelCustomDataProperty/1.0.0.yml
+    additionalProperties: false
+  links:
+    type: array
+    items:
+      $ref: ../EiffelEventLink/1.0.1.yml
+required:
+  - meta
+  - data
+  - links
+additonalProperties: false
+_links:
+  ACTIVITY_EXECUTION:
+    description: Declares the activity execution that was canceled.
+      In other words, [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md)
+      acts as a handle for the activity execution. This differs from
+      __CONTEXT__. In __ACTIVITY_EXECUTION__ the source carries information
+      pertaining to the target (i.e. the activity started, finished
+      or was canceled). In __CONTEXT__, on the other hand, the source
+      constitutes a subset of the target (e.g. this test case was executed
+      as part of that activity or test suite).
+    required: true
+    multiple: false
+    targets:
+      any_type: false
+      types:
+        - EiffelActivityTriggeredEvent
+  CAUSE:
+    description: While for most events it is recommended that __CAUSE__
+      SHOULD not be used in conjunction with __CONTEXT__, EiffelActivityCanceledEvent
+      is a special case as it represents a deviation from previous
+      intention. Therefore it is recommended that __CAUSE__ always
+      be included where applicable.
+    required: false
+    multiple: true
+    targets:
+      any_type: true
+      types: []
+  CONTEXT:
+    description: Identifies the activity or test suite of which this
+      event constitutes a part.
+    required: false
+    multiple: false
+    targets:
+      any_type: false
+      types:
+        - EiffelActivityTriggeredEvent
+        - EiffelTestSuiteStartedEvent
+  FLOW_CONTEXT:
+    description: 'Identifies the flow context of the event: which is
+      the continuous integration and delivery flow in which this occurred
+      – e.g. which product, project, track or version this is applicable
+      to.'
+    required: false
+    multiple: false
+    targets:
+      any_type: false
+      types:
+        - EiffelFlowContextDefinedEvent
+_history:
+  - version: 1.0.0
+    introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)'
+    changes: Initial version.
+_examples:
+  - title: Simple example
+    url: ../examples/events/EiffelActivityCanceledEvent/simple.json

definitions/EiffelActivityCanceledEvent/1.1.0.yml

@@ -0,0 +1,105 @@
+# Copyright 2017-2022 Ericsson 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");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+---
+$schema: http://json-schema.org/draft-04/schema#
+_abbrev: ActC
+_description: The EiffelActivityCanceledEvent signals that a previously
+  triggered activity execution has been canceled _before it has started_.
+  This is typically used in queuing situations where a queued execution
+  is dequeued. It is recommended that __CAUSE__ links be used to indicate
+  the reason.
+type: object
+properties:
+  meta:
+    $ref: ../EiffelMetaProperty/1.0.0.yml
+  data:
+    type: object
+    properties:
+      reason:
+        _description: Any human readable information as to the reason
+          for dequeueing.
+        type: string
+      customData:
+        type: array
+        items:
+          $ref: ../EiffelCustomDataProperty/1.0.0.yml
+    additionalProperties: false
+  links:
+    type: array
+    items:
+      $ref: ../EiffelEventLink/1.0.1.yml
+required:
+  - meta
+  - data
+  - links
+additonalProperties: false
+_links:
+  ACTIVITY_EXECUTION:
+    description: Declares the activity execution that was canceled.
+      In other words, [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md)
+      acts as a handle for the activity execution. This differs from
+      __CONTEXT__. In __ACTIVITY_EXECUTION__ the source carries information
+      pertaining to the target (i.e. the activity started, finished
+      or was canceled). In __CONTEXT__, on the other hand, the source
+      constitutes a subset of the target (e.g. this test case was executed
+      as part of that activity or test suite).
+    required: true
+    multiple: false
+    targets:
+      any_type: false
+      types:
+        - EiffelActivityTriggeredEvent
+  CAUSE:
+    description: While for most events it is recommended that __CAUSE__
+      SHOULD not be used in conjunction with __CONTEXT__, EiffelActivityCanceledEvent
+      is a special case as it represents a deviation from previous
+      intention. Therefore it is recommended that __CAUSE__ always
+      be included where applicable.
+    required: false
+    multiple: true
+    targets:
+      any_type: true
+      types: []
+  CONTEXT:
+    description: Identifies the activity or test suite of which this
+      event constitutes a part.
+    required: false
+    multiple: false
+    targets:
+      any_type: false
+      types:
+        - EiffelActivityTriggeredEvent
+        - EiffelTestSuiteStartedEvent
+  FLOW_CONTEXT:
+    description: 'Identifies the flow context of the event: which is
+      the continuous integration and delivery flow in which this occurred
+      – e.g. which product, project, track or version this is applicable
+      to.'
+    required: false
+    multiple: true
+    targets:
+      any_type: false
+      types:
+        - EiffelFlowContextDefinedEvent
+_history:
+  - version: 1.1.0
+    introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)'
+    changes: Multiple links of type FLOW_CONTEXT allowed.
+  - version: 1.0.0
+    introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)'
+    changes: Initial version.
+_examples:
+  - title: Simple example
+    url: ../examples/events/EiffelActivityCanceledEvent/simple.json