diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index a3e4b961..35415091 100644 --- a/.github/workflows/test.yml +++ b/.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 ) diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..900e642b --- /dev/null +++ b/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 diff --git a/README.md b/README.md index a4ba1156..c719c166 100644 --- a/README.md +++ b/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) diff --git a/definition_loader.py b/definition_loader.py new file mode 100644 index 00000000..33362954 --- /dev/null +++ b/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 diff --git a/definitions/EiffelActivityCanceledEvent/1.0.0.yml b/definitions/EiffelActivityCanceledEvent/1.0.0.yml new file mode 100644 index 00000000..2008ed8c --- /dev/null +++ b/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 diff --git a/definitions/EiffelActivityCanceledEvent/1.1.0.yml b/definitions/EiffelActivityCanceledEvent/1.1.0.yml new file mode 100644 index 00000000..7a391244 --- /dev/null +++ b/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 diff --git a/definitions/EiffelActivityCanceledEvent/2.0.0.yml b/definitions/EiffelActivityCanceledEvent/2.0.0.yml new file mode 100644 index 00000000..da4b843a --- /dev/null +++ b/definitions/EiffelActivityCanceledEvent/2.0.0.yml @@ -0,0 +1,109 @@ +# 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/2.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: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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 diff --git a/definitions/EiffelActivityCanceledEvent/3.0.0.yml b/definitions/EiffelActivityCanceledEvent/3.0.0.yml new file mode 100644 index 00000000..67fb4ce3 --- /dev/null +++ b/definitions/EiffelActivityCanceledEvent/3.0.0.yml @@ -0,0 +1,112 @@ +# 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/3.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: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityCanceledEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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 diff --git a/definitions/EiffelActivityCanceledEvent/3.1.0.yml b/definitions/EiffelActivityCanceledEvent/3.1.0.yml new file mode 100644 index 00000000..d6c7ad86 --- /dev/null +++ b/definitions/EiffelActivityCanceledEvent/3.1.0.yml @@ -0,0 +1,116 @@ +# 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/3.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.1.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: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityCanceledEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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 diff --git a/definitions/EiffelActivityFinishedEvent/1.0.0.yml b/definitions/EiffelActivityFinishedEvent/1.0.0.yml new file mode 100644 index 00000000..0810b4bd --- /dev/null +++ b/definitions/EiffelActivityFinishedEvent/1.0.0.yml @@ -0,0 +1,143 @@ +# 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: ActF +_description: The EiffelActivityFinishedEvent declares that a previously + started activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md) + followed by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)) + has finished. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the activity. + type: object + properties: + conclusion: + _description: |- + A terse standardized conclusion of the activity, designed to be machine readable. + SUCCESSFUL signifies that the activity was concluded and the outcome matched expectations. + UNSUCCESSFUL signifies that the activity was concluded, but the outcome did not match expectations. To exemplify, a compilation job was successfully invoked, but compilation failed. + FAILED signifies that the activity could not be successfully executed. To exemplify, a compilation could not be invoked, e.g. due to misconfiguration or environment issues. + ABORTED signifies that the activity was aborted before it could be concluded. + TIMED_OUT signifies that the activity did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the activity could not be determined. + type: string + enum: + - SUCCESSFUL + - UNSUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the activity outcome, + designed to provide human readers with further information. + type: string + required: + - conclusion + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + required: + - outcome + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was finished. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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/EiffelActivityFinishedEvent/simple.json diff --git a/definitions/EiffelActivityFinishedEvent/1.1.0.yml b/definitions/EiffelActivityFinishedEvent/1.1.0.yml new file mode 100644 index 00000000..8a7aae33 --- /dev/null +++ b/definitions/EiffelActivityFinishedEvent/1.1.0.yml @@ -0,0 +1,146 @@ +# 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: ActF +_description: The EiffelActivityFinishedEvent declares that a previously + started activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md) + followed by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)) + has finished. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the activity. + type: object + properties: + conclusion: + _description: |- + A terse standardized conclusion of the activity, designed to be machine readable. + SUCCESSFUL signifies that the activity was concluded and the outcome matched expectations. + UNSUCCESSFUL signifies that the activity was concluded, but the outcome did not match expectations. To exemplify, a compilation job was successfully invoked, but compilation failed. + FAILED signifies that the activity could not be successfully executed. To exemplify, a compilation could not be invoked, e.g. due to misconfiguration or environment issues. + ABORTED signifies that the activity was aborted before it could be concluded. + TIMED_OUT signifies that the activity did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the activity could not be determined. + type: string + enum: + - SUCCESSFUL + - UNSUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the activity outcome, + designed to provide human readers with further information. + type: string + required: + - conclusion + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + required: + - outcome + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was finished. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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/EiffelActivityFinishedEvent/simple.json diff --git a/definitions/EiffelActivityFinishedEvent/2.0.0.yml b/definitions/EiffelActivityFinishedEvent/2.0.0.yml new file mode 100644 index 00000000..933facda --- /dev/null +++ b/definitions/EiffelActivityFinishedEvent/2.0.0.yml @@ -0,0 +1,150 @@ +# 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: ActF +_description: The EiffelActivityFinishedEvent declares that a previously + started activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md) + followed by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)) + has finished. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the activity. + type: object + properties: + conclusion: + _description: |- + A terse standardized conclusion of the activity, designed to be machine readable. + SUCCESSFUL signifies that the activity was concluded and the outcome matched expectations. + UNSUCCESSFUL signifies that the activity was concluded, but the outcome did not match expectations. To exemplify, a compilation job was successfully invoked, but compilation failed. + FAILED signifies that the activity could not be successfully executed. To exemplify, a compilation could not be invoked, e.g. due to misconfiguration or environment issues. + ABORTED signifies that the activity was aborted before it could be concluded. + TIMED_OUT signifies that the activity did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the activity could not be determined. + type: string + enum: + - SUCCESSFUL + - UNSUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the activity outcome, + designed to provide human readers with further information. + type: string + required: + - conclusion + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + required: + - outcome + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was finished. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityFinishedEvent/simple.json diff --git a/definitions/EiffelActivityFinishedEvent/3.0.0.yml b/definitions/EiffelActivityFinishedEvent/3.0.0.yml new file mode 100644 index 00000000..f1d8eabd --- /dev/null +++ b/definitions/EiffelActivityFinishedEvent/3.0.0.yml @@ -0,0 +1,153 @@ +# 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: ActF +_description: The EiffelActivityFinishedEvent declares that a previously + started activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md) + followed by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)) + has finished. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the activity. + type: object + properties: + conclusion: + _description: |- + A terse standardized conclusion of the activity, designed to be machine readable. + SUCCESSFUL signifies that the activity was concluded and the outcome matched expectations. + UNSUCCESSFUL signifies that the activity was concluded, but the outcome did not match expectations. To exemplify, a compilation job was successfully invoked, but compilation failed. + FAILED signifies that the activity could not be successfully executed. To exemplify, a compilation could not be invoked, e.g. due to misconfiguration or environment issues. + ABORTED signifies that the activity was aborted before it could be concluded. + TIMED_OUT signifies that the activity did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the activity could not be determined. + type: string + enum: + - SUCCESSFUL + - UNSUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the activity outcome, + designed to provide human readers with further information. + type: string + required: + - conclusion + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + required: + - outcome + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was finished. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityFinishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityFinishedEvent/simple.json diff --git a/definitions/EiffelActivityFinishedEvent/3.1.0.yml b/definitions/EiffelActivityFinishedEvent/3.1.0.yml new file mode 100644 index 00000000..20cb377d --- /dev/null +++ b/definitions/EiffelActivityFinishedEvent/3.1.0.yml @@ -0,0 +1,169 @@ +# 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: ActF +_description: The EiffelActivityFinishedEvent declares that a previously + started activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md) + followed by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)) + has finished. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the activity. + type: object + properties: + conclusion: + _description: |- + A terse standardized conclusion of the activity, designed to be machine readable. + SUCCESSFUL signifies that the activity was concluded and the outcome matched expectations. + UNSUCCESSFUL signifies that the activity was concluded, but the outcome did not match expectations. To exemplify, a compilation job was successfully invoked, but compilation failed. + FAILED signifies that the activity could not be successfully executed. To exemplify, a compilation could not be invoked, e.g. due to misconfiguration or environment issues. + ABORTED signifies that the activity was aborted before it could be concluded. + TIMED_OUT signifies that the activity did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the activity could not be determined. + type: string + enum: + - SUCCESSFUL + - UNSUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the activity outcome, + designed to provide human readers with further information. + type: string + required: + - conclusion + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + required: + - outcome + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was finished. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.1.0 + introduced_in: Current version + changes: Add `data.persistentLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityFinishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityFinishedEvent/simple.json diff --git a/definitions/EiffelActivityFinishedEvent/3.2.0.yml b/definitions/EiffelActivityFinishedEvent/3.2.0.yml new file mode 100644 index 00000000..7b0e10c8 --- /dev/null +++ b/definitions/EiffelActivityFinishedEvent/3.2.0.yml @@ -0,0 +1,173 @@ +# 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: ActF +_description: The EiffelActivityFinishedEvent declares that a previously + started activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md) + followed by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)) + has finished. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the activity. + type: object + properties: + conclusion: + _description: |- + A terse standardized conclusion of the activity, designed to be machine readable. + SUCCESSFUL signifies that the activity was concluded and the outcome matched expectations. + UNSUCCESSFUL signifies that the activity was concluded, but the outcome did not match expectations. To exemplify, a compilation job was successfully invoked, but compilation failed. + FAILED signifies that the activity could not be successfully executed. To exemplify, a compilation could not be invoked, e.g. due to misconfiguration or environment issues. + ABORTED signifies that the activity was aborted before it could be concluded. + TIMED_OUT signifies that the activity did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the activity could not be determined. + type: string + enum: + - SUCCESSFUL + - UNSUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the activity outcome, + designed to provide human readers with further information. + type: string + required: + - conclusion + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + required: + - outcome + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was finished. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.2.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.1.0 + introduced_in: No edition set + changes: Add `data.persistentLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityFinishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityFinishedEvent/simple.json diff --git a/definitions/EiffelActivityStartedEvent/1.0.0.yml b/definitions/EiffelActivityStartedEvent/1.0.0.yml new file mode 100644 index 00000000..1fdfc0e1 --- /dev/null +++ b/definitions/EiffelActivityStartedEvent/1.0.0.yml @@ -0,0 +1,129 @@ +# 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: ActS +_description: The EiffelActivityStartedEvent declares that a previously + triggered activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md)) + has started. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + executionUri: + _description: Any URI at which further information about the + execution may be found; a typical use case is to link a CI + server job execution page. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the activity has finished there is no guarantee + that these links are valid. Persistently stored logs shall + be (re-)declared by [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was started. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_ACTIVITY_EXECUTION: + description: Identifies the latest previous execution of the activity. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelActivityTriggeredEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelActivityStartedEvent/simple.json diff --git a/definitions/EiffelActivityStartedEvent/1.1.0.yml b/definitions/EiffelActivityStartedEvent/1.1.0.yml new file mode 100644 index 00000000..da4d9766 --- /dev/null +++ b/definitions/EiffelActivityStartedEvent/1.1.0.yml @@ -0,0 +1,132 @@ +# 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: ActS +_description: The EiffelActivityStartedEvent declares that a previously + triggered activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md)) + has started. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + executionUri: + _description: Any URI at which further information about the + execution may be found; a typical use case is to link a CI + server job execution page. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the activity has finished there is no guarantee + that these links are valid. Persistently stored logs shall + be (re-)declared by [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was started. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_ACTIVITY_EXECUTION: + description: Identifies the latest previous execution of the activity. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelActivityTriggeredEvent +_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/EiffelActivityStartedEvent/simple.json diff --git a/definitions/EiffelActivityStartedEvent/2.0.0.yml b/definitions/EiffelActivityStartedEvent/2.0.0.yml new file mode 100644 index 00000000..b1b8d27e --- /dev/null +++ b/definitions/EiffelActivityStartedEvent/2.0.0.yml @@ -0,0 +1,136 @@ +# 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: ActS +_description: The EiffelActivityStartedEvent declares that a previously + triggered activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md)) + has started. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + executionUri: + _description: Any URI at which further information about the + execution may be found; a typical use case is to link a CI + server job execution page. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the activity has finished there is no guarantee + that these links are valid. Persistently stored logs shall + be (re-)declared by [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was started. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_ACTIVITY_EXECUTION: + description: Identifies the latest previous execution of the activity. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelActivityTriggeredEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityStartedEvent/simple.json diff --git a/definitions/EiffelActivityStartedEvent/3.0.0.yml b/definitions/EiffelActivityStartedEvent/3.0.0.yml new file mode 100644 index 00000000..5ed30a07 --- /dev/null +++ b/definitions/EiffelActivityStartedEvent/3.0.0.yml @@ -0,0 +1,139 @@ +# 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: ActS +_description: The EiffelActivityStartedEvent declares that a previously + triggered activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md)) + has started. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + executionUri: + _description: Any URI at which further information about the + execution may be found; a typical use case is to link a CI + server job execution page. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the activity has finished there is no guarantee + that these links are valid. Persistently stored logs shall + be (re-)declared by [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was started. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_ACTIVITY_EXECUTION: + description: Identifies the latest previous execution of the activity. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelActivityTriggeredEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityStartedEvent/simple.json diff --git a/definitions/EiffelActivityStartedEvent/4.0.0.yml b/definitions/EiffelActivityStartedEvent/4.0.0.yml new file mode 100644 index 00000000..ef1a19fd --- /dev/null +++ b/definitions/EiffelActivityStartedEvent/4.0.0.yml @@ -0,0 +1,143 @@ +# 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: ActS +_description: The EiffelActivityStartedEvent declares that a previously + triggered activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md)) + has started. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + executionUri: + _description: Any URI at which further information about the + execution may be found; a typical use case is to link a CI + server job execution page. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the activity has finished there is no guarantee + that these links are valid. Persistently stored logs shall + be (re-)declared by [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was started. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_ACTIVITY_EXECUTION: + description: Identifies the latest previous execution of the activity. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelActivityTriggeredEvent +_history: + - version: 4.0.0 + introduced_in: '[edition-agen-1](../../../tree/edition-agen-1)' + changes: Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)) + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityStartedEvent/simple.json diff --git a/definitions/EiffelActivityStartedEvent/4.1.0.yml b/definitions/EiffelActivityStartedEvent/4.1.0.yml new file mode 100644 index 00000000..74be78bc --- /dev/null +++ b/definitions/EiffelActivityStartedEvent/4.1.0.yml @@ -0,0 +1,159 @@ +# 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: ActS +_description: The EiffelActivityStartedEvent declares that a previously + triggered activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md)) + has started. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + executionUri: + _description: Any URI at which further information about the + execution may be found; a typical use case is to link a CI + server job execution page. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the activity has finished there is no guarantee + that these links are valid. Persistently stored logs shall + be (re-)declared by [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was started. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_ACTIVITY_EXECUTION: + description: Identifies the latest previous execution of the activity. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelActivityTriggeredEvent +_history: + - version: 4.1.0 + introduced_in: Current version + changes: Add `data.liveLogs.{mediaType,tags}`. + - version: 4.0.0 + introduced_in: '[edition-agen-1](../../../tree/edition-agen-1)' + changes: Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)) + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityStartedEvent/simple.json diff --git a/definitions/EiffelActivityStartedEvent/4.2.0.yml b/definitions/EiffelActivityStartedEvent/4.2.0.yml new file mode 100644 index 00000000..fbf71816 --- /dev/null +++ b/definitions/EiffelActivityStartedEvent/4.2.0.yml @@ -0,0 +1,162 @@ +# 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: ActS +_description: The EiffelActivityStartedEvent declares that a previously + triggered activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md)) + has started. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + executionUri: + _description: Any URI at which further information about the + execution may be found; a typical use case is to link a CI + server job execution page. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the activity has finished there is no guarantee + that these links are valid. Persistently stored logs shall + be (re-)declared by [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ACTIVITY_EXECUTION: + description: Declares the activity execution that was started. + 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: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_ACTIVITY_EXECUTION: + description: Identifies the latest previous execution of the activity. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelActivityTriggeredEvent +_history: + - version: 4.2.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 4.1.0 + introduced_in: No edition set + changes: Add `data.liveLogs.{mediaType,tags}`. + - version: 4.0.0 + introduced_in: '[edition-agen-1](../../../tree/edition-agen-1)' + changes: Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)) + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityStartedEvent/simple.json diff --git a/definitions/EiffelActivityTriggeredEvent/1.0.0.yml b/definitions/EiffelActivityTriggeredEvent/1.0.0.yml new file mode 100644 index 00000000..c435b973 --- /dev/null +++ b/definitions/EiffelActivityTriggeredEvent/1.0.0.yml @@ -0,0 +1,136 @@ +# 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: ActT +_description: |- + The EiffelActivityTriggeredEvent declares that a certain activity - typically a build, test or analysis activity - has been triggered by some factor. Note that this is crucially different from the activity execution having _started_ (as declared by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)). + + In a situation where execution follows immediately upon triggering these two events should be sent together. Where that is not the case (e.g. due to queuing) the time delta between EiffelActivityTriggeredEvent and EiffelActivityStartedEvent constitutes the queue time. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the activity. Uniqueness is not required + or checked, but is useful. + type: string + categories: + _description: Any categorization of the activity. This can + be used to group multiple similar activities for analysis + and visualization purposes. Example usage is to label the + similar but unique build activities of all the components + of system X as "System X Component Build" (whereas the name + would be e.g. "System X Component Y Build"). + type: array + items: + type: string + triggers: + _description: The circumstances triggering the activity. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the activity was manually triggered. + EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the activity was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the activity was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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/EiffelActivityTriggeredEvent/simple.json + - title: Example containing custom data + url: ../examples/events/EiffelActivityTriggeredEvent/simple-customdata.json diff --git a/definitions/EiffelActivityTriggeredEvent/1.1.0.yml b/definitions/EiffelActivityTriggeredEvent/1.1.0.yml new file mode 100644 index 00000000..4c7462b4 --- /dev/null +++ b/definitions/EiffelActivityTriggeredEvent/1.1.0.yml @@ -0,0 +1,139 @@ +# 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: ActT +_description: |- + The EiffelActivityTriggeredEvent declares that a certain activity - typically a build, test or analysis activity - has been triggered by some factor. Note that this is crucially different from the activity execution having _started_ (as declared by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)). + + In a situation where execution follows immediately upon triggering these two events should be sent together. Where that is not the case (e.g. due to queuing) the time delta between EiffelActivityTriggeredEvent and EiffelActivityStartedEvent constitutes the queue time. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the activity. Uniqueness is not required + or checked, but is useful. + type: string + categories: + _description: Any categorization of the activity. This can + be used to group multiple similar activities for analysis + and visualization purposes. Example usage is to label the + similar but unique build activities of all the components + of system X as "System X Component Build" (whereas the name + would be e.g. "System X Component Y Build"). + type: array + items: + type: string + triggers: + _description: The circumstances triggering the activity. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the activity was manually triggered. + EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the activity was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the activity was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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/EiffelActivityTriggeredEvent/simple.json + - title: Example containing custom data + url: ../examples/events/EiffelActivityTriggeredEvent/simple-customdata.json diff --git a/definitions/EiffelActivityTriggeredEvent/2.0.0.yml b/definitions/EiffelActivityTriggeredEvent/2.0.0.yml new file mode 100644 index 00000000..63b4584c --- /dev/null +++ b/definitions/EiffelActivityTriggeredEvent/2.0.0.yml @@ -0,0 +1,143 @@ +# 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: ActT +_description: |- + The EiffelActivityTriggeredEvent declares that a certain activity - typically a build, test or analysis activity - has been triggered by some factor. Note that this is crucially different from the activity execution having _started_ (as declared by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)). + + In a situation where execution follows immediately upon triggering these two events should be sent together. Where that is not the case (e.g. due to queuing) the time delta between EiffelActivityTriggeredEvent and EiffelActivityStartedEvent constitutes the queue time. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + name: + _description: The name of the activity. Uniqueness is not required + or checked, but is useful. + type: string + categories: + _description: Any categorization of the activity. This can + be used to group multiple similar activities for analysis + and visualization purposes. Example usage is to label the + similar but unique build activities of all the components + of system X as "System X Component Build" (whereas the name + would be e.g. "System X Component Y Build"). + type: array + items: + type: string + triggers: + _description: The circumstances triggering the activity. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the activity was manually triggered. + EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the activity was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the activity was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityTriggeredEvent/simple.json + - title: Example containing custom data + url: ../examples/events/EiffelActivityTriggeredEvent/simple-customdata.json diff --git a/definitions/EiffelActivityTriggeredEvent/3.0.0.yml b/definitions/EiffelActivityTriggeredEvent/3.0.0.yml new file mode 100644 index 00000000..d7f4e4c0 --- /dev/null +++ b/definitions/EiffelActivityTriggeredEvent/3.0.0.yml @@ -0,0 +1,146 @@ +# 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: ActT +_description: |- + The EiffelActivityTriggeredEvent declares that a certain activity - typically a build, test or analysis activity - has been triggered by some factor. Note that this is crucially different from the activity execution having _started_ (as declared by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)). + + In a situation where execution follows immediately upon triggering these two events should be sent together. Where that is not the case (e.g. due to queuing) the time delta between EiffelActivityTriggeredEvent and EiffelActivityStartedEvent constitutes the queue time. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + name: + _description: The name of the activity. Uniqueness is not required + or checked, but is useful. + type: string + categories: + _description: Any categorization of the activity. This can + be used to group multiple similar activities for analysis + and visualization purposes. Example usage is to label the + similar but unique build activities of all the components + of system X as "System X Component Build" (whereas the name + would be e.g. "System X Component Y Build"). + type: array + items: + type: string + triggers: + _description: The circumstances triggering the activity. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the activity was manually triggered. + EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the activity was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the activity was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityTriggeredEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityTriggeredEvent/simple.json + - title: Example containing custom data + url: ../examples/events/EiffelActivityTriggeredEvent/simple-customdata.json diff --git a/definitions/EiffelActivityTriggeredEvent/4.0.0.yml b/definitions/EiffelActivityTriggeredEvent/4.0.0.yml new file mode 100644 index 00000000..c8286c77 --- /dev/null +++ b/definitions/EiffelActivityTriggeredEvent/4.0.0.yml @@ -0,0 +1,150 @@ +# 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: ActT +_description: |- + The EiffelActivityTriggeredEvent declares that a certain activity - typically a build, test or analysis activity - has been triggered by some factor. Note that this is crucially different from the activity execution having _started_ (as declared by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)). + + In a situation where execution follows immediately upon triggering these two events should be sent together. Where that is not the case (e.g. due to queuing) the time delta between EiffelActivityTriggeredEvent and EiffelActivityStartedEvent constitutes the queue time. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the activity. Uniqueness is not required + or checked, but is useful. + type: string + categories: + _description: Any categorization of the activity. This can + be used to group multiple similar activities for analysis + and visualization purposes. Example usage is to label the + similar but unique build activities of all the components + of system X as "System X Component Build" (whereas the name + would be e.g. "System X Component Y Build"). + type: array + items: + type: string + triggers: + _description: The circumstances triggering the activity. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the activity was manually triggered. + EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the activity was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the activity was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 4.0.0 + introduced_in: '[edition-agen-1](../../../tree/edition-agen-1)' + changes: Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)) + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityTriggeredEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityTriggeredEvent/simple.json + - title: Example containing custom data + url: ../examples/events/EiffelActivityTriggeredEvent/simple-customdata.json diff --git a/definitions/EiffelActivityTriggeredEvent/4.1.0.yml b/definitions/EiffelActivityTriggeredEvent/4.1.0.yml new file mode 100644 index 00000000..faf9c463 --- /dev/null +++ b/definitions/EiffelActivityTriggeredEvent/4.1.0.yml @@ -0,0 +1,168 @@ +# 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: ActT +_description: |- + The EiffelActivityTriggeredEvent declares that a certain activity - typically a build, test or analysis activity - has been triggered by some factor. Note that this is crucially different from the activity execution having _started_ (as declared by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)). + + In a situation where execution follows immediately upon triggering these two events should be sent together. Where that is not the case (e.g. due to queuing) the time delta between EiffelActivityTriggeredEvent and EiffelActivityStartedEvent constitutes the queue time. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the activity. Uniqueness is not required + or checked, but is useful. + type: string + categories: + _description: Any categorization of the activity. This can + be used to group multiple similar activities for analysis + and visualization purposes. Example usage is to label the + similar but unique build activities of all the components + of system X as "System X Component Build" (whereas the name + would be e.g. "System X Component Y Build"). + type: array + items: + type: string + triggers: + _description: The circumstances triggering the activity. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the activity was manually triggered. + EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the activity was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the activity was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + CONTEXT: + description: 'Identifies the + [activity](../eiffel-syntax-and-usage/glossary.md#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 + PRECURSOR: + description: 'Used to declare temporal relationships between + [activities](../eiffel-syntax-and-usage/glossary.md#activity) in a + [pipeline](../eiffel-syntax-and-usage/glossary.md#pipeline), i.e. what + other activity/activities preceded this activity. This link type applies + primarily to non event-triggered activities. For more information on + the usage of this link type please see + [Activity Linking](../eiffel-syntax-and-usage/activity-linking.md).' + required: false + multiple: true + targets: + any_type: false + types: + - EiffelActivityTriggeredEvent +_history: + - version: 4.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 4.0.0 + introduced_in: '[edition-agen-1](../../../tree/edition-agen-1)' + changes: Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)) + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityTriggeredEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelActivityTriggeredEvent/simple.json + - title: Example containing custom data + url: ../examples/events/EiffelActivityTriggeredEvent/simple-customdata.json diff --git a/definitions/EiffelAnnouncementPublishedEvent/1.0.0.yml b/definitions/EiffelAnnouncementPublishedEvent/1.0.0.yml new file mode 100644 index 00000000..7216e8b4 --- /dev/null +++ b/definitions/EiffelAnnouncementPublishedEvent/1.0.0.yml @@ -0,0 +1,120 @@ +# 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: AnnP +_description: The EiffelAnnouncementPublishedEvent represents an announcement, + technically regarding any topic but typically used to communicate + any incidents or status updates regarding the continuous integration + and delivery pipeline. This information can then be favorably displayed + in visualization and dashboarding applications. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + heading: + _description: The heading of the announcement. + type: string + body: + _description: The body of the announcement. + type: string + uri: + _description: A URI where further information can be obtained, + if applicable. + type: string + severity: + _description: The severity of the announcement. The CLOSED + and CANCELED values SHOULD only be used when following up + a previous announcement, i.e. in conjunction with a __MODIFIED_ANNOUNCEMENT__ + link. + type: string + enum: + - MINOR + - MAJOR + - CRITICAL + - BLOCKER + - CLOSED + - CANCELED + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - heading + - body + - severity + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + MODIFIED_ANNOUNCEMENT: + description: Identifies an announcement of which this event represents + an update or modification, if any. Example usage is to declare + the end to a previously announced situation. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelAnnouncementPublishedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelAnnouncementPublishedEvent/simple.json diff --git a/definitions/EiffelAnnouncementPublishedEvent/1.1.0.yml b/definitions/EiffelAnnouncementPublishedEvent/1.1.0.yml new file mode 100644 index 00000000..e6e0dcef --- /dev/null +++ b/definitions/EiffelAnnouncementPublishedEvent/1.1.0.yml @@ -0,0 +1,123 @@ +# 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: AnnP +_description: The EiffelAnnouncementPublishedEvent represents an announcement, + technically regarding any topic but typically used to communicate + any incidents or status updates regarding the continuous integration + and delivery pipeline. This information can then be favorably displayed + in visualization and dashboarding applications. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + heading: + _description: The heading of the announcement. + type: string + body: + _description: The body of the announcement. + type: string + uri: + _description: A URI where further information can be obtained, + if applicable. + type: string + severity: + _description: The severity of the announcement. The CLOSED + and CANCELED values SHOULD only be used when following up + a previous announcement, i.e. in conjunction with a __MODIFIED_ANNOUNCEMENT__ + link. + type: string + enum: + - MINOR + - MAJOR + - CRITICAL + - BLOCKER + - CLOSED + - CANCELED + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - heading + - body + - severity + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + MODIFIED_ANNOUNCEMENT: + description: Identifies an announcement of which this event represents + an update or modification, if any. Example usage is to declare + the end to a previously announced situation. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelAnnouncementPublishedEvent +_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/EiffelAnnouncementPublishedEvent/simple.json diff --git a/definitions/EiffelAnnouncementPublishedEvent/2.0.0.yml b/definitions/EiffelAnnouncementPublishedEvent/2.0.0.yml new file mode 100644 index 00000000..dba855fd --- /dev/null +++ b/definitions/EiffelAnnouncementPublishedEvent/2.0.0.yml @@ -0,0 +1,127 @@ +# 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: AnnP +_description: The EiffelAnnouncementPublishedEvent represents an announcement, + technically regarding any topic but typically used to communicate + any incidents or status updates regarding the continuous integration + and delivery pipeline. This information can then be favorably displayed + in visualization and dashboarding applications. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + heading: + _description: The heading of the announcement. + type: string + body: + _description: The body of the announcement. + type: string + uri: + _description: A URI where further information can be obtained, + if applicable. + type: string + severity: + _description: The severity of the announcement. The CLOSED + and CANCELED values SHOULD only be used when following up + a previous announcement, i.e. in conjunction with a __MODIFIED_ANNOUNCEMENT__ + link. + type: string + enum: + - MINOR + - MAJOR + - CRITICAL + - BLOCKER + - CLOSED + - CANCELED + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - heading + - body + - severity + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + MODIFIED_ANNOUNCEMENT: + description: Identifies an announcement of which this event represents + an update or modification, if any. Example usage is to declare + the end to a previously announced situation. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelAnnouncementPublishedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelAnnouncementPublishedEvent/simple.json diff --git a/definitions/EiffelAnnouncementPublishedEvent/3.0.0.yml b/definitions/EiffelAnnouncementPublishedEvent/3.0.0.yml new file mode 100644 index 00000000..47998f7a --- /dev/null +++ b/definitions/EiffelAnnouncementPublishedEvent/3.0.0.yml @@ -0,0 +1,130 @@ +# 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: AnnP +_description: The EiffelAnnouncementPublishedEvent represents an announcement, + technically regarding any topic but typically used to communicate + any incidents or status updates regarding the continuous integration + and delivery pipeline. This information can then be favorably displayed + in visualization and dashboarding applications. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + heading: + _description: The heading of the announcement. + type: string + body: + _description: The body of the announcement. + type: string + uri: + _description: A URI where further information can be obtained, + if applicable. + type: string + severity: + _description: The severity of the announcement. The CLOSED + and CANCELED values SHOULD only be used when following up + a previous announcement, i.e. in conjunction with a __MODIFIED_ANNOUNCEMENT__ + link. + type: string + enum: + - MINOR + - MAJOR + - CRITICAL + - BLOCKER + - CLOSED + - CANCELED + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - heading + - body + - severity + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + MODIFIED_ANNOUNCEMENT: + description: Identifies an announcement of which this event represents + an update or modification, if any. Example usage is to declare + the end to a previously announced situation. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelAnnouncementPublishedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelAnnouncementPublishedEvent/simple.json diff --git a/definitions/EiffelAnnouncementPublishedEvent/3.1.0.yml b/definitions/EiffelAnnouncementPublishedEvent/3.1.0.yml new file mode 100644 index 00000000..6d75f8e8 --- /dev/null +++ b/definitions/EiffelAnnouncementPublishedEvent/3.1.0.yml @@ -0,0 +1,134 @@ +# 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: AnnP +_description: The EiffelAnnouncementPublishedEvent represents an announcement, + technically regarding any topic but typically used to communicate + any incidents or status updates regarding the continuous integration + and delivery pipeline. This information can then be favorably displayed + in visualization and dashboarding applications. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + heading: + _description: The heading of the announcement. + type: string + body: + _description: The body of the announcement. + type: string + uri: + _description: A URI where further information can be obtained, + if applicable. + type: string + severity: + _description: The severity of the announcement. The CLOSED + and CANCELED values SHOULD only be used when following up + a previous announcement, i.e. in conjunction with a __MODIFIED_ANNOUNCEMENT__ + link. + type: string + enum: + - MINOR + - MAJOR + - CRITICAL + - BLOCKER + - CLOSED + - CANCELED + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - heading + - body + - severity + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + MODIFIED_ANNOUNCEMENT: + description: Identifies an announcement of which this event represents + an update or modification, if any. Example usage is to declare + the end to a previously announced situation. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelAnnouncementPublishedEvent +_history: + - version: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelAnnouncementPublishedEvent/simple.json diff --git a/definitions/EiffelArtifactCreatedEvent/1.0.0.yml b/definitions/EiffelArtifactCreatedEvent/1.0.0.yml new file mode 100644 index 00000000..d7130c97 --- /dev/null +++ b/definitions/EiffelArtifactCreatedEvent/1.0.0.yml @@ -0,0 +1,224 @@ +# 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: ArtC +_description: The EiffelArtifactCreatedEvent declares that a software + artifact has been created, what its coordinates are, what it contains + and how it was created. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + gav: + _description: The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) + of the created artifact. + type: object + properties: + groupId: + _description: The groupId of the created artifact. + type: string + artifactId: + _description: The artifactId of the created artifact. + type: string + version: + _description: The version of the created artifact. + type: string + required: + - groupId + - artifactId + - version + additionalProperties: false + fileInformation: + _description: A list of the artifact file contents, following + the standard established by [Apache Maven](https://maven.apache.org/pom.html). + type: array + items: + type: object + properties: + classifier: + _description: The classifier of the file within the artifact. + If none, an empty string shall be used. + type: string + extension: + _description: The extension of the file within the artifact. + If none, an empty string shall be used. + type: string + required: + - classifier + - extension + additionalProperties: false + buildCommand: + _description: The command used to build the artifact within + the identified environment. Used for reproducability purposes. + type: string + requiresImplementation: + _description: |- + Defines whether this artifact requires an implementing artifact. This is typically used for interfaces requiring some backend implementation, although the interface does not presume to define _which_ implementation. Implicitly interpreted as "ANY" if undefined. + NONE signifies that there SHALL no implementations of this artifact. In other words, a composition containing another artifact identifying it in __data.implements__ would be illegal. + ANY signifies that there may or may not be implementations of this artifact. + EXACTLY_ONE signifies that a legal composition must contain one and only one implementation of this artifact. + AT_LEAST_ONE signifies that a legal composition must contain one or more implementations of this artifact. + type: string + enum: + - NONE + - ANY + - EXACTLY_ONE + - AT_LEAST_ONE + dependsOn: + _description: An array of [GAVs](https://maven.apache.org/guides/mini/guide-naming-conventions.html) + this artifact depends on. + type: array + items: + type: object + properties: + groupId: + _description: The groupId of the dependency. + type: string + artifactId: + _description: The artifactId of the dependency. + type: string + version: + _description: The version of the dependency. Note that + [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + is supported. + type: string + required: + - groupId + - artifactId + - version + additionalProperties: false + implements: + _description: An array of [GAVs](https://maven.apache.org/guides/mini/guide-naming-conventions.html) + this artifact implements. The typical use case of this is + to identify interfaces implemented by this artifact. + type: array + items: + type: object + properties: + groupId: + _description: The groupId of the implemented artifact. + type: string + artifactId: + _description: The artifactId of the implemented artifact. + type: string + version: + _description: The version of the implemented artifact. + Note that [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + is supported. + type: string + required: + - groupId + - artifactId + - version + additionalProperties: false + name: + _description: Any (colloquial) name of the artifact. Unlike + __data.gav__, this is not intended as an unambiguous identifier + of the artifact, but as a descriptive and human readable + name. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - gav + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition from which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + ENVIRONMENT: + description: Identifies the environment in which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the artifact the event represents. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelArtifactCreatedEvent/simple.json + - title: Interface example + url: ../examples/events/EiffelArtifactCreatedEvent/interface.json + - title: Backend example + url: ../examples/events/EiffelArtifactCreatedEvent/backend.json + - title: Dependent example + url: ../examples/events/EiffelArtifactCreatedEvent/dependent.json diff --git a/definitions/EiffelArtifactCreatedEvent/1.1.0.yml b/definitions/EiffelArtifactCreatedEvent/1.1.0.yml new file mode 100644 index 00000000..e0a7344a --- /dev/null +++ b/definitions/EiffelArtifactCreatedEvent/1.1.0.yml @@ -0,0 +1,227 @@ +# 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: ArtC +_description: The EiffelArtifactCreatedEvent declares that a software + artifact has been created, what its coordinates are, what it contains + and how it was created. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + gav: + _description: The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) + of the created artifact. + type: object + properties: + groupId: + _description: The groupId of the created artifact. + type: string + artifactId: + _description: The artifactId of the created artifact. + type: string + version: + _description: The version of the created artifact. + type: string + required: + - groupId + - artifactId + - version + additionalProperties: false + fileInformation: + _description: A list of the artifact file contents, following + the standard established by [Apache Maven](https://maven.apache.org/pom.html). + type: array + items: + type: object + properties: + classifier: + _description: The classifier of the file within the artifact. + If none, an empty string shall be used. + type: string + extension: + _description: The extension of the file within the artifact. + If none, an empty string shall be used. + type: string + required: + - classifier + - extension + additionalProperties: false + buildCommand: + _description: The command used to build the artifact within + the identified environment. Used for reproducability purposes. + type: string + requiresImplementation: + _description: |- + Defines whether this artifact requires an implementing artifact. This is typically used for interfaces requiring some backend implementation, although the interface does not presume to define _which_ implementation. Implicitly interpreted as "ANY" if undefined. + NONE signifies that there SHALL no implementations of this artifact. In other words, a composition containing another artifact identifying it in __data.implements__ would be illegal. + ANY signifies that there may or may not be implementations of this artifact. + EXACTLY_ONE signifies that a legal composition must contain one and only one implementation of this artifact. + AT_LEAST_ONE signifies that a legal composition must contain one or more implementations of this artifact. + type: string + enum: + - NONE + - ANY + - EXACTLY_ONE + - AT_LEAST_ONE + dependsOn: + _description: An array of [GAVs](https://maven.apache.org/guides/mini/guide-naming-conventions.html) + this artifact depends on. + type: array + items: + type: object + properties: + groupId: + _description: The groupId of the dependency. + type: string + artifactId: + _description: The artifactId of the dependency. + type: string + version: + _description: The version of the dependency. Note that + [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + is supported. + type: string + required: + - groupId + - artifactId + - version + additionalProperties: false + implements: + _description: An array of [GAVs](https://maven.apache.org/guides/mini/guide-naming-conventions.html) + this artifact implements. The typical use case of this is + to identify interfaces implemented by this artifact. + type: array + items: + type: object + properties: + groupId: + _description: The groupId of the implemented artifact. + type: string + artifactId: + _description: The artifactId of the implemented artifact. + type: string + version: + _description: The version of the implemented artifact. + Note that [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + is supported. + type: string + required: + - groupId + - artifactId + - version + additionalProperties: false + name: + _description: Any (colloquial) name of the artifact. Unlike + __data.gav__, this is not intended as an unambiguous identifier + of the artifact, but as a descriptive and human readable + name. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - gav + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition from which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + ENVIRONMENT: + description: Identifies the environment in which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the artifact the event represents. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_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/EiffelArtifactCreatedEvent/simple.json + - title: Interface example + url: ../examples/events/EiffelArtifactCreatedEvent/interface.json + - title: Backend example + url: ../examples/events/EiffelArtifactCreatedEvent/backend.json + - title: Dependent example + url: ../examples/events/EiffelArtifactCreatedEvent/dependent.json diff --git a/definitions/EiffelArtifactCreatedEvent/2.0.0.yml b/definitions/EiffelArtifactCreatedEvent/2.0.0.yml new file mode 100644 index 00000000..cbf36af0 --- /dev/null +++ b/definitions/EiffelArtifactCreatedEvent/2.0.0.yml @@ -0,0 +1,204 @@ +# 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: ArtC +_description: The EiffelArtifactCreatedEvent declares that a software + artifact has been created, what its coordinates are, what it contains + and how it was created. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + identity: + _description: The identity of the created artifact, in [purl + format](https://github.com/package-url/purl-spec). + _format: '[purl specification](https://github.com/package-url/purl-spec)' + type: string + pattern: '^pkg:' + fileInformation: + _description: A list of the artifact file contents. This information + is optional and, when included, MAY include a complete or + incomplete list of contents. In other words, it may be used + to highlight only particular files of interest, such as launcher + binaries or other entry-points. + type: array + items: + type: object + properties: + name: + _description: The name (including relative path from + the root of the artifact) on syntax appropriate for + the artifact packaging type. + type: string + tags: + _description: Any tags associated with the file, to support + navigation and identification of items of interest. + type: array + items: + type: string + required: + - name + additionalProperties: false + buildCommand: + _description: The command used to build the artifact within + the identified environment. Used for reproducability purposes. + type: string + requiresImplementation: + _description: |- + Defines whether this artifact requires an implementing artifact. This is typically used for interfaces requiring some backend implementation, although the interface does not presume to define _which_ implementation. Implicitly interpreted as "ANY" if undefined. + NONE signifies that there SHALL no implementations of this artifact. In other words, a composition containing another artifact identifying it in __data.implements__ would be illegal. + ANY signifies that there may or may not be implementations of this artifact. + EXACTLY_ONE signifies that a legal composition must contain one and only one implementation of this artifact. + AT_LEAST_ONE signifies that a legal composition must contain one or more implementations of this artifact. + type: string + enum: + - NONE + - ANY + - EXACTLY_ONE + - AT_LEAST_ONE + dependsOn: + _description: An array of [purl identified](https://github.com/package-url/purl-spec) + entities this artifact depends on. While not included in + the purl specification itself, the Eiffel protocol allows + version range notation according to [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + to be used for the version component of the package identity. + Note that the purl specification always requires the version + component to be percent-encoded. + _format: '[purl specification](https://github.com/package-url/purl-spec)' + type: array + items: + type: string + pattern: '^pkg:' + implements: + _description: An array of [purl identified](https://github.com/package-url/purl-spec) + entities this artifact implements. The typical use case of + this is to identify interfaces implemented by this artifact. + While not included in the purl specification itself, the + Eiffel protocol allows version range notation according to + [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + to be used for the version component of the package identity. + Note that the purl specification always requires the version + component to be percent-encoded. + _format: '[purl specification](https://github.com/package-url/purl-spec)' + type: array + items: + type: string + pattern: '^pkg:' + name: + _description: Any (colloquial) name of the artifact. Unlike + __data.gav__, this is not intended as an unambiguous identifier + of the artifact, but as a descriptive and human readable + name. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - identity + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition from which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + ENVIRONMENT: + description: Identifies the environment in which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the artifact the event represents. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactCreatedEvent/simple.json + - title: Interface example + url: ../examples/events/EiffelArtifactCreatedEvent/interface.json + - title: Backend example + url: ../examples/events/EiffelArtifactCreatedEvent/backend.json + - title: Dependent example + url: ../examples/events/EiffelArtifactCreatedEvent/dependent.json diff --git a/definitions/EiffelArtifactCreatedEvent/3.0.0.yml b/definitions/EiffelArtifactCreatedEvent/3.0.0.yml new file mode 100644 index 00000000..fa8d5744 --- /dev/null +++ b/definitions/EiffelArtifactCreatedEvent/3.0.0.yml @@ -0,0 +1,207 @@ +# 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: ArtC +_description: The EiffelArtifactCreatedEvent declares that a software + artifact has been created, what its coordinates are, what it contains + and how it was created. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + identity: + _description: The identity of the created artifact, in [purl + format](https://github.com/package-url/purl-spec). + _format: '[purl specification](https://github.com/package-url/purl-spec)' + type: string + pattern: '^pkg:' + fileInformation: + _description: A list of the artifact file contents. This information + is optional and, when included, MAY include a complete or + incomplete list of contents. In other words, it may be used + to highlight only particular files of interest, such as launcher + binaries or other entry-points. + type: array + items: + type: object + properties: + name: + _description: The name (including relative path from + the root of the artifact) on syntax appropriate for + the artifact packaging type. + type: string + tags: + _description: Any tags associated with the file, to support + navigation and identification of items of interest. + type: array + items: + type: string + required: + - name + additionalProperties: false + buildCommand: + _description: The command used to build the artifact within + the identified environment. Used for reproducability purposes. + type: string + requiresImplementation: + _description: |- + Defines whether this artifact requires an implementing artifact. This is typically used for interfaces requiring some backend implementation, although the interface does not presume to define _which_ implementation. Implicitly interpreted as "ANY" if undefined. + NONE signifies that there SHALL no implementations of this artifact. In other words, a composition containing another artifact identifying it in __data.implements__ would be illegal. + ANY signifies that there may or may not be implementations of this artifact. + EXACTLY_ONE signifies that a legal composition must contain one and only one implementation of this artifact. + AT_LEAST_ONE signifies that a legal composition must contain one or more implementations of this artifact. + type: string + enum: + - NONE + - ANY + - EXACTLY_ONE + - AT_LEAST_ONE + dependsOn: + _description: An array of [purl identified](https://github.com/package-url/purl-spec) + entities this artifact depends on. While not included in + the purl specification itself, the Eiffel protocol allows + version range notation according to [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + to be used for the version component of the package identity. + Note that the purl specification always requires the version + component to be percent-encoded. + _format: '[purl specification](https://github.com/package-url/purl-spec)' + type: array + items: + type: string + pattern: '^pkg:' + implements: + _description: An array of [purl identified](https://github.com/package-url/purl-spec) + entities this artifact implements. The typical use case of + this is to identify interfaces implemented by this artifact. + While not included in the purl specification itself, the + Eiffel protocol allows version range notation according to + [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + to be used for the version component of the package identity. + Note that the purl specification always requires the version + component to be percent-encoded. + _format: '[purl specification](https://github.com/package-url/purl-spec)' + type: array + items: + type: string + pattern: '^pkg:' + name: + _description: Any (colloquial) name of the artifact. Unlike + __data.identity__, this is not intended as an unambiguous + identifier of the artifact, but as a descriptive and human + readable name. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - identity + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition from which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + ENVIRONMENT: + description: Identifies the environment in which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the artifact the event represents. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactCreatedEvent/simple.json + - title: Interface example + url: ../examples/events/EiffelArtifactCreatedEvent/interface.json + - title: Backend example + url: ../examples/events/EiffelArtifactCreatedEvent/backend.json + - title: Dependent example + url: ../examples/events/EiffelArtifactCreatedEvent/dependent.json diff --git a/definitions/EiffelArtifactCreatedEvent/3.1.0.yml b/definitions/EiffelArtifactCreatedEvent/3.1.0.yml new file mode 100644 index 00000000..046f355a --- /dev/null +++ b/definitions/EiffelArtifactCreatedEvent/3.1.0.yml @@ -0,0 +1,211 @@ +# 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: ArtC +_description: The EiffelArtifactCreatedEvent declares that a software + artifact has been created, what its coordinates are, what it contains + and how it was created. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + identity: + _description: The identity of the created artifact, in [purl + format](https://github.com/package-url/purl-spec). + _format: '[purl specification](https://github.com/package-url/purl-spec)' + type: string + pattern: '^pkg:' + fileInformation: + _description: A list of the artifact file contents. This information + is optional and, when included, MAY include a complete or + incomplete list of contents. In other words, it may be used + to highlight only particular files of interest, such as launcher + binaries or other entry-points. + type: array + items: + type: object + properties: + name: + _description: The name (including relative path from + the root of the artifact) on syntax appropriate for + the artifact packaging type. + type: string + tags: + _description: Any tags associated with the file, to support + navigation and identification of items of interest. + type: array + items: + type: string + required: + - name + additionalProperties: false + buildCommand: + _description: The command used to build the artifact within + the identified environment. Used for reproducability purposes. + type: string + requiresImplementation: + _description: |- + Defines whether this artifact requires an implementing artifact. This is typically used for interfaces requiring some backend implementation, although the interface does not presume to define _which_ implementation. Implicitly interpreted as "ANY" if undefined. + NONE signifies that there SHALL no implementations of this artifact. In other words, a composition containing another artifact identifying it in __data.implements__ would be illegal. + ANY signifies that there may or may not be implementations of this artifact. + EXACTLY_ONE signifies that a legal composition must contain one and only one implementation of this artifact. + AT_LEAST_ONE signifies that a legal composition must contain one or more implementations of this artifact. + type: string + enum: + - NONE + - ANY + - EXACTLY_ONE + - AT_LEAST_ONE + dependsOn: + _description: An array of [purl identified](https://github.com/package-url/purl-spec) + entities this artifact depends on. While not included in + the purl specification itself, the Eiffel protocol allows + version range notation according to [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + to be used for the version component of the package identity. + Note that the purl specification always requires the version + component to be percent-encoded. + _format: '[purl specification](https://github.com/package-url/purl-spec)' + type: array + items: + type: string + pattern: '^pkg:' + implements: + _description: An array of [purl identified](https://github.com/package-url/purl-spec) + entities this artifact implements. The typical use case of + this is to identify interfaces implemented by this artifact. + While not included in the purl specification itself, the + Eiffel protocol allows version range notation according to + [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) + to be used for the version component of the package identity. + Note that the purl specification always requires the version + component to be percent-encoded. + _format: '[purl specification](https://github.com/package-url/purl-spec)' + type: array + items: + type: string + pattern: '^pkg:' + name: + _description: Any (colloquial) name of the artifact. Unlike + __data.identity__, this is not intended as an unambiguous + identifier of the artifact, but as a descriptive and human + readable name. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - identity + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition from which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + ENVIRONMENT: + description: Identifies the environment in which this artifact + was built. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the artifact the event represents. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_history: + - version: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactCreatedEvent/simple.json + - title: Interface example + url: ../examples/events/EiffelArtifactCreatedEvent/interface.json + - title: Backend example + url: ../examples/events/EiffelArtifactCreatedEvent/backend.json + - title: Dependent example + url: ../examples/events/EiffelArtifactCreatedEvent/dependent.json diff --git a/definitions/EiffelArtifactPublishedEvent/1.0.0.yml b/definitions/EiffelArtifactPublishedEvent/1.0.0.yml new file mode 100644 index 00000000..b658c242 --- /dev/null +++ b/definitions/EiffelArtifactPublishedEvent/1.0.0.yml @@ -0,0 +1,119 @@ +# 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: ArtP +_description: The EiffelArtifactPublishedEvent declares that a software + artifact (declared by [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md)) + has been published and is consequently available for retrieval at + one or more locations. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + locations: + _description: A list of locations at which the artifact may + be retrieved. + type: array + items: + type: object + properties: + type: + _description: |- + The type of location. May be used by (automated) readers to understand the method of retrieval, particularly with regards to authentication. + ARTIFACTORY signifies an [Artifactory](https://www.jfrog.com/artifactory/) + NEXUS signifies a [Nexus](http://www.sonatype.org/nexus/) + PLAIN signifies a plain HTTP GET request. + OTHER signifies other methods of retrieval. Note that using this type likely requires some foreknowledge on part of the reader in order to fetch the artifact. + type: string + enum: + - ARTIFACTORY + - NEXUS + - PLAIN + - OTHER + uri: + _description: The URI at which the artifact can be retrieved. + type: string + required: + - type + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - locations + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ARTIFACT: + description: Identifies the artifact that was published. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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/EiffelArtifactPublishedEvent/simple.json diff --git a/definitions/EiffelArtifactPublishedEvent/1.1.0.yml b/definitions/EiffelArtifactPublishedEvent/1.1.0.yml new file mode 100644 index 00000000..66d4e80b --- /dev/null +++ b/definitions/EiffelArtifactPublishedEvent/1.1.0.yml @@ -0,0 +1,122 @@ +# 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: ArtP +_description: The EiffelArtifactPublishedEvent declares that a software + artifact (declared by [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md)) + has been published and is consequently available for retrieval at + one or more locations. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + locations: + _description: A list of locations at which the artifact may + be retrieved. + type: array + items: + type: object + properties: + type: + _description: |- + The type of location. May be used by (automated) readers to understand the method of retrieval, particularly with regards to authentication. + ARTIFACTORY signifies an [Artifactory](https://www.jfrog.com/artifactory/) + NEXUS signifies a [Nexus](http://www.sonatype.org/nexus/) + PLAIN signifies a plain HTTP GET request. + OTHER signifies other methods of retrieval. Note that using this type likely requires some foreknowledge on part of the reader in order to fetch the artifact. + type: string + enum: + - ARTIFACTORY + - NEXUS + - PLAIN + - OTHER + uri: + _description: The URI at which the artifact can be retrieved. + type: string + required: + - type + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - locations + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ARTIFACT: + description: Identifies the artifact that was published. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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/EiffelArtifactPublishedEvent/simple.json diff --git a/definitions/EiffelArtifactPublishedEvent/2.0.0.yml b/definitions/EiffelArtifactPublishedEvent/2.0.0.yml new file mode 100644 index 00000000..28c65bc9 --- /dev/null +++ b/definitions/EiffelArtifactPublishedEvent/2.0.0.yml @@ -0,0 +1,126 @@ +# 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: ArtP +_description: The EiffelArtifactPublishedEvent declares that a software + artifact (declared by [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md)) + has been published and is consequently available for retrieval at + one or more locations. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + locations: + _description: A list of locations at which the artifact may + be retrieved. + type: array + items: + type: object + properties: + type: + _description: |- + The type of location. May be used by (automated) readers to understand the method of retrieval, particularly with regards to authentication. + ARTIFACTORY signifies an [Artifactory](https://www.jfrog.com/artifactory/) + NEXUS signifies a [Nexus](http://www.sonatype.org/nexus/) + PLAIN signifies a plain HTTP GET request. + OTHER signifies other methods of retrieval. Note that using this type likely requires some foreknowledge on part of the reader in order to fetch the artifact. + type: string + enum: + - ARTIFACTORY + - NEXUS + - PLAIN + - OTHER + uri: + _description: The URI at which the artifact can be retrieved. + type: string + required: + - type + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - locations + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ARTIFACT: + description: Identifies the artifact that was published. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactPublishedEvent/simple.json diff --git a/definitions/EiffelArtifactPublishedEvent/3.0.0.yml b/definitions/EiffelArtifactPublishedEvent/3.0.0.yml new file mode 100644 index 00000000..016598c9 --- /dev/null +++ b/definitions/EiffelArtifactPublishedEvent/3.0.0.yml @@ -0,0 +1,129 @@ +# 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: ArtP +_description: The EiffelArtifactPublishedEvent declares that a software + artifact (declared by [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md)) + has been published and is consequently available for retrieval at + one or more locations. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + locations: + _description: A list of locations at which the artifact may + be retrieved. + type: array + items: + type: object + properties: + type: + _description: |- + The type of location. May be used by (automated) readers to understand the method of retrieval, particularly with regards to authentication. + ARTIFACTORY signifies an [Artifactory](https://www.jfrog.com/artifactory/) + NEXUS signifies a [Nexus](http://www.sonatype.org/nexus/) + PLAIN signifies a plain HTTP GET request. + OTHER signifies other methods of retrieval. Note that using this type likely requires some foreknowledge on part of the reader in order to fetch the artifact. + type: string + enum: + - ARTIFACTORY + - NEXUS + - PLAIN + - OTHER + uri: + _description: The URI at which the artifact can be retrieved. + type: string + required: + - type + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - locations + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ARTIFACT: + description: Identifies the artifact that was published. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactPublishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactPublishedEvent/simple.json diff --git a/definitions/EiffelArtifactPublishedEvent/3.1.0.yml b/definitions/EiffelArtifactPublishedEvent/3.1.0.yml new file mode 100644 index 00000000..4b65cd2b --- /dev/null +++ b/definitions/EiffelArtifactPublishedEvent/3.1.0.yml @@ -0,0 +1,140 @@ +# 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: ArtP +_description: The EiffelArtifactPublishedEvent declares that a software + artifact (declared by [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md)) + has been published and is consequently available for retrieval at + one or more locations. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + locations: + _description: A list of locations at which the artifact may + be retrieved. + type: array + items: + type: object + properties: + name: + _description: Identifies the name of the file within + the artifact for which this location provides the URI. + Must correspond to a __data.fileInformation.name__ + value in the [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md) + connected via the __ARTIFACT__ link. + type: string + type: + _description: |- + The type of location. May be used by (automated) readers to understand the method of retrieval, particularly with regards to authentication. + ARTIFACTORY signifies an [Artifactory](https://www.jfrog.com/artifactory/) + NEXUS signifies a [Nexus](http://www.sonatype.org/nexus/) + PLAIN signifies a plain HTTP GET request. + OTHER signifies other methods of retrieval. Note that using this type likely requires some foreknowledge on part of the reader in order to fetch the artifact. + type: string + enum: + - ARTIFACTORY + - NEXUS + - PLAIN + - OTHER + uri: + _description: The URI at which the artifact can be retrieved. + type: string + required: + - type + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - locations + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ARTIFACT: + description: Identifies the artifact that was published. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.1.0 + introduced_in: '[edition-paris](../../../tree/edition-paris)' + changes: Added name qualifier for artifact locations (see [Issue + 248](https://github.com/eiffel-community/eiffel/issues/248)) + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactPublishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactPublishedEvent/simple.json diff --git a/definitions/EiffelArtifactPublishedEvent/3.2.0.yml b/definitions/EiffelArtifactPublishedEvent/3.2.0.yml new file mode 100644 index 00000000..32275bd1 --- /dev/null +++ b/definitions/EiffelArtifactPublishedEvent/3.2.0.yml @@ -0,0 +1,144 @@ +# 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: ArtP +_description: The EiffelArtifactPublishedEvent declares that a software + artifact (declared by [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md)) + has been published and is consequently available for retrieval at + one or more locations. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + locations: + _description: A list of locations at which the artifact may + be retrieved. + type: array + items: + type: object + properties: + name: + _description: Identifies the name of the file within + the artifact for which this location provides the URI. + Must correspond to a __data.fileInformation.name__ + value in the [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md) + connected via the __ARTIFACT__ link. + type: string + type: + _description: |- + The type of location. May be used by (automated) readers to understand the method of retrieval, particularly with regards to authentication. + ARTIFACTORY signifies an [Artifactory](https://www.jfrog.com/artifactory/) + NEXUS signifies a [Nexus](http://www.sonatype.org/nexus/) + PLAIN signifies a plain HTTP GET request. + OTHER signifies other methods of retrieval. Note that using this type likely requires some foreknowledge on part of the reader in order to fetch the artifact. + type: string + enum: + - ARTIFACTORY + - NEXUS + - PLAIN + - OTHER + uri: + _description: The URI at which the artifact can be retrieved. + type: string + required: + - type + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - locations + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + ARTIFACT: + description: Identifies the artifact that was published. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.2.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.1.0 + introduced_in: '[edition-paris](../../../tree/edition-paris)' + changes: Added name qualifier for artifact locations (see [Issue + 248](https://github.com/eiffel-community/eiffel/issues/248)) + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactPublishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactPublishedEvent/simple.json diff --git a/definitions/EiffelArtifactReusedEvent/1.0.0.yml b/definitions/EiffelArtifactReusedEvent/1.0.0.yml new file mode 100644 index 00000000..4a63a03b --- /dev/null +++ b/definitions/EiffelArtifactReusedEvent/1.0.0.yml @@ -0,0 +1,101 @@ +# 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: ArtR +_description: |- + The EiffelArtifactReusedEvent declares that an identified [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md) has been _reused_ for an identified [EiffelCompositionDefinedEvent](./EiffelCompositionDefinedEvent.md). This means that it is logically equivalent to an artifact that would have been built from that composition, and can be used for build avoidance (see the [Build Avoidance Usage Example](../usage-examples/build-avoidance.md) for more information). + + The event has no data members, but solely relies on its two required link types __REUSED_ARTIFACT__ and __COMPOSITION__ (see below). +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition for which an already existing + artifact (identified by __REUSED_ARTIFACT__) is declared reused. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + REUSED_ARTIFACT: + description: This link identifies the [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) + that is reused for the composition identified by __COMPOSITION__; + in other words, the artifact that is not rebuilt for a that composition. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelArtifactReusedEvent/simple.json diff --git a/definitions/EiffelArtifactReusedEvent/1.1.0.yml b/definitions/EiffelArtifactReusedEvent/1.1.0.yml new file mode 100644 index 00000000..1ae556ee --- /dev/null +++ b/definitions/EiffelArtifactReusedEvent/1.1.0.yml @@ -0,0 +1,104 @@ +# 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: ArtR +_description: |- + The EiffelArtifactReusedEvent declares that an identified [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md) has been _reused_ for an identified [EiffelCompositionDefinedEvent](./EiffelCompositionDefinedEvent.md). This means that it is logically equivalent to an artifact that would have been built from that composition, and can be used for build avoidance (see the [Build Avoidance Usage Example](../usage-examples/build-avoidance.md) for more information). + + The event has no data members, but solely relies on its two required link types __REUSED_ARTIFACT__ and __COMPOSITION__ (see below). +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition for which an already existing + artifact (identified by __REUSED_ARTIFACT__) is declared reused. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + REUSED_ARTIFACT: + description: This link identifies the [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) + that is reused for the composition identified by __COMPOSITION__; + in other words, the artifact that is not rebuilt for a that composition. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_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/EiffelArtifactReusedEvent/simple.json diff --git a/definitions/EiffelArtifactReusedEvent/2.0.0.yml b/definitions/EiffelArtifactReusedEvent/2.0.0.yml new file mode 100644 index 00000000..0cb193f9 --- /dev/null +++ b/definitions/EiffelArtifactReusedEvent/2.0.0.yml @@ -0,0 +1,108 @@ +# 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: ArtR +_description: |- + The EiffelArtifactReusedEvent declares that an identified [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md) has been _reused_ for an identified [EiffelCompositionDefinedEvent](./EiffelCompositionDefinedEvent.md). This means that it is logically equivalent to an artifact that would have been built from that composition, and can be used for build avoidance (see the [Build Avoidance Usage Example](../usage-examples/build-avoidance.md) for more information). + + The event has no data members, but solely relies on its two required link types __REUSED_ARTIFACT__ and __COMPOSITION__ (see below). +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition for which an already existing + artifact (identified by __REUSED_ARTIFACT__) is declared reused. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + REUSED_ARTIFACT: + description: This link identifies the [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) + that is reused for the composition identified by __COMPOSITION__; + in other words, the artifact that is not rebuilt for a that composition. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactReusedEvent/simple.json diff --git a/definitions/EiffelArtifactReusedEvent/3.0.0.yml b/definitions/EiffelArtifactReusedEvent/3.0.0.yml new file mode 100644 index 00000000..76a9dba6 --- /dev/null +++ b/definitions/EiffelArtifactReusedEvent/3.0.0.yml @@ -0,0 +1,111 @@ +# 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: ArtR +_description: |- + The EiffelArtifactReusedEvent declares that an identified [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md) has been _reused_ for an identified [EiffelCompositionDefinedEvent](./EiffelCompositionDefinedEvent.md). This means that it is logically equivalent to an artifact that would have been built from that composition, and can be used for build avoidance (see the [Build Avoidance Usage Example](../usage-examples/build-avoidance.md) for more information). + + The event has no data members, but solely relies on its two required link types __REUSED_ARTIFACT__ and __COMPOSITION__ (see below). +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition for which an already existing + artifact (identified by __REUSED_ARTIFACT__) is declared reused. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + REUSED_ARTIFACT: + description: This link identifies the [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) + that is reused for the composition identified by __COMPOSITION__; + in other words, the artifact that is not rebuilt for a that composition. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactReusedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactReusedEvent/simple.json diff --git a/definitions/EiffelArtifactReusedEvent/3.1.0.yml b/definitions/EiffelArtifactReusedEvent/3.1.0.yml new file mode 100644 index 00000000..be4d6125 --- /dev/null +++ b/definitions/EiffelArtifactReusedEvent/3.1.0.yml @@ -0,0 +1,115 @@ +# 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: ArtR +_description: |- + The EiffelArtifactReusedEvent declares that an identified [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md) has been _reused_ for an identified [EiffelCompositionDefinedEvent](./EiffelCompositionDefinedEvent.md). This means that it is logically equivalent to an artifact that would have been built from that composition, and can be used for build avoidance (see the [Build Avoidance Usage Example](../usage-examples/build-avoidance.md) for more information). + + The event has no data members, but solely relies on its two required link types __REUSED_ARTIFACT__ and __COMPOSITION__ (see below). +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + COMPOSITION: + description: Identifies the composition for which an already existing + artifact (identified by __REUSED_ARTIFACT__) is declared reused. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent + 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 + REUSED_ARTIFACT: + description: This link identifies the [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) + that is reused for the composition identified by __COMPOSITION__; + in other words, the artifact that is not rebuilt for a that composition. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent +_history: + - version: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactReusedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelArtifactReusedEvent/simple.json diff --git a/definitions/EiffelCompositionDefinedEvent/1.0.0.yml b/definitions/EiffelCompositionDefinedEvent/1.0.0.yml new file mode 100644 index 00000000..afc3c9db --- /dev/null +++ b/definitions/EiffelCompositionDefinedEvent/1.0.0.yml @@ -0,0 +1,116 @@ +# 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: CD +_description: The EiffelCompositionDefinedEvent declares a composition + of items (artifacts, sources and other compositions) has been defined, + typically with the purpose of enabling further downstream artifacts + to be generated. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the composition. + type: string + version: + _description: The version of the composition, if any. This + is in a sense redundant, as relationships between compositions + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ELEMENT: + description: Identifies an element and/or sub-composition of this + composition. The latter is particularly useful for documenting + large and potentially decentralized compositions, and may be + used to reduce the need to repeat large compositions in which + only small parts are subject to frequent change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeSubmittedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the composition. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelCompositionDefinedEvent/simple.json diff --git a/definitions/EiffelCompositionDefinedEvent/1.1.0.yml b/definitions/EiffelCompositionDefinedEvent/1.1.0.yml new file mode 100644 index 00000000..f2730f81 --- /dev/null +++ b/definitions/EiffelCompositionDefinedEvent/1.1.0.yml @@ -0,0 +1,119 @@ +# 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: CD +_description: The EiffelCompositionDefinedEvent declares a composition + of items (artifacts, sources and other compositions) has been defined, + typically with the purpose of enabling further downstream artifacts + to be generated. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the composition. + type: string + version: + _description: The version of the composition, if any. This + is in a sense redundant, as relationships between compositions + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ELEMENT: + description: Identifies an element and/or sub-composition of this + composition. The latter is particularly useful for documenting + large and potentially decentralized compositions, and may be + used to reduce the need to repeat large compositions in which + only small parts are subject to frequent change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeSubmittedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the composition. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent +_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/EiffelCompositionDefinedEvent/simple.json diff --git a/definitions/EiffelCompositionDefinedEvent/2.0.0.yml b/definitions/EiffelCompositionDefinedEvent/2.0.0.yml new file mode 100644 index 00000000..91ccbe29 --- /dev/null +++ b/definitions/EiffelCompositionDefinedEvent/2.0.0.yml @@ -0,0 +1,123 @@ +# 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: CD +_description: The EiffelCompositionDefinedEvent declares a composition + of items (artifacts, sources and other compositions) has been defined, + typically with the purpose of enabling further downstream artifacts + to be generated. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + name: + _description: The name of the composition. + type: string + version: + _description: The version of the composition, if any. This + is in a sense redundant, as relationships between compositions + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ELEMENT: + description: Identifies an element and/or sub-composition of this + composition. The latter is particularly useful for documenting + large and potentially decentralized compositions, and may be + used to reduce the need to repeat large compositions in which + only small parts are subject to frequent change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeSubmittedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the composition. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelCompositionDefinedEvent/simple.json diff --git a/definitions/EiffelCompositionDefinedEvent/3.0.0.yml b/definitions/EiffelCompositionDefinedEvent/3.0.0.yml new file mode 100644 index 00000000..5da2d699 --- /dev/null +++ b/definitions/EiffelCompositionDefinedEvent/3.0.0.yml @@ -0,0 +1,126 @@ +# 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: CD +_description: The EiffelCompositionDefinedEvent declares a composition + of items (artifacts, sources and other compositions) has been defined, + typically with the purpose of enabling further downstream artifacts + to be generated. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the composition. + type: string + version: + _description: The version of the composition, if any. This + is in a sense redundant, as relationships between compositions + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ELEMENT: + description: Identifies an element and/or sub-composition of this + composition. The latter is particularly useful for documenting + large and potentially decentralized compositions, and may be + used to reduce the need to repeat large compositions in which + only small parts are subject to frequent change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeSubmittedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the composition. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelCompositionDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelCompositionDefinedEvent/simple.json diff --git a/definitions/EiffelCompositionDefinedEvent/3.1.0.yml b/definitions/EiffelCompositionDefinedEvent/3.1.0.yml new file mode 100644 index 00000000..1f8fd064 --- /dev/null +++ b/definitions/EiffelCompositionDefinedEvent/3.1.0.yml @@ -0,0 +1,131 @@ +# 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: CD +_description: The EiffelCompositionDefinedEvent declares a composition + of items (artifacts, sources and other compositions) has been defined, + typically with the purpose of enabling further downstream artifacts + to be generated. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the composition. + type: string + version: + _description: The version of the composition, if any. This + is in a sense redundant, as relationships between compositions + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ELEMENT: + description: Identifies an element and/or sub-composition of this + composition. The latter is particularly useful for documenting + large and potentially decentralized compositions, and may be + used to reduce the need to repeat large compositions in which + only small parts are subject to frequent change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeCreatedEvent + - EiffelSourceChangeSubmittedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the composition. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent +_history: + - version: 3.1.0 + introduced_in: '[edition-paris](../../../tree/edition-paris)' + changes: Added SCC as valid target for ELEMENT links (see [Issue + 218](https://github.com/eiffel-community/eiffel/issues/218)) + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelCompositionDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelCompositionDefinedEvent/simple.json diff --git a/definitions/EiffelCompositionDefinedEvent/3.2.0.yml b/definitions/EiffelCompositionDefinedEvent/3.2.0.yml new file mode 100644 index 00000000..4b20500d --- /dev/null +++ b/definitions/EiffelCompositionDefinedEvent/3.2.0.yml @@ -0,0 +1,135 @@ +# 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: CD +_description: The EiffelCompositionDefinedEvent declares a composition + of items (artifacts, sources and other compositions) has been defined, + typically with the purpose of enabling further downstream artifacts + to be generated. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the composition. + type: string + version: + _description: The version of the composition, if any. This + is in a sense redundant, as relationships between compositions + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ELEMENT: + description: Identifies an element and/or sub-composition of this + composition. The latter is particularly useful for documenting + large and potentially decentralized compositions, and may be + used to reduce the need to repeat large compositions in which + only small parts are subject to frequent change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeCreatedEvent + - EiffelSourceChangeSubmittedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the composition. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelCompositionDefinedEvent +_history: + - version: 3.2.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.1.0 + introduced_in: '[edition-paris](../../../tree/edition-paris)' + changes: Added SCC as valid target for ELEMENT links (see [Issue + 218](https://github.com/eiffel-community/eiffel/issues/218)) + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelCompositionDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelCompositionDefinedEvent/simple.json diff --git a/definitions/EiffelConfidenceLevelModifiedEvent/1.0.0.yml b/definitions/EiffelConfidenceLevelModifiedEvent/1.0.0.yml new file mode 100644 index 00000000..d0ec01a8 --- /dev/null +++ b/definitions/EiffelConfidenceLevelModifiedEvent/1.0.0.yml @@ -0,0 +1,147 @@ +# 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: CLM +_description: |- + The EiffelConfidenceLevelModifiedEvent declares that an entity has achieved (or failed to achieve) a certain level of confidence, or in a broader sense to annotate it as being applicable or relevant to a certain case (e.g. fit for release to a certain customer segment or having passed certain criteria. This is particularly useful for promoting various engineering artifacts, such as product revisions, through the continuous integration and delivery pipeline. + + Confidence levels may operate at high or low levels of abstraction - ranging from "smokeTestsOk" to "releasable" or "released" - and they may group other confidence levels of lower abstraction levels. They may also be general or very niched, e.g. "releasable" or "reseabableToCustomerX". Confidence levels frequently figure in automated delivery interfaces within a tiered system context: lower level tiers issue an agreed confidence level signaling that a new version is ready for integration in a higher level tier. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the confidence level. It is recommended + for confidence level names to conform with camelCase formatting, + in line with the format of key names of the Eiffel protocol + as a whole. + type: string + value: + _description: |- + The value of the confidence level. + SUCCESS signifies that the confidence level has been successfully achieved. + FAILURE signifies that the confidence level could not be achieved. + INCONCLUSIVE signifies that achievement of the confidence level could not be determined. + type: string + enum: + - SUCCESS + - FAILURE + - INCONCLUSIVE + issuer: + _description: The individual or entity issuing the confidence + level. + type: object + properties: + name: + _description: The name of the issuer. + type: string + email: + _description: The e-mail address of the issuer. + type: string + id: + _description: Any identity, alias or handle of the issuer, + such as a corporate id or username. + type: string + group: + _description: Any group, such as a development team, committee + or test group, to which the issuer belongs. + type: string + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + - value + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + SUBJECT: + description: Identifies a subject of the confidence level; in other + words, what the confidence level applies to. + required: true + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeCreatedEvent + - EiffelSourceChangeSubmittedEvent + SUB_CONFIDENCE_LEVEL: + description: 'Used in events summarizing multiple confidence levels. + Example use case: the confidence level "allTestsOk" summarizes + the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", + and consequently links to them via __SUB_CONFIDENCE_LEVEL__. + This is intended for purely descriptive, rather than prescriptive, + use.' + required: false + multiple: true + targets: + any_type: false + types: + - EiffelConfidenceLevelModifiedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelConfidenceLevelModifiedEvent/simple.json diff --git a/definitions/EiffelConfidenceLevelModifiedEvent/1.1.0.yml b/definitions/EiffelConfidenceLevelModifiedEvent/1.1.0.yml new file mode 100644 index 00000000..bca9d7a1 --- /dev/null +++ b/definitions/EiffelConfidenceLevelModifiedEvent/1.1.0.yml @@ -0,0 +1,150 @@ +# 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: CLM +_description: |- + The EiffelConfidenceLevelModifiedEvent declares that an entity has achieved (or failed to achieve) a certain level of confidence, or in a broader sense to annotate it as being applicable or relevant to a certain case (e.g. fit for release to a certain customer segment or having passed certain criteria). This is particularly useful for promoting various engineering artifacts, such as product revisions, through the continuous integration and delivery pipeline. + + Confidence levels may operate at high or low levels of abstraction - ranging from "smokeTestsOk" to "releasable" or "released" - and they may group other confidence levels of lower abstraction levels. They may also be general or very niched, e.g. "releasable" or "reseabableToCustomerX". Confidence levels frequently figure in automated delivery interfaces within a tiered system context: lower level tiers issue an agreed confidence level signaling that a new version is ready for integration in a higher level tier. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the confidence level. It is recommended + for confidence level names to conform with camelCase formatting, + in line with the format of key names of the Eiffel protocol + as a whole. + type: string + value: + _description: |- + The value of the confidence level. + SUCCESS signifies that the confidence level has been successfully achieved. + FAILURE signifies that the confidence level could not be achieved. + INCONCLUSIVE signifies that achievement of the confidence level could not be determined. + type: string + enum: + - SUCCESS + - FAILURE + - INCONCLUSIVE + issuer: + _description: The individual or entity issuing the confidence + level. + type: object + properties: + name: + _description: The name of the issuer. + type: string + email: + _description: The e-mail address of the issuer. + type: string + id: + _description: Any identity, alias or handle of the issuer, + such as a corporate id or username. + type: string + group: + _description: Any group, such as a development team, committee + or test group, to which the issuer belongs. + type: string + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + - value + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + SUBJECT: + description: Identifies a subject of the confidence level; in other + words, what the confidence level applies to. + required: true + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeCreatedEvent + - EiffelSourceChangeSubmittedEvent + SUB_CONFIDENCE_LEVEL: + description: 'Used in events summarizing multiple confidence levels. + Example use case: the confidence level "allTestsOk" summarizes + the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", + and consequently links to them via __SUB_CONFIDENCE_LEVEL__. + This is intended for purely descriptive, rather than prescriptive, + use.' + required: false + multiple: true + targets: + any_type: false + types: + - EiffelConfidenceLevelModifiedEvent +_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/EiffelConfidenceLevelModifiedEvent/simple.json diff --git a/definitions/EiffelConfidenceLevelModifiedEvent/2.0.0.yml b/definitions/EiffelConfidenceLevelModifiedEvent/2.0.0.yml new file mode 100644 index 00000000..834bfde4 --- /dev/null +++ b/definitions/EiffelConfidenceLevelModifiedEvent/2.0.0.yml @@ -0,0 +1,154 @@ +# 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: CLM +_description: |- + The EiffelConfidenceLevelModifiedEvent declares that an entity has achieved (or failed to achieve) a certain level of confidence, or in a broader sense to annotate it as being applicable or relevant to a certain case (e.g. fit for release to a certain customer segment or having passed certain criteria). This is particularly useful for promoting various engineering artifacts, such as product revisions, through the continuous integration and delivery pipeline. + + Confidence levels may operate at high or low levels of abstraction - ranging from "smokeTestsOk" to "releasable" or "released" - and they may group other confidence levels of lower abstraction levels. They may also be general or very niched, e.g. "releasable" or "reseabableToCustomerX". Confidence levels frequently figure in automated delivery interfaces within a tiered system context: lower level tiers issue an agreed confidence level signaling that a new version is ready for integration in a higher level tier. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + name: + _description: The name of the confidence level. It is recommended + for confidence level names to conform with camelCase formatting, + in line with the format of key names of the Eiffel protocol + as a whole. + type: string + value: + _description: |- + The value of the confidence level. + SUCCESS signifies that the confidence level has been successfully achieved. + FAILURE signifies that the confidence level could not be achieved. + INCONCLUSIVE signifies that achievement of the confidence level could not be determined. + type: string + enum: + - SUCCESS + - FAILURE + - INCONCLUSIVE + issuer: + _description: The individual or entity issuing the confidence + level. + type: object + properties: + name: + _description: The name of the issuer. + type: string + email: + _description: The e-mail address of the issuer. + type: string + id: + _description: Any identity, alias or handle of the issuer, + such as a corporate id or username. + type: string + group: + _description: Any group, such as a development team, committee + or test group, to which the issuer belongs. + type: string + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + - value + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + SUBJECT: + description: Identifies a subject of the confidence level; in other + words, what the confidence level applies to. + required: true + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeCreatedEvent + - EiffelSourceChangeSubmittedEvent + SUB_CONFIDENCE_LEVEL: + description: 'Used in events summarizing multiple confidence levels. + Example use case: the confidence level "allTestsOk" summarizes + the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", + and consequently links to them via __SUB_CONFIDENCE_LEVEL__. + This is intended for purely descriptive, rather than prescriptive, + use.' + required: false + multiple: true + targets: + any_type: false + types: + - EiffelConfidenceLevelModifiedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelConfidenceLevelModifiedEvent/simple.json diff --git a/definitions/EiffelConfidenceLevelModifiedEvent/3.0.0.yml b/definitions/EiffelConfidenceLevelModifiedEvent/3.0.0.yml new file mode 100644 index 00000000..cc045840 --- /dev/null +++ b/definitions/EiffelConfidenceLevelModifiedEvent/3.0.0.yml @@ -0,0 +1,157 @@ +# 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: CLM +_description: |- + The EiffelConfidenceLevelModifiedEvent declares that an entity has achieved (or failed to achieve) a certain level of confidence, or in a broader sense to annotate it as being applicable or relevant to a certain case (e.g. fit for release to a certain customer segment or having passed certain criteria). This is particularly useful for promoting various engineering artifacts, such as product revisions, through the continuous integration and delivery pipeline. + + Confidence levels may operate at high or low levels of abstraction - ranging from "smokeTestsOk" to "releasable" or "released" - and they may group other confidence levels of lower abstraction levels. They may also be general or very niched, e.g. "releasable" or "reseabableToCustomerX". Confidence levels frequently figure in automated delivery interfaces within a tiered system context: lower level tiers issue an agreed confidence level signaling that a new version is ready for integration in a higher level tier. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the confidence level. It is recommended + for confidence level names to conform with camelCase formatting, + in line with the format of key names of the Eiffel protocol + as a whole. + type: string + value: + _description: |- + The value of the confidence level. + SUCCESS signifies that the confidence level has been successfully achieved. + FAILURE signifies that the confidence level could not be achieved. + INCONCLUSIVE signifies that achievement of the confidence level could not be determined. + type: string + enum: + - SUCCESS + - FAILURE + - INCONCLUSIVE + issuer: + _description: The individual or entity issuing the confidence + level. + type: object + properties: + name: + _description: The name of the issuer. + type: string + email: + _description: The e-mail address of the issuer. + type: string + id: + _description: Any identity, alias or handle of the issuer, + such as a corporate id or username. + type: string + group: + _description: Any group, such as a development team, committee + or test group, to which the issuer belongs. + type: string + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + - value + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + SUBJECT: + description: Identifies a subject of the confidence level; in other + words, what the confidence level applies to. + required: true + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeCreatedEvent + - EiffelSourceChangeSubmittedEvent + SUB_CONFIDENCE_LEVEL: + description: 'Used in events summarizing multiple confidence levels. + Example use case: the confidence level "allTestsOk" summarizes + the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", + and consequently links to them via __SUB_CONFIDENCE_LEVEL__. + This is intended for purely descriptive, rather than prescriptive, + use.' + required: false + multiple: true + targets: + any_type: false + types: + - EiffelConfidenceLevelModifiedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelConfidenceLevelModifiedEvent/simple.json diff --git a/definitions/EiffelConfidenceLevelModifiedEvent/3.1.0.yml b/definitions/EiffelConfidenceLevelModifiedEvent/3.1.0.yml new file mode 100644 index 00000000..7f785456 --- /dev/null +++ b/definitions/EiffelConfidenceLevelModifiedEvent/3.1.0.yml @@ -0,0 +1,161 @@ +# 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: CLM +_description: |- + The EiffelConfidenceLevelModifiedEvent declares that an entity has achieved (or failed to achieve) a certain level of confidence, or in a broader sense to annotate it as being applicable or relevant to a certain case (e.g. fit for release to a certain customer segment or having passed certain criteria). This is particularly useful for promoting various engineering artifacts, such as product revisions, through the continuous integration and delivery pipeline. + + Confidence levels may operate at high or low levels of abstraction - ranging from "smokeTestsOk" to "releasable" or "released" - and they may group other confidence levels of lower abstraction levels. They may also be general or very niched, e.g. "releasable" or "reseabableToCustomerX". Confidence levels frequently figure in automated delivery interfaces within a tiered system context: lower level tiers issue an agreed confidence level signaling that a new version is ready for integration in a higher level tier. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the confidence level. It is recommended + for confidence level names to conform with camelCase formatting, + in line with the format of key names of the Eiffel protocol + as a whole. + type: string + value: + _description: |- + The value of the confidence level. + SUCCESS signifies that the confidence level has been successfully achieved. + FAILURE signifies that the confidence level could not be achieved. + INCONCLUSIVE signifies that achievement of the confidence level could not be determined. + type: string + enum: + - SUCCESS + - FAILURE + - INCONCLUSIVE + issuer: + _description: The individual or entity issuing the confidence + level. + type: object + properties: + name: + _description: The name of the issuer. + type: string + email: + _description: The e-mail address of the issuer. + type: string + id: + _description: Any identity, alias or handle of the issuer, + such as a corporate id or username. + type: string + group: + _description: Any group, such as a development team, committee + or test group, to which the issuer belongs. + type: string + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + - value + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + SUBJECT: + description: Identifies a subject of the confidence level; in other + words, what the confidence level applies to. + required: true + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + - EiffelSourceChangeCreatedEvent + - EiffelSourceChangeSubmittedEvent + SUB_CONFIDENCE_LEVEL: + description: 'Used in events summarizing multiple confidence levels. + Example use case: the confidence level "allTestsOk" summarizes + the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", + and consequently links to them via __SUB_CONFIDENCE_LEVEL__. + This is intended for purely descriptive, rather than prescriptive, + use.' + required: false + multiple: true + targets: + any_type: false + types: + - EiffelConfidenceLevelModifiedEvent +_history: + - version: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelConfidenceLevelModifiedEvent/simple.json diff --git a/definitions/EiffelCustomDataProperty/1.0.0.yml b/definitions/EiffelCustomDataProperty/1.0.0.yml new file mode 100644 index 00000000..9f2049d6 --- /dev/null +++ b/definitions/EiffelCustomDataProperty/1.0.0.yml @@ -0,0 +1,25 @@ +# 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# +type: object +properties: + key: + type: string + value: {} +required: + - key + - value +additionalProperties: false diff --git a/definitions/EiffelEnvironmentDefinedEvent/1.0.0.yml b/definitions/EiffelEnvironmentDefinedEvent/1.0.0.yml new file mode 100644 index 00000000..880b76d4 --- /dev/null +++ b/definitions/EiffelEnvironmentDefinedEvent/1.0.0.yml @@ -0,0 +1,143 @@ +# 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: ED +_description: |- + The EiffelEnvironmentDefinedEvent declares an environment which may be referenced from other events in order to secure traceability to the conditions under which an artifact was created or a test was executed. Depending on the technology domain, the nature of an environment varies greatly however: it may be a virtual image, a complete mechatronic system of millions of independent parts, or anything in between. Consequently, a concise yet complete and generic syntax for describing any environment is futile. + + From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__. Exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the environment. + type: string + version: + _description: The version of the environment, if any. This + is in a sense redundant, as relationships between compositions + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + image: + _description: A string identifying e.g. a [Docker](https://www.docker.com/) + image. While not a perfect description of an environment, + in many cases it is both sufficient and conducive. + type: string + host: + _description: An object identifying a host. This object is + included for pragmatic reasons, as this method of environment + identification is often used in practice. It is discouraged, + however, as it is highly unreliable both in terms of consistency + and traceability. Consistency because consecutive executions + on the same host may produce different results, as there + are no inherent guarantees that it will stay the same over + time. Traceability because when analyzing the historical + record you want a static description of the environment _as + it was at the time of execution_, not a pointer to a dynamic + entity which may or may not have changed since then (and + may or may not have changed again the next time you inspect + it). + type: object + properties: + name: + _description: The hostname. + type: string + user: + _description: The user name on the host. + type: string + required: + - name + - user + additionalProperties: false + uri: + _description: A URI identifying the environment description. + This is the catch-all method of environment descriptions. + Eiffel does not concern itself with the format or nature + of the description, but merely points to its location. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the environment. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: URI example + url: ../examples/events/EiffelEnvironmentDefinedEvent/uri.json + - title: Host example + url: ../examples/events/EiffelEnvironmentDefinedEvent/host.json + - title: Image example + url: ../examples/events/EiffelEnvironmentDefinedEvent/image.json diff --git a/definitions/EiffelEnvironmentDefinedEvent/1.1.0.yml b/definitions/EiffelEnvironmentDefinedEvent/1.1.0.yml new file mode 100644 index 00000000..ae294dc5 --- /dev/null +++ b/definitions/EiffelEnvironmentDefinedEvent/1.1.0.yml @@ -0,0 +1,146 @@ +# 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: ED +_description: |- + The EiffelEnvironmentDefinedEvent declares an environment which may be referenced from other events in order to secure traceability to the conditions under which an artifact was created or a test was executed. Depending on the technology domain, the nature of an environment varies greatly however: it may be a virtual image, a complete mechatronic system of millions of independent parts, or anything in between. Consequently, a concise yet complete and generic syntax for describing any environment is futile. + + From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__. Exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the environment. + type: string + version: + _description: The version of the environment, if any. This + is in a sense redundant, as relationships between compositions + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + image: + _description: A string identifying e.g. a [Docker](https://www.docker.com/) + image. While not a perfect description of an environment, + in many cases it is both sufficient and conducive. + type: string + host: + _description: An object identifying a host. This object is + included for pragmatic reasons, as this method of environment + identification is often used in practice. It is discouraged, + however, as it is highly unreliable both in terms of consistency + and traceability. Consistency because consecutive executions + on the same host may produce different results, as there + are no inherent guarantees that it will stay the same over + time. Traceability because when analyzing the historical + record you want a static description of the environment _as + it was at the time of execution_, not a pointer to a dynamic + entity which may or may not have changed since then (and + may or may not have changed again the next time you inspect + it). + type: object + properties: + name: + _description: The hostname. + type: string + user: + _description: The user name on the host. + type: string + required: + - name + - user + additionalProperties: false + uri: + _description: A URI identifying the environment description. + This is the catch-all method of environment descriptions. + Eiffel does not concern itself with the format or nature + of the description, but merely points to its location. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the environment. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent +_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: URI example + url: ../examples/events/EiffelEnvironmentDefinedEvent/uri.json + - title: Host example + url: ../examples/events/EiffelEnvironmentDefinedEvent/host.json + - title: Image example + url: ../examples/events/EiffelEnvironmentDefinedEvent/image.json diff --git a/definitions/EiffelEnvironmentDefinedEvent/2.0.0.yml b/definitions/EiffelEnvironmentDefinedEvent/2.0.0.yml new file mode 100644 index 00000000..98bd699f --- /dev/null +++ b/definitions/EiffelEnvironmentDefinedEvent/2.0.0.yml @@ -0,0 +1,150 @@ +# 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: ED +_description: |- + The EiffelEnvironmentDefinedEvent declares an environment which may be referenced from other events in order to secure traceability to the conditions under which an artifact was created or a test was executed. Depending on the technology domain, the nature of an environment varies greatly however: it may be a virtual image, a complete mechatronic system of millions of independent parts, or anything in between. Consequently, a concise yet complete and generic syntax for describing any environment is futile. + + From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__. Exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + name: + _description: The name of the environment. + type: string + version: + _description: The version of the environment, if any. This + is in a sense redundant, as relationships between compositions + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + image: + _description: A string identifying e.g. a [Docker](https://www.docker.com/) + image. While not a perfect description of an environment, + in many cases it is both sufficient and conducive. + type: string + host: + _description: An object identifying a host. This object is + included for pragmatic reasons, as this method of environment + identification is often used in practice. It is discouraged, + however, as it is highly unreliable both in terms of consistency + and traceability. Consistency because consecutive executions + on the same host may produce different results, as there + are no inherent guarantees that it will stay the same over + time. Traceability because when analyzing the historical + record you want a static description of the environment _as + it was at the time of execution_, not a pointer to a dynamic + entity which may or may not have changed since then (and + may or may not have changed again the next time you inspect + it). + type: object + properties: + name: + _description: The hostname. + type: string + user: + _description: The user name on the host. + type: string + required: + - name + - user + additionalProperties: false + uri: + _description: A URI identifying the environment description. + This is the catch-all method of environment descriptions. + Eiffel does not concern itself with the format or nature + of the description, but merely points to its location. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the environment. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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: URI example + url: ../examples/events/EiffelEnvironmentDefinedEvent/uri.json + - title: Host example + url: ../examples/events/EiffelEnvironmentDefinedEvent/host.json + - title: Image example + url: ../examples/events/EiffelEnvironmentDefinedEvent/image.json diff --git a/definitions/EiffelEnvironmentDefinedEvent/3.0.0.yml b/definitions/EiffelEnvironmentDefinedEvent/3.0.0.yml new file mode 100644 index 00000000..b9f60678 --- /dev/null +++ b/definitions/EiffelEnvironmentDefinedEvent/3.0.0.yml @@ -0,0 +1,153 @@ +# 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: ED +_description: |- + The EiffelEnvironmentDefinedEvent declares an environment which may be referenced from other events in order to secure traceability to the conditions under which an artifact was created or a test was executed. Depending on the technology domain, the nature of an environment varies greatly however: it may be a virtual image, a complete mechatronic system of millions of independent parts, or anything in between. Consequently, a concise yet complete and generic syntax for describing any environment is futile. + + From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__. Exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the environment. + type: string + version: + _description: The version of the environment, if any. This + is in a sense redundant, as relationships between environments + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + image: + _description: A string identifying e.g. a [Docker](https://www.docker.com/) + image. While not a perfect description of an environment, + in many cases it is both sufficient and conducive. + type: string + host: + _description: An object identifying a host. This object is + included for pragmatic reasons, as this method of environment + identification is often used in practice. It is discouraged, + however, as it is highly unreliable both in terms of consistency + and traceability. Consistency because consecutive executions + on the same host may produce different results, as there + are no inherent guarantees that it will stay the same over + time. Traceability because when analyzing the historical + record you want a static description of the environment _as + it was at the time of execution_, not a pointer to a dynamic + entity which may or may not have changed since then (and + may or may not have changed again the next time you inspect + it). + type: object + properties: + name: + _description: The hostname. + type: string + user: + _description: The user name on the host. + type: string + required: + - name + - user + additionalProperties: false + uri: + _description: A URI identifying the environment description. + This is the catch-all method of environment descriptions. + Eiffel does not concern itself with the format or nature + of the description, but merely points to its location. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the environment. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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: URI example + url: ../examples/events/EiffelEnvironmentDefinedEvent/uri.json + - title: Host example + url: ../examples/events/EiffelEnvironmentDefinedEvent/host.json + - title: Image example + url: ../examples/events/EiffelEnvironmentDefinedEvent/image.json diff --git a/definitions/EiffelEnvironmentDefinedEvent/3.1.0.yml b/definitions/EiffelEnvironmentDefinedEvent/3.1.0.yml new file mode 100644 index 00000000..5ef77c51 --- /dev/null +++ b/definitions/EiffelEnvironmentDefinedEvent/3.1.0.yml @@ -0,0 +1,174 @@ +# 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: ED +_description: |- + The EiffelEnvironmentDefinedEvent declares an environment which may be referenced from other events in order to secure traceability to the conditions under which an artifact was created or a test was executed. Depending on the technology domain, the nature of an environment varies greatly however: it may be a virtual image, a complete mechatronic system of millions of independent parts, or anything in between. Consequently, a concise yet complete and generic syntax for describing any environment is futile. + + From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__, or a __RUNTIME_ENVIRONMENT__ link to another event that provides a more comprehensive description. Unless a link of the latter kind is used exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties or a RUNTIME_ENVIRONMENT link; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the environment. + type: string + version: + _description: The version of the environment, if any. This + is in a sense redundant, as relationships between environments + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + image: + _description: A string identifying e.g. a [Docker](https://www.docker.com/) + image that defines this environment. Use of this member is + discouraged. Prefer using the less ambiguous RUNTIME_ENVIRONMENT + link type. + type: string + host: + _description: An object identifying a host. This object is + included for pragmatic reasons, as this method of environment + identification is often used in practice. It is discouraged, + however, as it is highly unreliable both in terms of consistency + and traceability. Consistency because consecutive executions + on the same host may produce different results, as there + are no inherent guarantees that it will stay the same over + time. Traceability because when analyzing the historical + record you want a static description of the environment _as + it was at the time of execution_, not a pointer to a dynamic + entity which may or may not have changed since then (and + may or may not have changed again the next time you inspect + it). + type: object + properties: + name: + _description: The hostname. + type: string + user: + _description: The user name on the host. + type: string + required: + - name + - user + additionalProperties: false + uri: + _description: A URI identifying the environment description. + This is the catch-all method of environment descriptions. + Eiffel does not concern itself with the format or nature + of the description, but merely points to its location. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the environment. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + RUNTIME_ENVIRONMENT: + description: Identifies a description of a runtime environment + within which an activity has taken place. The target event could + e.g. identify a [Docker](https://www.docker.com/) image, a JVM + distribution archive, or a composition of operating system packages + that were installed on the host system. This link type has the + same purpose as the `data.image` member but allows richer and + less ambiguous descriptions. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent +_history: + - version: 3.1.0 + introduced_in: Current version + changes: Added RUNTIME_ENVIRONMENT link type. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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: URI example + url: ../examples/events/EiffelEnvironmentDefinedEvent/uri.json + - title: Host example + url: ../examples/events/EiffelEnvironmentDefinedEvent/host.json + - title: Image example + url: ../examples/events/EiffelEnvironmentDefinedEvent/image.json + - title: RUNTIME_ENVIRONMENT link example + url: ../examples/events/EiffelEnvironmentDefinedEvent/runtime-env-link.json diff --git a/definitions/EiffelEnvironmentDefinedEvent/3.2.0.yml b/definitions/EiffelEnvironmentDefinedEvent/3.2.0.yml new file mode 100644 index 00000000..d8c0f9ee --- /dev/null +++ b/definitions/EiffelEnvironmentDefinedEvent/3.2.0.yml @@ -0,0 +1,178 @@ +# 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: ED +_description: |- + The EiffelEnvironmentDefinedEvent declares an environment which may be referenced from other events in order to secure traceability to the conditions under which an artifact was created or a test was executed. Depending on the technology domain, the nature of an environment varies greatly however: it may be a virtual image, a complete mechatronic system of millions of independent parts, or anything in between. Consequently, a concise yet complete and generic syntax for describing any environment is futile. + + From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__, or a __RUNTIME_ENVIRONMENT__ link to another event that provides a more comprehensive description. Unless a link of the latter kind is used exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties or a RUNTIME_ENVIRONMENT link; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the environment. + type: string + version: + _description: The version of the environment, if any. This + is in a sense redundant, as relationships between environments + can be tracked via the __PREVIOUS_VERSION__ link type, but + can be used for improved clarity and semantics. + type: string + image: + _description: A string identifying e.g. a [Docker](https://www.docker.com/) + image that defines this environment. Use of this member is + discouraged. Prefer using the less ambiguous RUNTIME_ENVIRONMENT + link type. + type: string + host: + _description: An object identifying a host. This object is + included for pragmatic reasons, as this method of environment + identification is often used in practice. It is discouraged, + however, as it is highly unreliable both in terms of consistency + and traceability. Consistency because consecutive executions + on the same host may produce different results, as there + are no inherent guarantees that it will stay the same over + time. Traceability because when analyzing the historical + record you want a static description of the environment _as + it was at the time of execution_, not a pointer to a dynamic + entity which may or may not have changed since then (and + may or may not have changed again the next time you inspect + it). + type: object + properties: + name: + _description: The hostname. + type: string + user: + _description: The user name on the host. + type: string + required: + - name + - user + additionalProperties: false + uri: + _description: A URI identifying the environment description. + This is the catch-all method of environment descriptions. + Eiffel does not concern itself with the format or nature + of the description, but merely points to its location. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the environment. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + RUNTIME_ENVIRONMENT: + description: Identifies a description of a runtime environment + within which an activity has taken place. The target event could + e.g. identify a [Docker](https://www.docker.com/) image, a JVM + distribution archive, or a composition of operating system packages + that were installed on the host system. This link type has the + same purpose as the `data.image` member but allows richer and + less ambiguous descriptions. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent +_history: + - version: 3.2.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.1.0 + introduced_in: No edition set + changes: Added RUNTIME_ENVIRONMENT link type. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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: URI example + url: ../examples/events/EiffelEnvironmentDefinedEvent/uri.json + - title: Host example + url: ../examples/events/EiffelEnvironmentDefinedEvent/host.json + - title: Image example + url: ../examples/events/EiffelEnvironmentDefinedEvent/image.json + - title: RUNTIME_ENVIRONMENT link example + url: ../examples/events/EiffelEnvironmentDefinedEvent/runtime-env-link.json diff --git a/definitions/EiffelEventLink/1.0.0.yml b/definitions/EiffelEventLink/1.0.0.yml new file mode 100644 index 00000000..0454a943 --- /dev/null +++ b/definitions/EiffelEventLink/1.0.0.yml @@ -0,0 +1,26 @@ +# 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# +type: object +properties: + type: + type: string + target: + type: string +required: + - type + - target +additionalProperties: false diff --git a/definitions/EiffelEventLink/1.0.1.yml b/definitions/EiffelEventLink/1.0.1.yml new file mode 100644 index 00000000..bf43c19e --- /dev/null +++ b/definitions/EiffelEventLink/1.0.1.yml @@ -0,0 +1,27 @@ +# 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# +type: object +properties: + type: + type: string + target: + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ +required: + - type + - target +additionalProperties: false diff --git a/definitions/EiffelEventLink/1.1.0.yml b/definitions/EiffelEventLink/1.1.0.yml new file mode 100644 index 00000000..65bf2089 --- /dev/null +++ b/definitions/EiffelEventLink/1.1.0.yml @@ -0,0 +1,28 @@ +# 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# +type: object +properties: + type: + type: string + target: + type: string + domainId: + type: string +required: + - type + - target +additionalProperties: false diff --git a/definitions/EiffelEventLink/1.1.1.yml b/definitions/EiffelEventLink/1.1.1.yml new file mode 100644 index 00000000..761eb28b --- /dev/null +++ b/definitions/EiffelEventLink/1.1.1.yml @@ -0,0 +1,29 @@ +# 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# +type: object +properties: + type: + type: string + target: + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + domainId: + type: string +required: + - type + - target +additionalProperties: false diff --git a/definitions/EiffelFlowContextDefinedEvent/1.0.0.yml b/definitions/EiffelFlowContextDefinedEvent/1.0.0.yml new file mode 100644 index 00000000..dd3450fe --- /dev/null +++ b/definitions/EiffelFlowContextDefinedEvent/1.0.0.yml @@ -0,0 +1,106 @@ +# 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: FCD +_description: |- + The EiffelFlowContextDefined describes the context of other events, answering questions such as "Which project is change part of?" or "Which track does artifact belong to?". In this way it offers a method of classifying and structuring one's continuous integration and delivery system and thereby facilitaring traceability and searchability. + + The nature of the described context can vary. The event consequently offers a high degree of flexibility in its description, and none of its member fields are mandatory. Instead they can picked and mixed to fit the situation. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + product: + _description: A product context which other events can relate + to (e.g. "This activity is part of the Product X continuous + integration system."). + type: string + project: + _description: A project context which other events can relate + to (e.g. "This test is part of the Killer Feature project."). + type: string + program: + _description: A program context which other events can relate + to (e.g. "This source change was made for the Zero Bugs program."). + type: string + track: + _description: A track context which other events can relate + to (e.g. "This feature was implemented in the Customer X + Adaptations track."). + type: string + version: + _description: A version context which other events can relate + to. This member SHOULD be used in tandem with one of the + other optional members - a version by itself is not very + informative. + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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/EiffelFlowContextDefinedEvent/simple.json diff --git a/definitions/EiffelFlowContextDefinedEvent/1.1.0.yml b/definitions/EiffelFlowContextDefinedEvent/1.1.0.yml new file mode 100644 index 00000000..2ee578b5 --- /dev/null +++ b/definitions/EiffelFlowContextDefinedEvent/1.1.0.yml @@ -0,0 +1,109 @@ +# 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: FCD +_description: |- + The EiffelFlowContextDefinedEvent describes the context of other events, answering questions such as "Which project is this change part of?" or "Which track does this artifact belong to?". In this way it offers a method of classifying and structuring one's continuous integration and delivery system and thereby facilitating traceability and searchability. + + The nature of the described context can vary. The event consequently offers a high degree of flexibility in its description, and none of its member fields are mandatory. Instead they can picked and mixed to fit the situation. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + product: + _description: A product context which other events can relate + to (e.g. "This activity is part of the Product X continuous + integration system."). + type: string + project: + _description: A project context which other events can relate + to (e.g. "This test is part of the Killer Feature project."). + type: string + program: + _description: A program context which other events can relate + to (e.g. "This source change was made for the Zero Bugs program."). + type: string + track: + _description: A track context which other events can relate + to (e.g. "This feature was implemented in the Customer X + Adaptations track."). + type: string + version: + _description: A version context which other events can relate + to. This member SHOULD be used in tandem with one of the + other optional members - a version by itself is not very + informative. + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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/EiffelFlowContextDefinedEvent/simple.json diff --git a/definitions/EiffelFlowContextDefinedEvent/2.0.0.yml b/definitions/EiffelFlowContextDefinedEvent/2.0.0.yml new file mode 100644 index 00000000..e9f35f38 --- /dev/null +++ b/definitions/EiffelFlowContextDefinedEvent/2.0.0.yml @@ -0,0 +1,113 @@ +# 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: FCD +_description: |- + The EiffelFlowContextDefinedEvent describes the context of other events, answering questions such as "Which project is this change part of?" or "Which track does this artifact belong to?". In this way it offers a method of classifying and structuring one's continuous integration and delivery system and thereby facilitating traceability and searchability. + + The nature of the described context can vary. The event consequently offers a high degree of flexibility in its description, and none of its member fields are mandatory. Instead they can picked and mixed to fit the situation. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + product: + _description: A product context which other events can relate + to (e.g. "This activity is part of the Product X continuous + integration system."). + type: string + project: + _description: A project context which other events can relate + to (e.g. "This test is part of the Killer Feature project."). + type: string + program: + _description: A program context which other events can relate + to (e.g. "This source change was made for the Zero Bugs program."). + type: string + track: + _description: A track context which other events can relate + to (e.g. "This feature was implemented in the Customer X + Adaptations track."). + type: string + version: + _description: A version context which other events can relate + to. This member SHOULD be used in tandem with one of the + other optional members - a version by itself is not very + informative. + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelFlowContextDefinedEvent/simple.json diff --git a/definitions/EiffelFlowContextDefinedEvent/3.0.0.yml b/definitions/EiffelFlowContextDefinedEvent/3.0.0.yml new file mode 100644 index 00000000..35406d93 --- /dev/null +++ b/definitions/EiffelFlowContextDefinedEvent/3.0.0.yml @@ -0,0 +1,116 @@ +# 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: FCD +_description: |- + The EiffelFlowContextDefinedEvent describes the context of other events, answering questions such as "Which project is this change part of?" or "Which track does this artifact belong to?". In this way it offers a method of classifying and structuring one's continuous integration and delivery system and thereby facilitating traceability and searchability. + + The nature of the described context can vary. The event consequently offers a high degree of flexibility in its description, and none of its member fields are mandatory. Instead they can picked and mixed to fit the situation. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + product: + _description: A product context which other events can relate + to (e.g. "This activity is part of the Product X continuous + integration system."). + type: string + project: + _description: A project context which other events can relate + to (e.g. "This test is part of the Killer Feature project."). + type: string + program: + _description: A program context which other events can relate + to (e.g. "This source change was made for the Zero Bugs program."). + type: string + track: + _description: A track context which other events can relate + to (e.g. "This feature was implemented in the Customer X + Adaptations track."). + type: string + version: + _description: A version context which other events can relate + to. This member SHOULD be used in tandem with one of the + other optional members - a version by itself is not very + informative. + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelFlowContextDefinedEvent/simple.json diff --git a/definitions/EiffelFlowContextDefinedEvent/3.1.0.yml b/definitions/EiffelFlowContextDefinedEvent/3.1.0.yml new file mode 100644 index 00000000..e0ae6d0a --- /dev/null +++ b/definitions/EiffelFlowContextDefinedEvent/3.1.0.yml @@ -0,0 +1,120 @@ +# 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: FCD +_description: |- + The EiffelFlowContextDefinedEvent describes the context of other events, answering questions such as "Which project is this change part of?" or "Which track does this artifact belong to?". In this way it offers a method of classifying and structuring one's continuous integration and delivery system and thereby facilitating traceability and searchability. + + The nature of the described context can vary. The event consequently offers a high degree of flexibility in its description, and none of its member fields are mandatory. Instead they can picked and mixed to fit the situation. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + product: + _description: A product context which other events can relate + to (e.g. "This activity is part of the Product X continuous + integration system."). + type: string + project: + _description: A project context which other events can relate + to (e.g. "This test is part of the Killer Feature project."). + type: string + program: + _description: A program context which other events can relate + to (e.g. "This source change was made for the Zero Bugs program."). + type: string + track: + _description: A track context which other events can relate + to (e.g. "This feature was implemented in the Customer X + Adaptations track."). + type: string + version: + _description: A version context which other events can relate + to. This member SHOULD be used in tandem with one of the + other optional members - a version by itself is not very + informative. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelFlowContextDefinedEvent/simple.json diff --git a/definitions/EiffelIssueDefinedEvent/1.0.0.yml b/definitions/EiffelIssueDefinedEvent/1.0.0.yml new file mode 100644 index 00000000..34668fdd --- /dev/null +++ b/definitions/EiffelIssueDefinedEvent/1.0.0.yml @@ -0,0 +1,121 @@ +# 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: ID +_description: The EiffelIssueDefinedEvent declares that an issue has + been created in some external issue management software. ID is semantically + similar to + [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) and + [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md). +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + type: + _description: The type of issue. + type: string + enum: + - BUG + - IMPROVEMENT + - FEATURE + - WORK_ITEM + - REQUIREMENT + - OTHER + tracker: + _description: |- + The name of the issue tracker. This can unfortunately not be + standardized, and is therefore context sensitive: though some trackers and ALM + tools are more popular than others, an exhaustive enumeration is impossible, + particularly when considering company specific internal solutions. Consequently + one should not rely on the name as the primary method of retrieval, but rather + __data.uri__. __data.tracker__ together with __data.id__ + is still useful for analysis and traceability, however, as long as it can be + correctly interpreted. + type: string + id: + _description: |- + The identity of the issue. This is tracker dependent - most + trackers have their own issue naming schemes. + type: string + uri: + _description: A URI that links to a document describing the + issue in depth. + type: string + title: + _description: |- + A one-line title or summary of the issue. This exists mostly + for human consumption, as "Implement widget X" is much more meaningful to a + human when viewing a graph of Eiffel events than "1302". This is not meant + to be a detailed description, as such information should be accessible by + following __data.uri__. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - type + - tracker + - id + - uri + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: Current version + changes: Initial version +_examples: + - title: Simple example + url: ../examples/events/EiffelIssueDefinedEvent/simple.json diff --git a/definitions/EiffelIssueDefinedEvent/2.0.0.yml b/definitions/EiffelIssueDefinedEvent/2.0.0.yml new file mode 100644 index 00000000..dc6885a4 --- /dev/null +++ b/definitions/EiffelIssueDefinedEvent/2.0.0.yml @@ -0,0 +1,125 @@ +# 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: ID +_description: The EiffelIssueDefinedEvent declares that an issue has + been created in some external issue management software. ID is semantically + similar to + [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) and + [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md). +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + type: + _description: The type of issue. + type: string + enum: + - BUG + - IMPROVEMENT + - FEATURE + - WORK_ITEM + - REQUIREMENT + - OTHER + tracker: + _description: |- + The name of the issue tracker. This can unfortunately not be + standardized, and is therefore context sensitive: though some trackers and ALM + tools are more popular than others, an exhaustive enumeration is impossible, + particularly when considering company specific internal solutions. Consequently + one should not rely on the name as the primary method of retrieval, but rather + __data.uri__. __data.tracker__ together with __data.id__ + is still useful for analysis and traceability, however, as long as it can be + correctly interpreted. + type: string + id: + _description: |- + The identity of the issue. This is tracker dependent - most + trackers have their own issue naming schemes. + type: string + uri: + _description: A URI that links to a document describing the + issue in depth. + type: string + title: + _description: |- + A one-line title or summary of the issue. This exists mostly + for human consumption, as "Implement widget X" is much more meaningful to a + human when viewing a graph of Eiffel events than "1302". This is not meant + to be a detailed description, as such information should be accessible by + following __data.uri__. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - type + - tracker + - id + - uri + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 1.0.0 + introduced_in: '[0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueDefinedEvent.md)' + changes: Initial version +_examples: + - title: Simple example + url: ../examples/events/EiffelIssueDefinedEvent/simple.json diff --git a/definitions/EiffelIssueDefinedEvent/3.0.0.yml b/definitions/EiffelIssueDefinedEvent/3.0.0.yml new file mode 100644 index 00000000..d060dd80 --- /dev/null +++ b/definitions/EiffelIssueDefinedEvent/3.0.0.yml @@ -0,0 +1,128 @@ +# 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: ID +_description: The EiffelIssueDefinedEvent declares that an issue has + been created in some external issue management software. ID is semantically + similar to + [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) and + [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md). +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + type: + _description: The type of issue. + type: string + enum: + - BUG + - IMPROVEMENT + - FEATURE + - WORK_ITEM + - REQUIREMENT + - OTHER + tracker: + _description: |- + The name of the issue tracker. This can unfortunately not be + standardized, and is therefore context sensitive: though some trackers and ALM + tools are more popular than others, an exhaustive enumeration is impossible, + particularly when considering company specific internal solutions. Consequently + one should not rely on the name as the primary method of retrieval, but rather + __data.uri__. __data.tracker__ together with __data.id__ + is still useful for analysis and traceability, however, as long as it can be + correctly interpreted. + type: string + id: + _description: |- + The identity of the issue. This is tracker dependent - most + trackers have their own issue naming schemes. + type: string + uri: + _description: A URI that links to a document describing the + issue in depth. + type: string + title: + _description: |- + A one-line title or summary of the issue. This exists mostly + for human consumption, as "Implement widget X" is much more meaningful to a + human when viewing a graph of Eiffel events than "1302". This is not meant + to be a detailed description, as such information should be accessible by + following __data.uri__. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - type + - tracker + - id + - uri + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelIssueDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 1.0.0 + introduced_in: '[0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueDefinedEvent.md)' + changes: Initial version +_examples: + - title: Simple example + url: ../examples/events/EiffelIssueDefinedEvent/simple.json diff --git a/definitions/EiffelIssueDefinedEvent/3.1.0.yml b/definitions/EiffelIssueDefinedEvent/3.1.0.yml new file mode 100644 index 00000000..76ef40a4 --- /dev/null +++ b/definitions/EiffelIssueDefinedEvent/3.1.0.yml @@ -0,0 +1,132 @@ +# 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: ID +_description: The EiffelIssueDefinedEvent declares that an issue has + been created in some external issue management software. ID is semantically + similar to + [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) and + [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md). +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + type: + _description: The type of issue. + type: string + enum: + - BUG + - IMPROVEMENT + - FEATURE + - WORK_ITEM + - REQUIREMENT + - OTHER + tracker: + _description: |- + The name of the issue tracker. This can unfortunately not be + standardized, and is therefore context sensitive: though some trackers and ALM + tools are more popular than others, an exhaustive enumeration is impossible, + particularly when considering company specific internal solutions. Consequently + one should not rely on the name as the primary method of retrieval, but rather + __data.uri__. __data.tracker__ together with __data.id__ + is still useful for analysis and traceability, however, as long as it can be + correctly interpreted. + type: string + id: + _description: |- + The identity of the issue. This is tracker dependent - most + trackers have their own issue naming schemes. + type: string + uri: + _description: A URI that links to a document describing the + issue in depth. + type: string + title: + _description: |- + A one-line title or summary of the issue. This exists mostly + for human consumption, as "Implement widget X" is much more meaningful to a + human when viewing a graph of Eiffel events than "1302". This is not meant + to be a detailed description, as such information should be accessible by + following __data.uri__. + type: string + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - type + - tracker + - id + - uri + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelIssueDefinedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 1.0.0 + introduced_in: '[0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueDefinedEvent.md)' + changes: Initial version +_examples: + - title: Simple example + url: ../examples/events/EiffelIssueDefinedEvent/simple.json diff --git a/definitions/EiffelIssueVerifiedEvent/1.0.0.yml b/definitions/EiffelIssueVerifiedEvent/1.0.0.yml new file mode 100644 index 00000000..7efc0e2a --- /dev/null +++ b/definitions/EiffelIssueVerifiedEvent/1.0.0.yml @@ -0,0 +1,170 @@ +# 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: IV +_description: The EiffelIssueVerifiedEvent declares that an issue, + typically a requirement, has been verified by some means. It is different + from [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md) + in that multiple test case executions may serve as the basis for + a single verification or, conversely, multiple issues may be verified + based on a single test case execution. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + issues: + _description: A list of verified (successfully or not) issues. + type: array + items: + type: object + properties: + type: + _description: The type of issue. + type: string + enum: + - BUG + - IMPROVEMENT + - FEATURE + - WORK_ITEM + - REQUIREMENT + - OTHER + tracker: + _description: 'The name of the issue tracker. This can + unfortunately not be standardized, and is therefore + context sensitive: though some trackers and ALM tools + are more popular than others, an exhaustive enumeration + is impossible, particularly when considering company + specific internal solutions. Consequently one should + not rely on the name as the primary method of retrieval, + but rather __data.issues.uri__. __data.issues.tracker__ + together with __data.issues.id__ is still useful for + analysis and traceability, however, as long as it can + be correctly interpreted.' + type: string + id: + _description: The identity of the issue. This is tracker + dependent - most trackers have their own issue naming + schemes. + type: string + uri: + _description: The URI of the issue. + type: string + value: + _description: |- + The value of the verification. + SUCCESS signifies that the issue was successfully verified. + FAILURE signifies that verification of the issue failed. + INCONCLUSIVE signifies that the verification of the issue was inconclusive. + type: string + enum: + - SUCCESS + - FAILURE + - INCONCLUSIVE + required: + - type + - tracker + - id + - uri + - value + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - issues + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the issue was + verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + IUT: + description: Identifies the Item Under Test; in other words, the + entity for which the issue has been verified. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + VERIFICATION_BASIS: + description: Used to declare the basis on which the verification + statement(s) of this event have been issued. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelTestCaseFinishedEvent + - EiffelTestSuiteFinishedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelIssueVerifiedEvent/simple.json diff --git a/definitions/EiffelIssueVerifiedEvent/1.1.0.yml b/definitions/EiffelIssueVerifiedEvent/1.1.0.yml new file mode 100644 index 00000000..bb5a62c3 --- /dev/null +++ b/definitions/EiffelIssueVerifiedEvent/1.1.0.yml @@ -0,0 +1,173 @@ +# 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: IV +_description: The EiffelIssueVerifiedEvent declares that an issue, + typically a requirement, has been verified by some means. It is different + from [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md) + in that multiple test case executions may serve as the basis for + a single verification or, conversely, multiple issues may be verified + based on a single test case execution. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + issues: + _description: A list of verified (successfully or not) issues. + type: array + items: + type: object + properties: + type: + _description: The type of issue. + type: string + enum: + - BUG + - IMPROVEMENT + - FEATURE + - WORK_ITEM + - REQUIREMENT + - OTHER + tracker: + _description: 'The name of the issue tracker. This can + unfortunately not be standardized, and is therefore + context sensitive: though some trackers and ALM tools + are more popular than others, an exhaustive enumeration + is impossible, particularly when considering company + specific internal solutions. Consequently one should + not rely on the name as the primary method of retrieval, + but rather __data.issues.uri__. __data.issues.tracker__ + together with __data.issues.id__ is still useful for + analysis and traceability, however, as long as it can + be correctly interpreted.' + type: string + id: + _description: The identity of the issue. This is tracker + dependent - most trackers have their own issue naming + schemes. + type: string + uri: + _description: The URI of the issue. + type: string + value: + _description: |- + The value of the verification. + SUCCESS signifies that the issue was successfully verified. + FAILURE signifies that verification of the issue failed. + INCONCLUSIVE signifies that the verification of the issue was inconclusive. + type: string + enum: + - SUCCESS + - FAILURE + - INCONCLUSIVE + required: + - type + - tracker + - id + - uri + - value + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - issues + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the issue was + verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + IUT: + description: Identifies the Item Under Test; in other words, the + entity for which the issue has been verified. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + VERIFICATION_BASIS: + description: Used to declare the basis on which the verification + statement(s) of this event have been issued. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelTestCaseFinishedEvent + - EiffelTestSuiteFinishedEvent +_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/EiffelIssueVerifiedEvent/simple.json diff --git a/definitions/EiffelIssueVerifiedEvent/2.0.0.yml b/definitions/EiffelIssueVerifiedEvent/2.0.0.yml new file mode 100644 index 00000000..5baf2ff8 --- /dev/null +++ b/definitions/EiffelIssueVerifiedEvent/2.0.0.yml @@ -0,0 +1,142 @@ +# 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: IV +_description: |- + The EiffelIssueVerifiedEvent declares that an issue, typically a requirement, has been verified by some means. It is different from [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md) in that multiple test case executions may serve as the basis for a single verification or, conversely, multiple issues may be verified based on a single test case execution. + + EiffelIssueVerifiedEvent has no data members, instead relying on its required link types. While "SUCCESSFUL_ISSUE", "FAILED_ISSUE", and "INCONCLUSIVE_ISSUE" are all marked as not required, at least one link of at least one of these types MUST be present in an EiffelIssueVerifiedEvent. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the issue was + verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + FAILED_ISSUE: + description: Identifies an issue that has failed verification. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + 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 + INCONCLUSIVE_ISSUE: + description: Identifies an issue for which this verification was + inconclusive. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + IUT: + description: Identifies the Item Under Test; in other words, the + entity for which the issue has been verified. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + SUCCESSFUL_ISSUE: + description: Identifies an issue that has been successfully verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + VERIFICATION_BASIS: + description: Used to declare the basis on which the verification + statement(s) of this event have been issued. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelTestCaseFinishedEvent + - EiffelTestSuiteFinishedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Replaced data.issues with links + - 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/EiffelIssueVerifiedEvent/simple.json diff --git a/definitions/EiffelIssueVerifiedEvent/3.0.0.yml b/definitions/EiffelIssueVerifiedEvent/3.0.0.yml new file mode 100644 index 00000000..f08b5848 --- /dev/null +++ b/definitions/EiffelIssueVerifiedEvent/3.0.0.yml @@ -0,0 +1,146 @@ +# 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: IV +_description: |- + The EiffelIssueVerifiedEvent declares that an issue, typically a requirement, has been verified by some means. It is different from [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md) in that multiple test case executions may serve as the basis for a single verification or, conversely, multiple issues may be verified based on a single test case execution. + + EiffelIssueVerifiedEvent has no data members, instead relying on its required link types. While "SUCCESSFUL_ISSUE", "FAILED_ISSUE", and "INCONCLUSIVE_ISSUE" are all marked as not required, at least one link of at least one of these types MUST be present in an EiffelIssueVerifiedEvent. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the issue was + verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + FAILED_ISSUE: + description: Identifies an issue that has failed verification. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + 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 + INCONCLUSIVE_ISSUE: + description: Identifies an issue for which this verification was + inconclusive. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + IUT: + description: Identifies the Item Under Test; in other words, the + entity for which the issue has been verified. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + SUCCESSFUL_ISSUE: + description: Identifies an issue that has been successfully verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + VERIFICATION_BASIS: + description: Used to declare the basis on which the verification + statement(s) of this event have been issued. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelTestCaseFinishedEvent + - EiffelTestSuiteFinishedEvent +_history: + - version: 3.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.0.0 + introduced_in: '[0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueVerifiedEvent.md)' + changes: Replaced data.issues with links + - 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/EiffelIssueVerifiedEvent/simple.json diff --git a/definitions/EiffelIssueVerifiedEvent/4.0.0.yml b/definitions/EiffelIssueVerifiedEvent/4.0.0.yml new file mode 100644 index 00000000..b229437d --- /dev/null +++ b/definitions/EiffelIssueVerifiedEvent/4.0.0.yml @@ -0,0 +1,149 @@ +# 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: IV +_description: |- + The EiffelIssueVerifiedEvent declares that an issue, typically a requirement, has been verified by some means. It is different from [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md) in that multiple test case executions may serve as the basis for a single verification or, conversely, multiple issues may be verified based on a single test case execution. + + EiffelIssueVerifiedEvent has no data members, instead relying on its required link types. While "SUCCESSFUL_ISSUE", "FAILED_ISSUE", and "INCONCLUSIVE_ISSUE" are all marked as not required, at least one link of at least one of these types MUST be present in an EiffelIssueVerifiedEvent. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the issue was + verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + FAILED_ISSUE: + description: Identifies an issue that has failed verification. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + 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 + INCONCLUSIVE_ISSUE: + description: Identifies an issue for which this verification was + inconclusive. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + IUT: + description: Identifies the Item Under Test; in other words, the + entity for which the issue has been verified. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + SUCCESSFUL_ISSUE: + description: Identifies an issue that has been successfully verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + VERIFICATION_BASIS: + description: Used to declare the basis on which the verification + statement(s) of this event have been issued. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelTestCaseFinishedEvent + - EiffelTestSuiteFinishedEvent +_history: + - version: 4.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 3.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelIssueVerifiedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.0.0 + introduced_in: '[0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueVerifiedEvent.md)' + changes: Replaced data.issues with links + - 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/EiffelIssueVerifiedEvent/simple.json diff --git a/definitions/EiffelIssueVerifiedEvent/4.1.0.yml b/definitions/EiffelIssueVerifiedEvent/4.1.0.yml new file mode 100644 index 00000000..20b6c619 --- /dev/null +++ b/definitions/EiffelIssueVerifiedEvent/4.1.0.yml @@ -0,0 +1,153 @@ +# 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: IV +_description: |- + The EiffelIssueVerifiedEvent declares that an issue, typically a requirement, has been verified by some means. It is different from [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md) in that multiple test case executions may serve as the basis for a single verification or, conversely, multiple issues may be verified based on a single test case execution. + + EiffelIssueVerifiedEvent has no data members, instead relying on its required link types. While "SUCCESSFUL_ISSUE", "FAILED_ISSUE", and "INCONCLUSIVE_ISSUE" are all marked as not required, at least one link of at least one of these types MUST be present in an EiffelIssueVerifiedEvent. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the issue was + verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + FAILED_ISSUE: + description: Identifies an issue that has failed verification. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + 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 + INCONCLUSIVE_ISSUE: + description: Identifies an issue for which this verification was + inconclusive. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + IUT: + description: Identifies the Item Under Test; in other words, the + entity for which the issue has been verified. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + SUCCESSFUL_ISSUE: + description: Identifies an issue that has been successfully verified. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + VERIFICATION_BASIS: + description: Used to declare the basis on which the verification + statement(s) of this event have been issued. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelTestCaseFinishedEvent + - EiffelTestSuiteFinishedEvent +_history: + - version: 4.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 4.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 3.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelIssueVerifiedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.0.0 + introduced_in: '[0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueVerifiedEvent.md)' + changes: Replaced data.issues with links + - 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/EiffelIssueVerifiedEvent/simple.json diff --git a/definitions/EiffelMetaProperty/1.0.0.yml b/definitions/EiffelMetaProperty/1.0.0.yml new file mode 100644 index 00000000..5a3e9110 --- /dev/null +++ b/definitions/EiffelMetaProperty/1.0.0.yml @@ -0,0 +1,153 @@ +# 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# +type: object +properties: + id: + _description: >- + The unique identity of the event, generated at event creation. + _format: '[UUID](http://tools.ietf.org/html/rfc4122)' + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + type: + _description: >- + The type of event. This field is required by the recipient of + the event, as each event type has a specific meaning and a specific + set of members in the __data__ and __links__ objects. + _format: An event type name + type: string + version: + _description: >- + The version of the event type. This field is required by the recipient + of the event to interpret the contents. Please see + [Versioning](../eiffel-syntax-and-usage/versioning.md) for more + information. + _format: '[Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html)' + type: string + time: + _description: The event creation timestamp. + _format: Milliseconds since epoch. + type: integer + tags: + _description: >- + Any tags or keywords associated with the events, for searchability + purposes. + _format: Free text + type: array + items: + type: string + source: + _description: >- + A description of the source of the event. This object is primarily for + traceability purposes, and while optional, some form of identification + of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of + identifying the source of the event, techniques which may be select from + based on the technology domain and needs in any particular use case. + type: object + properties: + domainId: + _description: >- + Identifies the + [domain](../eiffel-syntax-and-usage/glossary.md#domain) that + produced an event. + _format: Free text + type: string + host: + _description: The hostname of the event sender. + _format: Hostname + type: string + name: + _description: The name of the event sender. + _format: Free text + type: string + serializer: + _description: >- + The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) + coordinates of the serializer software used to construct the event. + type: object + properties: + groupId: + _description: The groupId of the serializer software. + _format: groupId + type: string + artifactId: + _description: The artifactId of the serializer software. + _format: artifactId + type: string + version: + _description: The version of the serializer software. + _format: version + type: string + required: + - groupId + - artifactId + - version + additionalProperties: false + uri: + _description: The URI of, related to or describing the event sender. + _format: URI + type: string + additionalProperties: false + security: + _description: >- + An optional object for enclosing security related information, + particularly supporting data integrity. See + [Security](../eiffel-syntax-and-usage/security.md) for further + information. + type: object + properties: + sdm: + _description: >- + An optional object for properties supporting the + [Strong Distribution Model](http://www.cryptnet.net/fdp/crypto/strong_distro.html). + Note that this only addressed the _integrity_ of the Eiffel event, + not its _confidentiality_ or _availability_. + type: object + properties: + authorIdentity: + _description: >- + The identity of the author of the event. This property is + intended to enable the recipient to look up the appropriate + public key for decrypting the digest and thereby verifying + author identity and data integrity. The format of the author + identity varies depending on the key infrastructure solution + used. Note that this requires the presence of a Trusted + Authority (TA) which the recipient can query for the correct + public key. The identity and location of the TA must never + be included in the event itself, as this would compromise + the security of the solution. + type: string + encryptedDigest: + _description: >- + The encrypted digest. The cryptographic hash function and + the decryption algorithm to use, similarly to the Trusted + Authority (TA), must be known to the recipient. Note that + the digest of the entire event is affected by the value of + this property. For this reason the input to the hash function + SHALL be the entire event unaltered in all parts except for + this property, which SHALL be replaced by an empty string. + type: string + required: + - authorIdentity + - encryptedDigest + additionalProperties: false + additionalProperties: false +required: + - id + - type + - version + - time +additionalProperties: false diff --git a/definitions/EiffelMetaProperty/2.0.0.yml b/definitions/EiffelMetaProperty/2.0.0.yml new file mode 100644 index 00000000..92608755 --- /dev/null +++ b/definitions/EiffelMetaProperty/2.0.0.yml @@ -0,0 +1,114 @@ +# 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# +type: object +properties: + id: + _description: >- + The unique identity of the event, generated at event creation. + _format: '[UUID](http://tools.ietf.org/html/rfc4122)' + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + type: + _description: >- + The type of event. This field is required by the recipient of + the event, as each event type has a specific meaning and a specific + set of members in the __data__ and __links__ objects. + _format: An event type name + type: string + version: + _description: >- + The version of the event type. This field is required by the recipient + of the event to interpret the contents. Please see + [Versioning](../eiffel-syntax-and-usage/versioning.md) for more + information. + _format: '[Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html)' + type: string + time: + _description: The event creation timestamp. + _format: UNIX Epoch time, in milliseconds. + type: integer + tags: + _description: >- + Any tags or keywords associated with the events, for searchability + purposes. + _format: Free text + type: array + items: + type: string + source: + _description: >- + A description of the source of the event. This object is primarily for + traceability purposes, and while optional, some form of identification + of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of + identifying the source of the event, techniques which may be select from + based on the technology domain and needs in any particular use case. + type: object + properties: + domainId: + _description: >- + Identifies the + [domain](../eiffel-syntax-and-usage/glossary.md#domain) that + produced an event. + _format: Free text + type: string + host: + _description: The hostname of the event sender. + _format: Hostname + type: string + name: + _description: The name of the event sender. + _format: Free text + type: string + serializer: + _description: >- + The identity of the serializer software used to construct the event, + in [purl format](https://github.com/package-url/purl-spec). + _format: >- + [purl specification](https://github.com/package-url/purl-spec) + type: string + pattern: '^pkg:' + uri: + _description: The URI of, related to or describing the event sender. + _format: URI + type: string + additionalProperties: false + security: + _description: >- + An optional object for enclosing security related information, + particularly supporting data integrity. See + [Security](../eiffel-syntax-and-usage/security.md) for further + information. + type: object + properties: + sdm: + type: object + properties: + authorIdentity: + type: string + encryptedDigest: + type: string + required: + - authorIdentity + - encryptedDigest + additionalProperties: false + additionalProperties: false +required: + - id + - type + - version + - time +additionalProperties: false diff --git a/definitions/EiffelMetaProperty/3.0.0.yml b/definitions/EiffelMetaProperty/3.0.0.yml new file mode 100644 index 00000000..7c366205 --- /dev/null +++ b/definitions/EiffelMetaProperty/3.0.0.yml @@ -0,0 +1,201 @@ +# 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# +type: object +properties: + id: + _description: >- + The unique identity of the event, generated at event creation. + _format: '[UUID](http://tools.ietf.org/html/rfc4122)' + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + type: + _description: >- + The type of event. This field is required by the recipient of + the event, as each event type has a specific meaning and a specific + set of members in the __data__ and __links__ objects. + _format: An event type name + type: string + version: + _description: >- + The version of the event type. This field is required by the recipient + of the event to interpret the contents. Please see + [Versioning](../eiffel-syntax-and-usage/versioning.md) for more + information. + _format: '[Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html)' + type: string + time: + _description: The event creation timestamp. + _format: UNIX Epoch time, in milliseconds. + type: integer + tags: + _description: >- + Any tags or keywords associated with the events, for searchability + purposes. + _format: Free text + type: array + items: + type: string + source: + _description: >- + A description of the source of the event. This object is primarily for + traceability purposes, and while optional, some form of identification + of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of + identifying the source of the event, techniques which may be select from + based on the technology domain and needs in any particular use case. + type: object + properties: + domainId: + _description: >- + Identifies the + [domain](../eiffel-syntax-and-usage/glossary.md#domain) that + produced an event. + _format: Free text + type: string + host: + _description: The hostname of the event sender. + _format: Hostname + type: string + name: + _description: The name of the event sender. + _format: Free text + type: string + serializer: + _description: >- + The identity of the serializer software used to construct the event, + in [purl format](https://github.com/package-url/purl-spec). + _format: >- + [purl specification](https://github.com/package-url/purl-spec) + type: string + pattern: '^pkg:' + uri: + _description: The URI of, related to or describing the event sender. + _format: URI + type: string + additionalProperties: false + security: + _description: >- + An optional object for enclosing security related information, + particularly supporting data integrity. See + [Security](../eiffel-syntax-and-usage/security.md) for further + information. + type: object + properties: + authorIdentity: + _description: >- + The identity of the author of the event. This property is intended + to enable the recipient to identify the author of the event contents + and/or look up the appropriate public key for decrypting the + __meta.security.integrityProtection.signature__ value and thereby + verifying author identity and data integrity. + _format: '[Distinguished Name](https://tools.ietf.org/html/rfc2253)' + type: string + integrityProtection: + _description: >- + An optional object for enabling information integrity protection via + cryptographic signing. To generate a correct + __meta.security.integrityProtection__ object: + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. + To verify the integrity of the event, the consumer then resets + __meta.security.integrityProtection.signature__ to an empty string + and ensures Canonical JSON Form before verifying the signature. + type: object + properties: + signature: + _description: The signature produced by the signing algorithm. + type: string + alg: + _description: >- + The cryptographic algorithm used to digitally sign the event. + If no signing is performed, the + __meta.security.integrityProtection__ SHALL be omitted rather + than setting __meta.security.integrityProtection.alg__ to "none". + _format: >- + [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), + excluding "none" + type: string + enum: + - HS256 + - HS384 + - HS512 + - RS256 + - RS384 + - RS512 + - ES256 + - ES384 + - ES512 + - PS256 + - PS384 + - PS512 + publicKey: + _description: >- + The producer of the event may include the relevant public key + for convenience, rather than relying a separate key distribution + mechanism. Note that this property, along with the rest of the + event, is encompassed by the integrity protection offered via + __meta.security.integrityProtection__. + type: string + required: + - signature + - alg + additionalProperties: false + sequenceProtection: + _description: >- + An optional object for enabling verification of intact event + sequences in a distributed environment, thereby protecting against + data loss, race conditions and replay attacks. It allows event + publishers to state the order in which they produce a certain set + of events. In other words, it cannot provide any global guarantees + as to event sequencing, but rather per-publisher guarantees. Every + object in the array represents a named sequence of which this event + forms a part. For every event including a given named sequence, + the publisher SHALL increment + __meta.security.sequenceProtection.position__ by 1. The first event + produced in a given named sequence SHALL numbered 1. + type: array + items: + type: object + properties: + sequenceName: + _description: >- + The name of the sequence. There MUST not be two identical + __meta.security.sequenceProtection.sequenceName__ values in + the same event. + type: string + position: + _description: The number of the event within the named sequence. + type: integer + additionalProperties: false + required: + - sequenceName + - position + additionalProperties: false + required: + - authorIdentity +required: + - id + - type + - version + - time +additionalProperties: false diff --git a/definitions/EiffelSourceChangeCreatedEvent/1.0.0.yml b/definitions/EiffelSourceChangeCreatedEvent/1.0.0.yml new file mode 100644 index 00000000..1866219a --- /dev/null +++ b/definitions/EiffelSourceChangeCreatedEvent/1.0.0.yml @@ -0,0 +1,275 @@ +# 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: SCC +_description: |- + The EiffelSourceChangeCreatedEvent declares that a change to sources has been made, but not yet submitted (see [EiffelSourceChangeSubmittedEvent](./EiffelSourceChangeSubmittedEvent.md)). This can be used to represent a change done on a private branch, undergoing review or made in a forked repository. Unlike EiffelSourceChangeSubmittedEvent, EiffelSourceChangeCreatedEvent _describes the change_ in terms of who authored it and which issues it addressed. + + Where changes are integrated (or "submitted") directly on a shared branch of interest (e.g. "master", "dev" or "mainline") both EiffelSourceChangeCreatedEvent and EiffelSourceChangeSubmittedEvent are sent together. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + author: + _description: The author of the change. + type: object + properties: + name: + _description: The name of the author. + type: string + email: + _description: The email address of the author. + type: string + id: + _description: Any identity, username or alias of the author. + type: string + group: + _description: Any group or organization to which the contributor + belongs. + type: string + additionalProperties: false + change: + _description: A summary of the change. + type: object + properties: + insertions: + _description: The number of inserted lines in the change. + type: integer + deletions: + _description: The number of deleted lines in the change. + type: integer + files: + _description: A URI to a list of files changed, on JSON + String array format. + type: string + details: + _description: A URI to further details about the change. + These details are not assumed to be on any standardized + format, and may be intended for human and/or machine + consumption. Examples include e.g. Gerrit patch set descriptions + or GitHub commit pages. It is recommended to also include + __data.change.tracker__ to provide a hint as to the nature + of the linked details. + type: string + tracker: + _description: The name of the tracker, if any, of the change. + Examples include e.g. Gerrit or GitHub. + type: string + id: + _description: The unique identity, if any, of the change + (apart from what is expressed in the identifier object). + Examples include e.g. Gerrit Change-Ids or GitHub Pull + Requests. It is recommended to also include __data.change.tracker__ + to provide a hint as to the nature of the identity. + type: string + additionalProperties: false + issues: + _description: A list of issues addressed by the change. + type: array + items: + properties: + type: + type: string + enum: + - BUG + - IMPROVEMENT + - FEATURE + - WORK_ITEM + - REQUIREMENT + - OTHER + tracker: + type: string + id: + type: string + uri: + type: string + transition: + type: string + enum: + - RESOLVED + - PARTIAL + - REMOVED + required: + - type + - tracker + - id + - uri + - transition + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + 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 +additionalProperties: false +_links: + BASE: + description: Identifies the base revision of the created source + change. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the created source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelSourceChangeCreatedEvent/simple.json diff --git a/definitions/EiffelSourceChangeCreatedEvent/1.1.0.yml b/definitions/EiffelSourceChangeCreatedEvent/1.1.0.yml new file mode 100644 index 00000000..0545394d --- /dev/null +++ b/definitions/EiffelSourceChangeCreatedEvent/1.1.0.yml @@ -0,0 +1,278 @@ +# 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: SCC +_description: |- + The EiffelSourceChangeCreatedEvent declares that a change to sources has been made, but not yet submitted (see [EiffelSourceChangeSubmittedEvent](./EiffelSourceChangeSubmittedEvent.md)). This can be used to represent a change done on a private branch, undergoing review or made in a forked repository. Unlike EiffelSourceChangeSubmittedEvent, EiffelSourceChangeCreatedEvent _describes the change_ in terms of who authored it and which issues it addressed. + + Where changes are integrated (or "submitted") directly on a shared branch of interest (e.g. "master", "dev" or "mainline") both EiffelSourceChangeCreatedEvent and EiffelSourceChangeSubmittedEvent are sent together. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + author: + _description: The author of the change. + type: object + properties: + name: + _description: The name of the author. + type: string + email: + _description: The email address of the author. + type: string + id: + _description: Any identity, username or alias of the author. + type: string + group: + _description: Any group or organization to which the contributor + belongs. + type: string + additionalProperties: false + change: + _description: A summary of the change. + type: object + properties: + insertions: + _description: The number of inserted lines in the change. + type: integer + deletions: + _description: The number of deleted lines in the change. + type: integer + files: + _description: A URI to a list of files changed, on JSON + String array format. + type: string + details: + _description: A URI to further details about the change. + These details are not assumed to be on any standardized + format, and may be intended for human and/or machine + consumption. Examples include e.g. Gerrit patch set descriptions + or GitHub commit pages. It is recommended to also include + __data.change.tracker__ to provide a hint as to the nature + of the linked details. + type: string + tracker: + _description: The name of the tracker, if any, of the change. + Examples include e.g. Gerrit or GitHub. + type: string + id: + _description: The unique identity, if any, of the change + (apart from what is expressed in the identifier object). + Examples include e.g. Gerrit Change-Ids or GitHub Pull + Requests. It is recommended to also include __data.change.tracker__ + to provide a hint as to the nature of the identity. + type: string + additionalProperties: false + issues: + _description: A list of issues addressed by the change. + type: array + items: + properties: + type: + type: string + enum: + - BUG + - IMPROVEMENT + - FEATURE + - WORK_ITEM + - REQUIREMENT + - OTHER + tracker: + type: string + id: + type: string + uri: + type: string + transition: + type: string + enum: + - RESOLVED + - PARTIAL + - REMOVED + required: + - type + - tracker + - id + - uri + - transition + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + 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 +additionalProperties: false +_links: + BASE: + description: Identifies the base revision of the created source + change. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the created source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent +_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/EiffelSourceChangeCreatedEvent/simple.json diff --git a/definitions/EiffelSourceChangeCreatedEvent/2.0.0.yml b/definitions/EiffelSourceChangeCreatedEvent/2.0.0.yml new file mode 100644 index 00000000..833fb324 --- /dev/null +++ b/definitions/EiffelSourceChangeCreatedEvent/2.0.0.yml @@ -0,0 +1,283 @@ +# 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: SCC +_description: |- + The EiffelSourceChangeCreatedEvent declares that a change to sources has been made, but not yet submitted (see [EiffelSourceChangeSubmittedEvent](./EiffelSourceChangeSubmittedEvent.md)). This can be used to represent a change done on a private branch, undergoing review or made in a forked repository. Unlike EiffelSourceChangeSubmittedEvent, EiffelSourceChangeCreatedEvent _describes the change_ in terms of who authored it and which issues it addressed. + + Where changes are integrated (or "submitted") directly on a shared branch of interest (e.g. "master", "dev" or "mainline") both EiffelSourceChangeCreatedEvent and EiffelSourceChangeSubmittedEvent are sent together. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + author: + _description: The author of the change. + type: object + properties: + name: + _description: The name of the author. + type: string + email: + _description: The email address of the author. + type: string + id: + _description: Any identity, username or alias of the author. + type: string + group: + _description: Any group or organization to which the contributor + belongs. + type: string + additionalProperties: false + change: + _description: A summary of the change. + type: object + properties: + insertions: + _description: The number of inserted lines in the change. + type: integer + deletions: + _description: The number of deleted lines in the change. + type: integer + files: + _description: A URI to a list of files changed, on JSON + String array format. + type: string + details: + _description: A URI to further details about the change. + These details are not assumed to be on any standardized + format, and may be intended for human and/or machine + consumption. Examples include e.g. Gerrit patch set descriptions + or GitHub commit pages. It is recommended to also include + __data.change.tracker__ to provide a hint as to the nature + of the linked details. + type: string + tracker: + _description: The name of the tracker, if any, of the change. + Examples include e.g. Gerrit or GitHub. + type: string + id: + _description: The unique identity, if any, of the change + (apart from what is expressed in the identifier object). + Examples include e.g. Gerrit Change-Ids or GitHub Pull + Requests. It is recommended to also include __data.change.tracker__ + to provide a hint as to the nature of the identity. + type: string + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + 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 +additionalProperties: false +_links: + BASE: + description: Identifies the base revision of the created source + change. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + DERESOLVED_ISSUE: + description: Identifies an issue which was previously resolved, + but that this SCC claims it has made changes to warrant removing + the resolved status. For example, if an issue "Feature X" was + resolved, but this SCC removed the implmentation that led to + "Feature X" being resolved, that issue should no longer be considered + resolved. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + 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 + PARTIALLY_RESOLVED_ISSUE: + description: Identifies an issue that this event partially resolves. + That is, this SCC introduces some change that has advanced an + issue towards a resolved state, but not completely resolved. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the created source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent + RESOLVED_ISSUE: + description: Identifies an issue that this SCC is claiming it has + done enough to resolve. This is not an authoritative resolution, + only a claim. The issue may or may not change status as a consequence + this, e.g. through a [successful verification](../eiffel-vocabular/EiffelIssueVerifiedEvent.md) + or a manual update on the issue tracker. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Replaced data.issues with links + - 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/EiffelSourceChangeCreatedEvent/simple.json diff --git a/definitions/EiffelSourceChangeCreatedEvent/3.0.0.yml b/definitions/EiffelSourceChangeCreatedEvent/3.0.0.yml new file mode 100644 index 00000000..5ec6c121 --- /dev/null +++ b/definitions/EiffelSourceChangeCreatedEvent/3.0.0.yml @@ -0,0 +1,287 @@ +# 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: SCC +_description: |- + The EiffelSourceChangeCreatedEvent declares that a change to sources has been made, but not yet submitted (see [EiffelSourceChangeSubmittedEvent](./EiffelSourceChangeSubmittedEvent.md)). This can be used to represent a change done on a private branch, undergoing review or made in a forked repository. Unlike EiffelSourceChangeSubmittedEvent, EiffelSourceChangeCreatedEvent _describes the change_ in terms of who authored it and which issues it addressed. + + Where changes are integrated (or "submitted") directly on a shared branch of interest (e.g. "master", "dev" or "mainline") both EiffelSourceChangeCreatedEvent and EiffelSourceChangeSubmittedEvent are sent together. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + author: + _description: The author of the change. + type: object + properties: + name: + _description: The name of the author. + type: string + email: + _description: The email address of the author. + type: string + id: + _description: Any identity, username or alias of the author. + type: string + group: + _description: Any group or organization to which the contributor + belongs. + type: string + additionalProperties: false + change: + _description: A summary of the change. + type: object + properties: + insertions: + _description: The number of inserted lines in the change. + type: integer + deletions: + _description: The number of deleted lines in the change. + type: integer + files: + _description: A URI to a list of files changed, on JSON + String array format. + type: string + details: + _description: A URI to further details about the change. + These details are not assumed to be on any standardized + format, and may be intended for human and/or machine + consumption. Examples include e.g. Gerrit patch set descriptions + or GitHub commit pages. It is recommended to also include + __data.change.tracker__ to provide a hint as to the nature + of the linked details. + type: string + tracker: + _description: The name of the tracker, if any, of the change. + Examples include e.g. Gerrit or GitHub. + type: string + id: + _description: The unique identity, if any, of the change + (apart from what is expressed in the identifier object). + Examples include e.g. Gerrit Change-Ids or GitHub Pull + Requests. It is recommended to also include __data.change.tracker__ + to provide a hint as to the nature of the identity. + type: string + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + 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 +additionalProperties: false +_links: + BASE: + description: Identifies the base revision of the created source + change. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + DERESOLVED_ISSUE: + description: Identifies an issue which was previously resolved, + but that this SCC claims it has made changes to warrant removing + the resolved status. For example, if an issue "Feature X" was + resolved, but this SCC removed the implmentation that led to + "Feature X" being resolved, that issue should no longer be considered + resolved. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + 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 + PARTIALLY_RESOLVED_ISSUE: + description: Identifies an issue that this event partially resolves. + That is, this SCC introduces some change that has advanced an + issue towards a resolved state, but not completely resolved. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the created source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent + RESOLVED_ISSUE: + description: Identifies an issue that this SCC is claiming it has + done enough to resolve. This is not an authoritative resolution, + only a claim. The issue may or may not change status as a consequence + this, e.g. through a [successful verification](../eiffel-vocabular/EiffelIssueVerifiedEvent.md) + or a manual update on the issue tracker. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent +_history: + - version: 3.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.0.0 + introduced_in: '[0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)' + changes: Replaced data.issues with links + - 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/EiffelSourceChangeCreatedEvent/simple.json diff --git a/definitions/EiffelSourceChangeCreatedEvent/4.0.0.yml b/definitions/EiffelSourceChangeCreatedEvent/4.0.0.yml new file mode 100644 index 00000000..6afaa93d --- /dev/null +++ b/definitions/EiffelSourceChangeCreatedEvent/4.0.0.yml @@ -0,0 +1,290 @@ +# 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: SCC +_description: |- + The EiffelSourceChangeCreatedEvent declares that a change to sources has been made, but not yet submitted (see [EiffelSourceChangeSubmittedEvent](./EiffelSourceChangeSubmittedEvent.md)). This can be used to represent a change done on a private branch, undergoing review or made in a forked repository. Unlike EiffelSourceChangeSubmittedEvent, EiffelSourceChangeCreatedEvent _describes the change_ in terms of who authored it and which issues it addressed. + + Where changes are integrated (or "submitted") directly on a shared branch of interest (e.g. "master", "dev" or "mainline") both EiffelSourceChangeCreatedEvent and EiffelSourceChangeSubmittedEvent are sent together. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + author: + _description: The author of the change. + type: object + properties: + name: + _description: The name of the author. + type: string + email: + _description: The email address of the author. + type: string + id: + _description: Any identity, username or alias of the author. + type: string + group: + _description: Any group or organization to which the contributor + belongs. + type: string + additionalProperties: false + change: + _description: A summary of the change. + type: object + properties: + insertions: + _description: The number of inserted lines in the change. + type: integer + deletions: + _description: The number of deleted lines in the change. + type: integer + files: + _description: A URI to a list of files changed, on JSON + String array format. + type: string + details: + _description: A URI to further details about the change. + These details are not assumed to be on any standardized + format, and may be intended for human and/or machine + consumption. Examples include e.g. Gerrit patch set descriptions + or GitHub commit pages. It is recommended to also include + __data.change.tracker__ to provide a hint as to the nature + of the linked details. + type: string + tracker: + _description: The name of the tracker, if any, of the change. + Examples include e.g. Gerrit or GitHub. + type: string + id: + _description: The unique identity, if any, of the change + (apart from what is expressed in the identifier object). + Examples include e.g. Gerrit Change-Ids or GitHub Pull + Requests. It is recommended to also include __data.change.tracker__ + to provide a hint as to the nature of the identity. + type: string + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + 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 +additionalProperties: false +_links: + BASE: + description: Identifies the base revision of the created source + change. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + DERESOLVED_ISSUE: + description: Identifies an issue which was previously resolved, + but that this SCC claims it has made changes to warrant removing + the resolved status. For example, if an issue "Feature X" was + resolved, but this SCC removed the implmentation that led to + "Feature X" being resolved, that issue should no longer be considered + resolved. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + 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 + PARTIALLY_RESOLVED_ISSUE: + description: Identifies an issue that this event partially resolves. + That is, this SCC introduces some change that has advanced an + issue towards a resolved state, but not completely resolved. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the created source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent + RESOLVED_ISSUE: + description: Identifies an issue that this SCC is claiming it has + done enough to resolve. This is not an authoritative resolution, + only a claim. The issue may or may not change status as a consequence + this, e.g. through a [successful verification](../eiffel-vocabular/EiffelIssueVerifiedEvent.md) + or a manual update on the issue tracker. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent +_history: + - version: 4.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 3.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.0.0 + introduced_in: '[0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)' + changes: Replaced data.issues with links + - 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/EiffelSourceChangeCreatedEvent/simple.json diff --git a/definitions/EiffelSourceChangeCreatedEvent/4.1.0.yml b/definitions/EiffelSourceChangeCreatedEvent/4.1.0.yml new file mode 100644 index 00000000..07c74daf --- /dev/null +++ b/definitions/EiffelSourceChangeCreatedEvent/4.1.0.yml @@ -0,0 +1,294 @@ +# 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: SCC +_description: |- + The EiffelSourceChangeCreatedEvent declares that a change to sources has been made, but not yet submitted (see [EiffelSourceChangeSubmittedEvent](./EiffelSourceChangeSubmittedEvent.md)). This can be used to represent a change done on a private branch, undergoing review or made in a forked repository. Unlike EiffelSourceChangeSubmittedEvent, EiffelSourceChangeCreatedEvent _describes the change_ in terms of who authored it and which issues it addressed. + + Where changes are integrated (or "submitted") directly on a shared branch of interest (e.g. "master", "dev" or "mainline") both EiffelSourceChangeCreatedEvent and EiffelSourceChangeSubmittedEvent are sent together. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + author: + _description: The author of the change. + type: object + properties: + name: + _description: The name of the author. + type: string + email: + _description: The email address of the author. + type: string + id: + _description: Any identity, username or alias of the author. + type: string + group: + _description: Any group or organization to which the contributor + belongs. + type: string + additionalProperties: false + change: + _description: A summary of the change. + type: object + properties: + insertions: + _description: The number of inserted lines in the change. + type: integer + deletions: + _description: The number of deleted lines in the change. + type: integer + files: + _description: A URI to a list of files changed, on JSON + String array format. + type: string + details: + _description: A URI to further details about the change. + These details are not assumed to be on any standardized + format, and may be intended for human and/or machine + consumption. Examples include e.g. Gerrit patch set descriptions + or GitHub commit pages. It is recommended to also include + __data.change.tracker__ to provide a hint as to the nature + of the linked details. + type: string + tracker: + _description: The name of the tracker, if any, of the change. + Examples include e.g. Gerrit or GitHub. + type: string + id: + _description: The unique identity, if any, of the change + (apart from what is expressed in the identifier object). + Examples include e.g. Gerrit Change-Ids or GitHub Pull + Requests. It is recommended to also include __data.change.tracker__ + to provide a hint as to the nature of the identity. + type: string + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + BASE: + description: Identifies the base revision of the created source + change. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + DERESOLVED_ISSUE: + description: Identifies an issue which was previously resolved, + but that this SCC claims it has made changes to warrant removing + the resolved status. For example, if an issue "Feature X" was + resolved, but this SCC removed the implmentation that led to + "Feature X" being resolved, that issue should no longer be considered + resolved. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + 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 + PARTIALLY_RESOLVED_ISSUE: + description: Identifies an issue that this event partially resolves. + That is, this SCC introduces some change that has advanced an + issue towards a resolved state, but not completely resolved. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the created source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent + RESOLVED_ISSUE: + description: Identifies an issue that this SCC is claiming it has + done enough to resolve. This is not an authoritative resolution, + only a claim. The issue may or may not change status as a consequence + this, e.g. through a [successful verification](../eiffel-vocabular/EiffelIssueVerifiedEvent.md) + or a manual update on the issue tracker. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelIssueDefinedEvent +_history: + - version: 4.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 4.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 3.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.0.0 + introduced_in: '[0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)' + changes: Replaced data.issues with links + - 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/EiffelSourceChangeCreatedEvent/simple.json diff --git a/definitions/EiffelSourceChangeSubmittedEvent/1.0.0.yml b/definitions/EiffelSourceChangeSubmittedEvent/1.0.0.yml new file mode 100644 index 00000000..4e3ae520 --- /dev/null +++ b/definitions/EiffelSourceChangeSubmittedEvent/1.0.0.yml @@ -0,0 +1,210 @@ +# 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: SCS +_description: |- + The EiffelSourceChangeSubmittedEvent declares that a change has been integrated into to a shared source branch of interest (e.g. "master", "dev" or "mainline") as opposed to a private or local branch. Note that it does not describe what has changed, but instead uses the __CHANGE__ link type to reference [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + + Typical use cases for EiffelSourceChangeSubmittedEvent is to signal that a patch has passed code review and been submitted or that a feature/topic/team branch has been merged into the mainline/trunk/master. Where changes are made directly on the mainline, it is recommended to send both [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md) and EiffelSourceChangeSubmittedEvent together for information completeness. + + Even though multiple types of identifiers are available (see below), the event SHOULD include one and SHALL not include more than one; changes to multiple repositories are represented by multiple events. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + submitter: + _description: The agent (individual, group or machine) submitting + the change. This is crucially different from the __data.author__ + field of [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + type: object + properties: + name: + _description: The name of the submitter. + type: string + email: + _description: The email address of the submitter. + type: string + id: + _description: Any identity, username or alias of the submitter. + type: string + group: + _description: Any group or organization to which the submitter + belongs. + type: string + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + CHANGE: + description: Identifies the change that was submitted. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the submitted source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelSourceChangeSubmittedEvent/simple.json diff --git a/definitions/EiffelSourceChangeSubmittedEvent/1.1.0.yml b/definitions/EiffelSourceChangeSubmittedEvent/1.1.0.yml new file mode 100644 index 00000000..bff387eb --- /dev/null +++ b/definitions/EiffelSourceChangeSubmittedEvent/1.1.0.yml @@ -0,0 +1,213 @@ +# 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: SCS +_description: |- + The EiffelSourceChangeSubmittedEvent declares that a change has been integrated into to a shared source branch of interest (e.g. "master", "dev" or "mainline") as opposed to a private or local branch. Note that it does not describe what has changed, but instead uses the __CHANGE__ link type to reference [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + + Typical use cases for EiffelSourceChangeSubmittedEvent is to signal that a patch has passed code review and been submitted or that a feature/topic/team branch has been merged into the mainline/trunk/master. Where changes are made directly on the mainline, it is recommended to send both [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md) and EiffelSourceChangeSubmittedEvent together for information completeness. + + Even though multiple types of identifiers are available (see below), the event SHOULD include one and SHALL not include more than one; changes to multiple repositories are represented by multiple events. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + submitter: + _description: The agent (individual, group or machine) submitting + the change. This is crucially different from the __data.author__ + field of [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + type: object + properties: + name: + _description: The name of the submitter. + type: string + email: + _description: The email address of the submitter. + type: string + id: + _description: Any identity, username or alias of the submitter. + type: string + group: + _description: Any group or organization to which the submitter + belongs. + type: string + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + CHANGE: + description: Identifies the change that was submitted. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the submitted source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent +_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/EiffelSourceChangeSubmittedEvent/simple.json diff --git a/definitions/EiffelSourceChangeSubmittedEvent/2.0.0.yml b/definitions/EiffelSourceChangeSubmittedEvent/2.0.0.yml new file mode 100644 index 00000000..aa6f2aab --- /dev/null +++ b/definitions/EiffelSourceChangeSubmittedEvent/2.0.0.yml @@ -0,0 +1,217 @@ +# 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: SCS +_description: |- + The EiffelSourceChangeSubmittedEvent declares that a change has been integrated into to a shared source branch of interest (e.g. "master", "dev" or "mainline") as opposed to a private or local branch. Note that it does not describe what has changed, but instead uses the __CHANGE__ link type to reference [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + + Typical use cases for EiffelSourceChangeSubmittedEvent is to signal that a patch has passed code review and been submitted or that a feature/topic/team branch has been merged into the mainline/trunk/master. Where changes are made directly on the mainline, it is recommended to send both [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md) and EiffelSourceChangeSubmittedEvent together for information completeness. + + Even though multiple types of identifiers are available (see below), the event SHOULD include one and SHALL not include more than one; changes to multiple repositories are represented by multiple events. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + submitter: + _description: The agent (individual, group or machine) submitting + the change. This is crucially different from the __data.author__ + field of [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + type: object + properties: + name: + _description: The name of the submitter. + type: string + email: + _description: The email address of the submitter. + type: string + id: + _description: Any identity, username or alias of the submitter. + type: string + group: + _description: Any group or organization to which the submitter + belongs. + type: string + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + CHANGE: + description: Identifies the change that was submitted. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the submitted source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelSourceChangeSubmittedEvent/simple.json diff --git a/definitions/EiffelSourceChangeSubmittedEvent/3.0.0.yml b/definitions/EiffelSourceChangeSubmittedEvent/3.0.0.yml new file mode 100644 index 00000000..aecc19e4 --- /dev/null +++ b/definitions/EiffelSourceChangeSubmittedEvent/3.0.0.yml @@ -0,0 +1,220 @@ +# 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: SCS +_description: |- + The EiffelSourceChangeSubmittedEvent declares that a change has been integrated into to a shared source branch of interest (e.g. "master", "dev" or "mainline") as opposed to a private or local branch. Note that it does not describe what has changed, but instead uses the __CHANGE__ link type to reference [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + + Typical use cases for EiffelSourceChangeSubmittedEvent is to signal that a patch has passed code review and been submitted or that a feature/topic/team branch has been merged into the mainline/trunk/master. Where changes are made directly on the mainline, it is recommended to send both [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md) and EiffelSourceChangeSubmittedEvent together for information completeness. + + Even though multiple types of identifiers are available (see below), the event SHOULD include one and SHALL not include more than one; changes to multiple repositories are represented by multiple events. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + submitter: + _description: The agent (individual, group or machine) submitting + the change. This is crucially different from the __data.author__ + field of [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + type: object + properties: + name: + _description: The name of the submitter. + type: string + email: + _description: The email address of the submitter. + type: string + id: + _description: Any identity, username or alias of the submitter. + type: string + group: + _description: Any group or organization to which the submitter + belongs. + type: string + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + CHANGE: + description: Identifies the change that was submitted. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the submitted source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelSourceChangeSubmittedEvent/simple.json diff --git a/definitions/EiffelSourceChangeSubmittedEvent/3.1.0.yml b/definitions/EiffelSourceChangeSubmittedEvent/3.1.0.yml new file mode 100644 index 00000000..15329287 --- /dev/null +++ b/definitions/EiffelSourceChangeSubmittedEvent/3.1.0.yml @@ -0,0 +1,224 @@ +# 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: SCS +_description: |- + The EiffelSourceChangeSubmittedEvent declares that a change has been integrated into to a shared source branch of interest (e.g. "master", "dev" or "mainline") as opposed to a private or local branch. Note that it does not describe what has changed, but instead uses the __CHANGE__ link type to reference [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + + Typical use cases for EiffelSourceChangeSubmittedEvent is to signal that a patch has passed code review and been submitted or that a feature/topic/team branch has been merged into the mainline/trunk/master. Where changes are made directly on the mainline, it is recommended to send both [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md) and EiffelSourceChangeSubmittedEvent together for information completeness. + + Even though multiple types of identifiers are available (see below), the event SHOULD include one and SHALL not include more than one; changes to multiple repositories are represented by multiple events. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + submitter: + _description: The agent (individual, group or machine) submitting + the change. This is crucially different from the __data.author__ + field of [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md). + type: object + properties: + name: + _description: The name of the submitter. + type: string + email: + _description: The email address of the submitter. + type: string + id: + _description: Any identity, username or alias of the submitter. + type: string + group: + _description: Any group or organization to which the submitter + belongs. + type: string + additionalProperties: false + gitIdentifier: + _description: Identifier of a Git change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The name of the branch where the change was + made. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - commitId + - repoUri + additionalProperties: false + svnIdentifier: + _description: Identifier of a Subversion change. + type: object + properties: + revision: + _description: The revision of the change. + type: integer + directory: + _description: The directory (branch/tag) of the change. + type: string + repoName: + _description: The name of the repository containing the + change. + type: string + repoUri: + _description: The URI of the repository containing the + change. + type: string + required: + - revision + - directory + - repoUri + additionalProperties: false + ccCompositeIdentifier: + _description: Identifier of a composite ClearCase change – + in other words, not single file commit, but analogous of + repository-wide commits of e.g. SVN or Git. + type: object + properties: + vobs: + _description: The names of the changed ClearCase VOBs. + type: array + items: + type: string + branch: + _description: The branch of the change. + type: string + configSpec: + _description: The URI of the relevant ClearCase config + spec. + type: string + required: + - vobs + - branch + - configSpec + additionalProperties: false + hgIdentifier: + _description: Identifier of a Mercurial change. + type: object + properties: + commitId: + _description: The commit identity (hash) of the change. + type: string + branch: + _description: The branch of the change. + type: string + repoName: + _description: The name of the repo. + type: string + repoUri: + _description: The URI of the repo. + type: string + required: + - commitId + - repoUri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + required: false + multiple: true + targets: + any_type: true + types: [] + CHANGE: + description: Identifies the change that was submitted. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelSourceChangeCreatedEvent + 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 + PREVIOUS_VERSION: + description: Identifies a latest previous version (there may be + more than one in case of merges) of the submitted source change. + required: false + multiple: true + targets: + any_type: false + types: + - EiffelSourceChangeSubmittedEvent +_history: + - version: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelSourceChangeSubmittedEvent/simple.json diff --git a/definitions/EiffelTestCaseCanceledEvent/1.0.0.yml b/definitions/EiffelTestCaseCanceledEvent/1.0.0.yml new file mode 100644 index 00000000..0ab62c07 --- /dev/null +++ b/definitions/EiffelTestCaseCanceledEvent/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: TCC +_description: The EiffelTestCaseCanceledEvent declares that a previously + triggered test case execution (represented by [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md)) + 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 +additionalProperties: false +_links: + CAUSE: + description: While for most events it is recommended that __CAUSE__ + SHOULD not be used in conjunction with __CONTEXT__, EiffelTestCaseCanceledEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestCaseCanceledEvent/simple.json diff --git a/definitions/EiffelTestCaseCanceledEvent/1.1.0.yml b/definitions/EiffelTestCaseCanceledEvent/1.1.0.yml new file mode 100644 index 00000000..6b47df1f --- /dev/null +++ b/definitions/EiffelTestCaseCanceledEvent/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: TCC +_description: The EiffelTestCaseCanceledEvent declares that a previously + triggered test case execution (represented by [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md)) + 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 +additionalProperties: false +_links: + CAUSE: + description: While for most events it is recommended that __CAUSE__ + SHOULD not be used in conjunction with __CONTEXT__, EiffelTestCaseCanceledEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_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/EiffelTestCaseCanceledEvent/simple.json diff --git a/definitions/EiffelTestCaseCanceledEvent/2.0.0.yml b/definitions/EiffelTestCaseCanceledEvent/2.0.0.yml new file mode 100644 index 00000000..cc97816e --- /dev/null +++ b/definitions/EiffelTestCaseCanceledEvent/2.0.0.yml @@ -0,0 +1,109 @@ +# 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: TCC +_description: The EiffelTestCaseCanceledEvent declares that a previously + triggered test case execution (represented by [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md)) + 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/2.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 +additionalProperties: false +_links: + CAUSE: + description: While for most events it is recommended that __CAUSE__ + SHOULD not be used in conjunction with __CONTEXT__, EiffelTestCaseCanceledEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseCanceledEvent/simple.json diff --git a/definitions/EiffelTestCaseCanceledEvent/3.0.0.yml b/definitions/EiffelTestCaseCanceledEvent/3.0.0.yml new file mode 100644 index 00000000..f741484a --- /dev/null +++ b/definitions/EiffelTestCaseCanceledEvent/3.0.0.yml @@ -0,0 +1,112 @@ +# 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: TCC +_description: The EiffelTestCaseCanceledEvent declares that a previously + triggered test case execution (represented by [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md)) + 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/3.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 +additionalProperties: false +_links: + CAUSE: + description: While for most events it is recommended that __CAUSE__ + SHOULD not be used in conjunction with __CONTEXT__, EiffelTestCaseCanceledEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseCanceledEvent/simple.json diff --git a/definitions/EiffelTestCaseCanceledEvent/3.1.0.yml b/definitions/EiffelTestCaseCanceledEvent/3.1.0.yml new file mode 100644 index 00000000..9122780b --- /dev/null +++ b/definitions/EiffelTestCaseCanceledEvent/3.1.0.yml @@ -0,0 +1,116 @@ +# 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: TCC +_description: The EiffelTestCaseCanceledEvent declares that a previously + triggered test case execution (represented by [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md)) + 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/3.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.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: While for most events it is recommended that __CAUSE__ + SHOULD not be used in conjunction with __CONTEXT__, EiffelTestCaseCanceledEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseCanceledEvent/simple.json diff --git a/definitions/EiffelTestCaseFinishedEvent/1.0.0.yml b/definitions/EiffelTestCaseFinishedEvent/1.0.0.yml new file mode 100644 index 00000000..fea19ac8 --- /dev/null +++ b/definitions/EiffelTestCaseFinishedEvent/1.0.0.yml @@ -0,0 +1,122 @@ +# 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: TCF +_description: |- + The EiffelTestCaseFinishedEvent declares that a previously started test case (declared by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test case reports not only the conclusion of the test case execution - whether the test case was successfully executed - but also passes a verdict on the item under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. + + Also note that unlike [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md), EiffelTestCaseFinishedEvent must report both __data.outcome.verdict__ and __data.outcome.conclusion__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test case. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. + PASSED signifies that the item or items under test successfully passed the test case. + FAILED signifies that the item or items under test failed to pass the test case. + INCONCLUSIVE signifies that the verdict of the test case was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test case, designed to be machine readable. + SUCCESSFUL signifies that the test case was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test case could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test case was aborted before it could be concluded. + TIMED_OUT signifies that the test case did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test case could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test case outcome, + designed to provide human readers with further information. + type: string + metrics: + _description: A list of metrics collected during the test + case execution. Note that while complete freedom is allowed + in metrics names and value types, it is highly recommended + to keep reported metrics concise and consistent. In other + words, do not include excessive amounts of data (use + __data.persistentLogs__ for that), and avoid unnecessary + variations in value names or types over time. + type: array + items: + type: object + properties: + name: + _description: The metrics name. + type: string + value: + _description: The metrics value. + additionalProperties: false + required: + - verdict + - conclusion + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - outcome + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: {} +_history: [] +_examples: [] diff --git a/definitions/EiffelTestCaseFinishedEvent/1.0.1.yml b/definitions/EiffelTestCaseFinishedEvent/1.0.1.yml new file mode 100644 index 00000000..6e364289 --- /dev/null +++ b/definitions/EiffelTestCaseFinishedEvent/1.0.1.yml @@ -0,0 +1,181 @@ +# 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: TCF +_description: |- + The EiffelTestCaseFinishedEvent declares that a previously started test case (declared by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test case reports not only the conclusion of the test case execution - whether the test case was successfully executed - but also passes a verdict on the item under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. + + Also note that unlike [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md), EiffelTestCaseFinishedEvent must report both __data.outcome.verdict__ and __data.outcome.conclusion__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test case. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. + PASSED signifies that the item or items under test successfully passed the test case. + FAILED signifies that the item or items under test failed to pass the test case. + INCONCLUSIVE signifies that the verdict of the test case was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test case, designed to be machine readable. + SUCCESSFUL signifies that the test case was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test case could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test case was aborted before it could be concluded. + TIMED_OUT signifies that the test case did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test case could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test case outcome, + designed to provide human readers with further information. + type: string + metrics: + _description: A list of metrics collected during the test + case execution. Note that while complete freedom is allowed + in metrics names and value types, it is highly recommended + to keep reported metrics concise and consistent. In other + words, do not include excessive amounts of data (use + __data.persistentLogs__ for that), and avoid unnecessary + variations in value names or types over time. + type: array + items: + type: object + properties: + name: + _description: The metrics name. + type: string + value: + _description: The metrics value. + required: + - name + - value + additionalProperties: false + required: + - verdict + - conclusion + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - outcome + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 1.0.1 + introduced_in: Current version + changes: data.outcome.metrics.value and data.outcome.metrics.name + made mandatory. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestCaseFinishedEvent/simple.json diff --git a/definitions/EiffelTestCaseFinishedEvent/1.1.0.yml b/definitions/EiffelTestCaseFinishedEvent/1.1.0.yml new file mode 100644 index 00000000..dd6d23e4 --- /dev/null +++ b/definitions/EiffelTestCaseFinishedEvent/1.1.0.yml @@ -0,0 +1,184 @@ +# 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: TCF +_description: |- + The EiffelTestCaseFinishedEvent declares that a previously started test case (declared by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test case reports not only the conclusion of the test case execution - whether the test case was successfully executed - but also passes a verdict on the item under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. + + Also note that unlike [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md), EiffelTestCaseFinishedEvent must report both __data.outcome.verdict__ and __data.outcome.conclusion__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test case. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. + PASSED signifies that the item or items under test successfully passed the test case. + FAILED signifies that the item or items under test failed to pass the test case. + INCONCLUSIVE signifies that the verdict of the test case was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test case, designed to be machine readable. + SUCCESSFUL signifies that the test case was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test case could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test case was aborted before it could be concluded. + TIMED_OUT signifies that the test case did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test case could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test case outcome, + designed to provide human readers with further information. + type: string + metrics: + _description: A list of metrics collected during the test + case execution. Note that while complete freedom is allowed + in metrics names and value types, it is highly recommended + to keep reported metrics concise and consistent. In other + words, do not include excessive amounts of data (use + __data.persistentLogs__ for that), and avoid unnecessary + variations in value names or types over time. + type: array + items: + type: object + properties: + name: + _description: The metrics name. + type: string + value: + _description: The metrics value. + required: + - name + - value + additionalProperties: false + required: + - verdict + - conclusion + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - outcome + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 1.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 1.0.1 + introduced_in: '[0a2f9ef](../../../blob/0a2f9ef139fe6ead2493e5deddf1337ffb3dd4af/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)' + changes: data.outcome.metrics.value and data.outcome.metrics.name + made mandatory. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestCaseFinishedEvent/simple.json diff --git a/definitions/EiffelTestCaseFinishedEvent/2.0.0.yml b/definitions/EiffelTestCaseFinishedEvent/2.0.0.yml new file mode 100644 index 00000000..d3a739da --- /dev/null +++ b/definitions/EiffelTestCaseFinishedEvent/2.0.0.yml @@ -0,0 +1,188 @@ +# 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: TCF +_description: |- + The EiffelTestCaseFinishedEvent declares that a previously started test case (declared by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test case reports not only the conclusion of the test case execution - whether the test case was successfully executed - but also passes a verdict on the item under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. + + Also note that unlike [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md), EiffelTestCaseFinishedEvent must report both __data.outcome.verdict__ and __data.outcome.conclusion__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test case. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. + PASSED signifies that the item or items under test successfully passed the test case. + FAILED signifies that the item or items under test failed to pass the test case. + INCONCLUSIVE signifies that the verdict of the test case was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test case, designed to be machine readable. + SUCCESSFUL signifies that the test case was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test case could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test case was aborted before it could be concluded. + TIMED_OUT signifies that the test case did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test case could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test case outcome, + designed to provide human readers with further information. + type: string + metrics: + _description: A list of metrics collected during the test + case execution. Note that while complete freedom is allowed + in metrics names and value types, it is highly recommended + to keep reported metrics concise and consistent. In other + words, do not include excessive amounts of data (use + __data.persistentLogs__ for that), and avoid unnecessary + variations in value names or types over time. + type: array + items: + type: object + properties: + name: + _description: The metrics name. + type: string + value: + _description: The metrics value. + required: + - name + - value + additionalProperties: false + required: + - verdict + - conclusion + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - outcome + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 1.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 1.0.1 + introduced_in: '[0a2f9ef](../../../blob/0a2f9ef139fe6ead2493e5deddf1337ffb3dd4af/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)' + changes: data.outcome.metrics.value and data.outcome.metrics.name + made mandatory. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestCaseFinishedEvent/simple.json diff --git a/definitions/EiffelTestCaseFinishedEvent/3.0.0.yml b/definitions/EiffelTestCaseFinishedEvent/3.0.0.yml new file mode 100644 index 00000000..11583087 --- /dev/null +++ b/definitions/EiffelTestCaseFinishedEvent/3.0.0.yml @@ -0,0 +1,191 @@ +# 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: TCF +_description: |- + The EiffelTestCaseFinishedEvent declares that a previously started test case (declared by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test case reports not only the conclusion of the test case execution - whether the test case was successfully executed - but also passes a verdict on the item under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. + + Also note that unlike [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md), EiffelTestCaseFinishedEvent must report both __data.outcome.verdict__ and __data.outcome.conclusion__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test case. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. + PASSED signifies that the item or items under test successfully passed the test case. + FAILED signifies that the item or items under test failed to pass the test case. + INCONCLUSIVE signifies that the verdict of the test case was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test case, designed to be machine readable. + SUCCESSFUL signifies that the test case was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test case could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test case was aborted before it could be concluded. + TIMED_OUT signifies that the test case did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test case could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test case outcome, + designed to provide human readers with further information. + type: string + metrics: + _description: A list of metrics collected during the test + case execution. Note that while complete freedom is allowed + in metrics names and value types, it is highly recommended + to keep reported metrics concise and consistent. In other + words, do not include excessive amounts of data (use + __data.persistentLogs__ for that), and avoid unnecessary + variations in value names or types over time. + type: array + items: + type: object + properties: + name: + _description: The metrics name. + type: string + value: + _description: The metrics value. + required: + - name + - value + additionalProperties: false + required: + - verdict + - conclusion + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - outcome + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 1.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 1.0.1 + introduced_in: '[0a2f9ef](../../../blob/0a2f9ef139fe6ead2493e5deddf1337ffb3dd4af/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)' + changes: data.outcome.metrics.value and data.outcome.metrics.name + made mandatory. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestCaseFinishedEvent/simple.json diff --git a/definitions/EiffelTestCaseFinishedEvent/3.1.0.yml b/definitions/EiffelTestCaseFinishedEvent/3.1.0.yml new file mode 100644 index 00000000..ea7b13e5 --- /dev/null +++ b/definitions/EiffelTestCaseFinishedEvent/3.1.0.yml @@ -0,0 +1,207 @@ +# 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: TCF +_description: |- + The EiffelTestCaseFinishedEvent declares that a previously started test case (declared by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test case reports not only the conclusion of the test case execution - whether the test case was successfully executed - but also passes a verdict on the item under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. + + Also note that unlike [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md), EiffelTestCaseFinishedEvent must report both __data.outcome.verdict__ and __data.outcome.conclusion__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test case. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. + PASSED signifies that the item or items under test successfully passed the test case. + FAILED signifies that the item or items under test failed to pass the test case. + INCONCLUSIVE signifies that the verdict of the test case was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test case, designed to be machine readable. + SUCCESSFUL signifies that the test case was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test case could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test case was aborted before it could be concluded. + TIMED_OUT signifies that the test case did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test case could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test case outcome, + designed to provide human readers with further information. + type: string + metrics: + _description: A list of metrics collected during the test + case execution. Note that while complete freedom is allowed + in metrics names and value types, it is highly recommended + to keep reported metrics concise and consistent. In other + words, do not include excessive amounts of data (use + __data.persistentLogs__ for that), and avoid unnecessary + variations in value names or types over time. + type: array + items: + type: object + properties: + name: + _description: The metrics name. + type: string + value: + _description: The metrics value. + required: + - name + - value + additionalProperties: false + required: + - verdict + - conclusion + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - outcome + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 3.1.0 + introduced_in: Current version + changes: Add `data.persistentLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 1.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 1.0.1 + introduced_in: '[0a2f9ef](../../../blob/0a2f9ef139fe6ead2493e5deddf1337ffb3dd4af/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)' + changes: data.outcome.metrics.value and data.outcome.metrics.name + made mandatory. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestCaseFinishedEvent/simple.json diff --git a/definitions/EiffelTestCaseFinishedEvent/3.2.0.yml b/definitions/EiffelTestCaseFinishedEvent/3.2.0.yml new file mode 100644 index 00000000..f4a25400 --- /dev/null +++ b/definitions/EiffelTestCaseFinishedEvent/3.2.0.yml @@ -0,0 +1,211 @@ +# 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: TCF +_description: |- + The EiffelTestCaseFinishedEvent declares that a previously started test case (declared by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test case reports not only the conclusion of the test case execution - whether the test case was successfully executed - but also passes a verdict on the item under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. + + Also note that unlike [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md), EiffelTestCaseFinishedEvent must report both __data.outcome.verdict__ and __data.outcome.conclusion__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test case. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. + PASSED signifies that the item or items under test successfully passed the test case. + FAILED signifies that the item or items under test failed to pass the test case. + INCONCLUSIVE signifies that the verdict of the test case was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test case, designed to be machine readable. + SUCCESSFUL signifies that the test case was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test case could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test case was aborted before it could be concluded. + TIMED_OUT signifies that the test case did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test case could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test case outcome, + designed to provide human readers with further information. + type: string + metrics: + _description: A list of metrics collected during the test + case execution. Note that while complete freedom is allowed + in metrics names and value types, it is highly recommended + to keep reported metrics concise and consistent. In other + words, do not include excessive amounts of data (use + __data.persistentLogs__ for that), and avoid unnecessary + variations in value names or types over time. + type: array + items: + type: object + properties: + name: + _description: The metrics name. + type: string + value: + _description: The metrics value. + required: + - name + - value + additionalProperties: false + required: + - verdict + - conclusion + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - outcome + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 3.2.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.1.0 + introduced_in: No edition set + changes: Add `data.persistentLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 1.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 1.0.1 + introduced_in: '[0a2f9ef](../../../blob/0a2f9ef139fe6ead2493e5deddf1337ffb3dd4af/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)' + changes: data.outcome.metrics.value and data.outcome.metrics.name + made mandatory. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestCaseFinishedEvent/simple.json diff --git a/definitions/EiffelTestCaseStartedEvent/1.0.0.yml b/definitions/EiffelTestCaseStartedEvent/1.0.0.yml new file mode 100644 index 00000000..906b8de5 --- /dev/null +++ b/definitions/EiffelTestCaseStartedEvent/1.0.0.yml @@ -0,0 +1,130 @@ +# 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: TCS +_description: The EiffelTestCaseStartedEvent declares that the execution + of a test case has commenced. This event SHALL be preceded by a [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md), + and appropriately linked to via __TEST_CASE_EXECUTION__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + executor: + _description: The name of the test case executor, if applicable. + This property can be used to identify tests executed by a + particular test framework. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test case execution has finished there + is no guarantee that these links are valid. Persistently + stored logs shall be (re-)declared by [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the test case + is being executed. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestCaseStartedEvent/simple.json diff --git a/definitions/EiffelTestCaseStartedEvent/1.1.0.yml b/definitions/EiffelTestCaseStartedEvent/1.1.0.yml new file mode 100644 index 00000000..dbe3e900 --- /dev/null +++ b/definitions/EiffelTestCaseStartedEvent/1.1.0.yml @@ -0,0 +1,133 @@ +# 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: TCS +_description: The EiffelTestCaseStartedEvent declares that the execution + of a test case has commenced. This event SHALL be preceded by a [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md), + and appropriately linked to via __TEST_CASE_EXECUTION__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + executor: + _description: The name of the test case executor, if applicable. + This property can be used to identify tests executed by a + particular test framework. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test case execution has finished there + is no guarantee that these links are valid. Persistently + stored logs shall be (re-)declared by [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the test case + is being executed. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_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/EiffelTestCaseStartedEvent/simple.json diff --git a/definitions/EiffelTestCaseStartedEvent/2.0.0.yml b/definitions/EiffelTestCaseStartedEvent/2.0.0.yml new file mode 100644 index 00000000..58294a1a --- /dev/null +++ b/definitions/EiffelTestCaseStartedEvent/2.0.0.yml @@ -0,0 +1,137 @@ +# 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: TCS +_description: The EiffelTestCaseStartedEvent declares that the execution + of a test case has commenced. This event SHALL be preceded by a [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md), + and appropriately linked to via __TEST_CASE_EXECUTION__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + executor: + _description: The name of the test case executor, if applicable. + This property can be used to identify tests executed by a + particular test framework. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test case execution has finished there + is no guarantee that these links are valid. Persistently + stored logs shall be (re-)declared by [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the test case + is being executed. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseStartedEvent/simple.json diff --git a/definitions/EiffelTestCaseStartedEvent/3.0.0.yml b/definitions/EiffelTestCaseStartedEvent/3.0.0.yml new file mode 100644 index 00000000..861cf9d8 --- /dev/null +++ b/definitions/EiffelTestCaseStartedEvent/3.0.0.yml @@ -0,0 +1,140 @@ +# 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: TCS +_description: The EiffelTestCaseStartedEvent declares that the execution + of a test case has commenced. This event SHALL be preceded by a [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md), + and appropriately linked to via __TEST_CASE_EXECUTION__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + executor: + _description: The name of the test case executor, if applicable. + This property can be used to identify tests executed by a + particular test framework. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test case execution has finished there + is no guarantee that these links are valid. Persistently + stored logs shall be (re-)declared by [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the test case + is being executed. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseStartedEvent/simple.json diff --git a/definitions/EiffelTestCaseStartedEvent/3.1.0.yml b/definitions/EiffelTestCaseStartedEvent/3.1.0.yml new file mode 100644 index 00000000..ccb5dea6 --- /dev/null +++ b/definitions/EiffelTestCaseStartedEvent/3.1.0.yml @@ -0,0 +1,156 @@ +# 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: TCS +_description: The EiffelTestCaseStartedEvent declares that the execution + of a test case has commenced. This event SHALL be preceded by a [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md), + and appropriately linked to via __TEST_CASE_EXECUTION__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + executor: + _description: The name of the test case executor, if applicable. + This property can be used to identify tests executed by a + particular test framework. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test case execution has finished there + is no guarantee that these links are valid. Persistently + stored logs shall be (re-)declared by [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md). + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the test case + is being executed. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 3.1.0 + introduced_in: Current version + changes: Add `data.liveLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseStartedEvent/simple.json diff --git a/definitions/EiffelTestCaseStartedEvent/3.2.0.yml b/definitions/EiffelTestCaseStartedEvent/3.2.0.yml new file mode 100644 index 00000000..d645590f --- /dev/null +++ b/definitions/EiffelTestCaseStartedEvent/3.2.0.yml @@ -0,0 +1,160 @@ +# 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: TCS +_description: The EiffelTestCaseStartedEvent declares that the execution + of a test case has commenced. This event SHALL be preceded by a [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md), + and appropriately linked to via __TEST_CASE_EXECUTION__. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + executor: + _description: The name of the test case executor, if applicable. + This property can be used to identify tests executed by a + particular test framework. + type: string + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test case execution has finished there + is no guarantee that these links are valid. Persistently + stored logs shall be (re-)declared by [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md). + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + ENVIRONMENT: + description: Identifies the environment in which the test case + is being executed. + required: false + multiple: false + targets: + any_type: false + types: + - EiffelEnvironmentDefinedEvent + 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 + TEST_CASE_EXECUTION: + description: Identifies the relevant test case execution. In other + words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) + acts as a handle for a particular test case execution. This differs + from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries + information pertaining to the target (i.e. the test case execution + 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: + - EiffelTestCaseTriggeredEvent +_history: + - version: 3.2.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.1.0 + introduced_in: No edition set + changes: Add `data.liveLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseStartedEvent/simple.json diff --git a/definitions/EiffelTestCaseTriggeredEvent/1.0.0.yml b/definitions/EiffelTestCaseTriggeredEvent/1.0.0.yml new file mode 100644 index 00000000..a5f0c1e5 --- /dev/null +++ b/definitions/EiffelTestCaseTriggeredEvent/1.0.0.yml @@ -0,0 +1,180 @@ +# 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: TCT +_description: |- + The EiffelTestCaseTriggeredEvent declares that the execution of a test case has been triggered, but not yet started. This can either be declared stand-alone or as part of an activity or test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + This event is used to communicate intent, and thereby serves a similar purpose to that of [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md). A triggered test case execution is expected to either be started (represented by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) or canceled (represented by [EiffelTestCaseCanceledEvent](./EiffelTestCaseCanceledEvent.md)). Consequently, any delay between triggering and execution can be assumed to imply queuing time (e.g. waiting for available test resources) and monitored as such. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + testCase: + _description: Identification of the test case to be executed. + type: object + properties: + tracker: + _description: The name of the test case tracker - typically + a test management system. + type: string + id: + _description: The unique identity of the test case to be + executed. + type: string + version: + _description: The unique version of the identified test + case to be executed. Where this property is not used + it is assumed that test cases are not version controlled. + type: string + uri: + _description: A location where a description of the test + case can be retrieved. To the extent that multiple versions + of the same test case co-exist, this property SHALL identify + the exact version to be executed. + type: string + required: + - id + additionalProperties: false + recipeId: + _description: If triggering this test case execution was the + result of an Execution Recipe, as defined by an [EiffelTestExecutionRecipeCollectionCreatedEvent](./EiffelTestExecutionRecipeCollectionCreatedEvent.md), + this UUID SHALL match the relevant __data.batches.recipes.id__ + in that event. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + triggers: + _description: The circumstances triggering the test case execution. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the test case execution was manually triggered. + EIFFEL_EVENT signifies that the test case execution was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the test case execution was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the test case execution was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + parameters: + _description: A list of parameters to be passed to the test + case execution. + type: array + items: + type: object + properties: + name: + _description: The name of the parameter. + type: string + value: + _description: The value of the parameter. + type: string + required: + - name + - value + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - testCase + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + IUT: + description: Identifies the Item Under Test; in other words, the + entity that is about to be tested. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestCaseTriggeredEvent/simple.json diff --git a/definitions/EiffelTestCaseTriggeredEvent/1.1.0.yml b/definitions/EiffelTestCaseTriggeredEvent/1.1.0.yml new file mode 100644 index 00000000..d9a2e965 --- /dev/null +++ b/definitions/EiffelTestCaseTriggeredEvent/1.1.0.yml @@ -0,0 +1,183 @@ +# 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: TCT +_description: |- + The EiffelTestCaseTriggeredEvent declares that the execution of a test case has been triggered, but not yet started. This can either be declared stand-alone or as part of an activity or test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + This event is used to communicate intent, and thereby serves a similar purpose to that of [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md). A triggered test case execution is expected to either be started (represented by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) or canceled (represented by [EiffelTestCaseCanceledEvent](./EiffelTestCaseCanceledEvent.md)). Consequently, any delay between triggering and execution can be assumed to imply queuing time (e.g. waiting for available test resources) and monitored as such. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + testCase: + _description: Identification of the test case to be executed. + type: object + properties: + tracker: + _description: The name of the test case tracker - typically + a test management system. + type: string + id: + _description: The unique identity of the test case to be + executed. + type: string + version: + _description: The unique version of the identified test + case to be executed. Where this property is not used + it is assumed that test cases are not version controlled. + type: string + uri: + _description: A location where a description of the test + case can be retrieved. To the extent that multiple versions + of the same test case co-exist, this property SHALL identify + the exact version to be executed. + type: string + required: + - id + additionalProperties: false + recipeId: + _description: If triggering this test case execution was the + result of an Execution Recipe, as defined by an [EiffelTestExecutionRecipeCollectionCreatedEvent](./EiffelTestExecutionRecipeCollectionCreatedEvent.md), + this UUID SHALL match the relevant __data.batches.recipes.id__ + in that event. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + triggers: + _description: The circumstances triggering the test case execution. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the test case execution was manually triggered. + EIFFEL_EVENT signifies that the test case execution was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the test case execution was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the test case execution was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + parameters: + _description: A list of parameters to be passed to the test + case execution. + type: array + items: + type: object + properties: + name: + _description: The name of the parameter. + type: string + value: + _description: The value of the parameter. + type: string + required: + - name + - value + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - testCase + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + IUT: + description: Identifies the Item Under Test; in other words, the + entity that is about to be tested. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent +_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/EiffelTestCaseTriggeredEvent/simple.json diff --git a/definitions/EiffelTestCaseTriggeredEvent/2.0.0.yml b/definitions/EiffelTestCaseTriggeredEvent/2.0.0.yml new file mode 100644 index 00000000..6310eb31 --- /dev/null +++ b/definitions/EiffelTestCaseTriggeredEvent/2.0.0.yml @@ -0,0 +1,187 @@ +# 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: TCT +_description: |- + The EiffelTestCaseTriggeredEvent declares that the execution of a test case has been triggered, but not yet started. This can either be declared stand-alone or as part of an activity or test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + This event is used to communicate intent, and thereby serves a similar purpose to that of [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md). A triggered test case execution is expected to either be started (represented by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) or canceled (represented by [EiffelTestCaseCanceledEvent](./EiffelTestCaseCanceledEvent.md)). Consequently, any delay between triggering and execution can be assumed to imply queuing time (e.g. waiting for available test resources) and monitored as such. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + testCase: + _description: Identification of the test case to be executed. + type: object + properties: + tracker: + _description: The name of the test case tracker - typically + a test management system. + type: string + id: + _description: The unique identity of the test case to be + executed. + type: string + version: + _description: The unique version of the identified test + case to be executed. Where this property is not used + it is assumed that test cases are not version controlled. + type: string + uri: + _description: A location where a description of the test + case can be retrieved. To the extent that multiple versions + of the same test case co-exist, this property SHALL identify + the exact version to be executed. + type: string + required: + - id + additionalProperties: false + recipeId: + _description: If triggering this test case execution was the + result of an Execution Recipe, as defined by an [EiffelTestExecutionRecipeCollectionCreatedEvent](./EiffelTestExecutionRecipeCollectionCreatedEvent.md), + this UUID SHALL match the relevant __data.batches.recipes.id__ + in that event. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + triggers: + _description: The circumstances triggering the test case execution. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the test case execution was manually triggered. + EIFFEL_EVENT signifies that the test case execution was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the test case execution was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the test case execution was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + parameters: + _description: A list of parameters to be passed to the test + case execution. + type: array + items: + type: object + properties: + name: + _description: The name of the parameter. + type: string + value: + _description: The value of the parameter. + type: string + required: + - name + - value + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - testCase + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + IUT: + description: Identifies the Item Under Test; in other words, the + entity that is about to be tested. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseTriggeredEvent/simple.json diff --git a/definitions/EiffelTestCaseTriggeredEvent/3.0.0.yml b/definitions/EiffelTestCaseTriggeredEvent/3.0.0.yml new file mode 100644 index 00000000..d2dcc31a --- /dev/null +++ b/definitions/EiffelTestCaseTriggeredEvent/3.0.0.yml @@ -0,0 +1,192 @@ +# 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: TCT +_description: |- + The EiffelTestCaseTriggeredEvent declares that the execution of a test case has been triggered, but not yet started. This can either be declared stand-alone or as part of an activity or test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + This event is used to communicate intent, and thereby serves a similar purpose to that of [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md). A triggered test case execution is expected to either be started (represented by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) or canceled (represented by [EiffelTestCaseCanceledEvent](./EiffelTestCaseCanceledEvent.md)). Consequently, any delay between triggering and execution can be assumed to imply queuing time (e.g. waiting for available test resources) and monitored as such. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + testCase: + _description: Identification of the test case to be executed. + type: object + properties: + tracker: + _description: The name of the test case tracker - typically + a test management system. + type: string + id: + _description: The unique identity of the test case to be + executed. + type: string + version: + _description: The unique version of the identified test + case to be executed. Where this property is not used + it is assumed that test cases are not version controlled. + type: string + uri: + _description: A location where a description of the test + case can be retrieved. To the extent that multiple versions + of the same test case co-exist, this property SHALL identify + the exact version to be executed. + type: string + required: + - id + additionalProperties: false + recipeId: + _description: If triggering this test case execution was the + result of an Execution Recipe, as defined by an [EiffelTestExecutionRecipeCollectionCreatedEvent](./EiffelTestExecutionRecipeCollectionCreatedEvent.md), + this UUID SHALL match the relevant __data.batches.recipes.id__ + in that event. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + triggers: + _description: The circumstances triggering the test case execution. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the test case execution was manually triggered. + EIFFEL_EVENT signifies that the test case execution was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the test case execution was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the test case execution was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + parameters: + _description: A list of parameters to be passed to the test + case execution. + type: array + items: + type: object + properties: + name: + _description: The name of the parameter. + type: string + value: + _description: The value of the parameter. + type: string + required: + - name + - value + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - testCase + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + IUT: + description: Identifies the Item Under Test; in other words, the + entity that is about to be tested. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseTriggeredEvent/simple.json + - title: Simple example using pre-3.0.0 meta.security object + url: ../examples/events/EiffelTestCaseTriggeredEvent/simple-2.0.0.json diff --git a/definitions/EiffelTestCaseTriggeredEvent/3.1.0.yml b/definitions/EiffelTestCaseTriggeredEvent/3.1.0.yml new file mode 100644 index 00000000..25067e1b --- /dev/null +++ b/definitions/EiffelTestCaseTriggeredEvent/3.1.0.yml @@ -0,0 +1,210 @@ +# 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: TCT +_description: |- + The EiffelTestCaseTriggeredEvent declares that the execution of a test case has been triggered, but not yet started. This can either be declared stand-alone or as part of an activity or test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + This event is used to communicate intent, and thereby serves a similar purpose to that of [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md). A triggered test case execution is expected to either be started (represented by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) or canceled (represented by [EiffelTestCaseCanceledEvent](./EiffelTestCaseCanceledEvent.md)). Consequently, any delay between triggering and execution can be assumed to imply queuing time (e.g. waiting for available test resources) and monitored as such. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + testCase: + _description: Identification of the test case to be executed. + type: object + properties: + tracker: + _description: The name of the test case tracker - typically + a test management system. + type: string + id: + _description: The unique identity of the test case to be + executed. + type: string + version: + _description: The unique version of the identified test + case to be executed. Where this property is not used + it is assumed that test cases are not version controlled. + type: string + uri: + _description: A location where a description of the test + case can be retrieved. To the extent that multiple versions + of the same test case co-exist, this property SHALL identify + the exact version to be executed. + type: string + required: + - id + additionalProperties: false + recipeId: + _description: If triggering this test case execution was the + result of an Execution Recipe, as defined by an [EiffelTestExecutionRecipeCollectionCreatedEvent](./EiffelTestExecutionRecipeCollectionCreatedEvent.md), + this UUID SHALL match the relevant __data.batches.recipes.id__ + in that event. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + triggers: + _description: The circumstances triggering the test case execution. + type: array + items: + type: object + properties: + type: + _description: |- + The type of trigger. + MANUAL signifies that the test case execution was manually triggered. + EIFFEL_EVENT signifies that the test case execution was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. + SOURCE_CHANGE signifies that the test case execution was triggered as a consequence of a detected source change __not__ represented by Eiffel events. + TIMER signifies that the test case execution was triggered by a timer. + OTHER signifies any other triggering cause. + type: string + enum: + - MANUAL + - EIFFEL_EVENT + - SOURCE_CHANGE + - TIMER + - OTHER + description: + _description: A description of the trigger. + type: string + required: + - type + additionalProperties: false + executionType: + _description: The type of execution (often related to, but + ultimately separate from, __data.triggers.type__). + type: string + enum: + - MANUAL + - SEMI_AUTOMATED + - AUTOMATED + - OTHER + parameters: + _description: A list of parameters to be passed to the test + case execution. + type: array + items: + type: object + properties: + name: + _description: The name of the parameter. + type: string + value: + _description: The value of the parameter. + type: string + required: + - name + - value + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - testCase + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + IUT: + description: Identifies the Item Under Test; in other words, the + entity that is about to be tested. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelArtifactCreatedEvent + - EiffelCompositionDefinedEvent + PRECURSOR: + description: 'Used to declare temporal relationships between + [activities](../eiffel-syntax-and-usage/glossary.md#activity) in a + [pipeline](../eiffel-syntax-and-usage/glossary.md#pipeline), i.e. what + other activity/activities preceded this activity. This link type applies + primarily to non event-triggered activities. For more information on + the usage of this link type please see + [Activity Linking](../eiffel-syntax-and-usage/activity-linking.md).' + required: false + multiple: true + targets: + any_type: false + types: + - EiffelTestCaseTriggeredEvent +_history: + - version: 3.1.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestCaseTriggeredEvent/simple.json + - title: Simple example using pre-3.0.0 meta.security object + url: ../examples/events/EiffelTestCaseTriggeredEvent/simple-2.0.0.json diff --git a/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/1.0.0.yml b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/1.0.0.yml new file mode 100644 index 00000000..021121f9 --- /dev/null +++ b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/1.0.0.yml @@ -0,0 +1,185 @@ +# 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: TERCC +_description: |- + The EiffelTestExecutionRecipeCollectionCreatedEvent declares that a collection of test execution recipes has been created. In order to clarify what that means, several concepts need to be explained. + + Just as Eiffel is an opinionated protocol, EiffelTestExecutionRecipeCollectionCreatedEvent is an opinionated event, and to a certain extent that opinion goes against the grain of traditional test management. This event assumes that activity configurations and test scope definitions are two separate things. To exemplify, when one's CI server triggers the Acceptance Test activity in the pipeline, there is nothing in that activity that says which tests to execute where or with what parameters: that is a separate concern. Instead, it will query a test selection service for that information. This information is encapsulated by the EiffelTestExecutionRecipeCollectionCreatedEvent, which contains all the information needed to configure and execute the tests. + + How the test selection service generates the recipe collection is, from the point of view of the Eiffel protocol, irrelevant. It may very well be from a statically defined list of test cases, or from an elaborate test selection algorithm weighing together a host of factors to determine the optimal set of test cases to execute at any particular time, or a combination of the two. + + The __data__ object consists of two main parts. __data.selectionStrategy__ identifies the strategy used to select the test cases and generate the recipe collection, while __data.batches__ or __data.batchesUri__ contain or reference, respectively, the recipes. The recipes are grouped in batches, which are used to control the order of execution of test cases. Every batch has a priority to let the test executor order them in sequence, but within each batch no assumptions are made as to the execution order the test cases. This way the recipe collection can either allow the executor a high degree of freedom in scheduling the test executions, and/or prescribe the exact sequential order in which they must be executed. Each event SHALL include one and only one of __data.batches__ and __data.batchesUri__. + + Finally, each recipe (__data.batches.recipes__) consists of two parts: the test case to execute, and the constraints of that execution. The EiffelTestExecutionRecipeCollectionCreatedEvent does not control the syntax of these constraints, as the nature of such constraints are highly dependent on technology domain and test execution framework. That being said, there are three questions that typically need to be answered: what is the item under test, in what kind of environment is it to be tested, and what are the test parameters? Note the distinction between test case and test execution: it is perfectly legal for a single test case to appear multiple times within the same EiffelTestExecutionRecipeCollectionCreatedEvent, but (presumably) with different constraints. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + selectionStrategy: + _description: The strategy used to select the test cases and + generate the recipe collection. + type: object + properties: + tracker: + _description: The name of the selection strategy that generated + the test execution recipe collection. + type: string + id: + _description: The unique identity of the selection strategy + that generated the test execution recipe collection. + type: string + uri: + _description: The URI at which the the selection strategy + that generated the test execution recipe collection can + be retrieved. + type: string + required: + - id + additionalProperties: false + batchesUri: + _description: 'A URI at which at which the array of test execution + batches can be fetched. The format of the document at this + URI SHALL be on the format prescribed by __data.batches__ + (i.e. ``` [ { "name": "Batch 1", ...}, {...}] ```). Each + event SHALL include one and only one of __data.batches__ + and __data.batchesUri__.' + type: string + batches: + _description: A list of batches of recipes. Each event SHALL + include one and only one of __data.batches__ and __data.batchesUri__. + In the interest of keeping message sizes small, it is recommended + to use __data.batches__ only for limited numbers of test + cases (on the order of ten executions). For larger numbers + of executions, __data.batchesUri__ SHOULD be used instead. + type: array + items: + type: object + properties: + name: + _description: The name of the recipe batch. + type: string + priority: + _description: The execution priority of the batch, as + compared to other batches in the collection. A lower + value SHALL be interpreted as a higher priority. + type: integer + recipes: + _description: The collection of test execution recipes + within the batch. + type: array + items: + type: object + properties: + id: + _description: A UUID identifying the unique execution. + Note that this is different from the id of a + test case, in two ways. First, a test case is + a (presumably) persistnent entity, whereas an + execution is transient in nature. Second, a test + case may be executed any number of times in any + given recipe collection. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + testCase: + _description: The test case to be executed in this + execution recipe. + type: object + properties: + tracker: + _description: The name of the test case tracker + - typically a test management system. + type: string + id: + _description: The unique identity of the test + case. + type: string + uri: + _description: A location where a description + of the test case can be retrieved. + type: string + required: + - id + additionalProperties: false + constraints: + _description: 'Any constraints of the execution. + The syntax of this object is not controlled, + as the nature of such constraints are highly + dependent on technology domain and test execution + framework. That being said, there are three questions + that typically need to be answered: what is the + item under test, in what kind of environment + is it to be tested, and what are the test parameters?' + type: object + required: + - id + - testCase + additionalProperties: false + dependencies: + _description: A list of test case execution dependencies. + Ideally, test cases are atomic and can be executed + in isolation. In cases where a test case assumes that + another test case has been executed previously in the + same environment, however, this property can be used + to specify that. It serves as an instruction to the + test executor to place two executions subsequent to + one another in the same environment. + type: array + items: + type: object + properties: + dependent: + _description: The UUID of the dependent execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed only after that of the + dependency. + type: string + dependency: + _description: The UUID of the dependency execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed prior to that of the + dependent. + type: string + required: + - dependent + - dependency + additionalProperties: false + required: + - priority + - recipes + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - selectionStrategy + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: {} +_history: [] +_examples: [] diff --git a/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/2.0.0.yml b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/2.0.0.yml new file mode 100644 index 00000000..97e7f0d4 --- /dev/null +++ b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/2.0.0.yml @@ -0,0 +1,245 @@ +# 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: TERCC +_description: |- + The EiffelTestExecutionRecipeCollectionCreatedEvent declares that a collection of test execution recipes has been created. In order to clarify what that means, several concepts need to be explained. + + Just as Eiffel is an opinionated protocol, EiffelTestExecutionRecipeCollectionCreatedEvent is an opinionated event, and to a certain extent that opinion goes against the grain of traditional test management. This event assumes that activity configurations and test scope definitions are two separate things. To exemplify, when one's CI server triggers the Acceptance Test activity in the pipeline, there is nothing in that activity that says which tests to execute where or with what parameters: that is a separate concern. Instead, it will query a test selection service for that information. This information is encapsulated by the EiffelTestExecutionRecipeCollectionCreatedEvent, which contains all the information needed to configure and execute the tests. + + How the test selection service generates the recipe collection is, from the point of view of the Eiffel protocol, irrelevant. It may very well be from a statically defined list of test cases, or from an elaborate test selection algorithm weighing together a host of factors to determine the optimal set of test cases to execute at any particular time, or a combination of the two. + + The __data__ object consists of two main parts. __data.selectionStrategy__ identifies the strategy used to select the test cases and generate the recipe collection, while __data.batches__ or __data.batchesUri__ contain or reference, respectively, the recipes. The recipes are grouped in batches, which are used to control the order of execution of test cases. Every batch has a priority to let the test executor order them in sequence, but within each batch no assumptions are made as to the execution order the test cases. This way the recipe collection can either allow the executor a high degree of freedom in scheduling the test executions, and/or prescribe the exact sequential order in which they must be executed. Each event SHALL include one and only one of __data.batches__ and __data.batchesUri__. + + Finally, each recipe (__data.batches.recipes__) consists of two parts: the test case to execute, and the constraints of that execution. The EiffelTestExecutionRecipeCollectionCreatedEvent does not control the syntax of these constraints, as the nature of such constraints are highly dependent on technology domain and test execution framework. That being said, there are three questions that typically need to be answered: what is the item under test, in what kind of environment is it to be tested, and what are the test parameters? Note the distinction between test case and test execution: it is perfectly legal for a single test case to appear multiple times within the same EiffelTestExecutionRecipeCollectionCreatedEvent, but (presumably) with different constraints. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + selectionStrategy: + _description: The strategy used to select the test cases and + generate the recipe collection. + type: object + properties: + tracker: + _description: The name of the selection strategy that generated + the test execution recipe collection. + type: string + id: + _description: The unique identity of the selection strategy + that generated the test execution recipe collection. + type: string + uri: + _description: The URI at which the the selection strategy + that generated the test execution recipe collection can + be retrieved. + type: string + required: + - id + additionalProperties: false + batchesUri: + _description: 'A URI at which at which the array of test execution + batches can be fetched. The format of the document at this + URI SHALL be on the format prescribed by __data.batches__ + (i.e. ``` [ { "name": "Batch 1", ...}, {...}] ```). Each + event SHALL include one and only one of __data.batches__ + and __data.batchesUri__.' + type: string + batches: + _description: A list of batches of recipes. Each event SHALL + include one and only one of __data.batches__ and __data.batchesUri__. + In the interest of keeping message sizes small, it is recommended + to use __data.batches__ only for limited numbers of test + cases (on the order of ten executions). For larger numbers + of executions, __data.batchesUri__ SHOULD be used instead. + type: array + items: + type: object + properties: + name: + _description: The name of the recipe batch. + type: string + priority: + _description: The execution priority of the batch, as + compared to other batches in the collection. A lower + value SHALL be interpreted as a higher priority. + type: integer + recipes: + _description: The collection of test execution recipes + within the batch. + type: array + items: + type: object + properties: + id: + _description: A UUID identifying the unique execution. + Note that this is different from the id of a + test case, in two ways. First, a test case is + a (presumably) persistnent entity, whereas an + execution is transient in nature. Second, a test + case may be executed any number of times in any + given recipe collection. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + testCase: + _description: The test case to be executed in this + execution recipe. + type: object + properties: + tracker: + _description: The name of the test case tracker + - typically a test management system. + type: string + id: + _description: The unique identity of the test + case. + type: string + uri: + _description: A location where a description + of the test case can be retrieved. + type: string + required: + - id + additionalProperties: false + constraints: + _description: 'Any constraints of the execution. + The nature of such constraints is highly dependent + on technology domain and test execution framework. + Consequently, there are no pre-defined or required + constraints. Instead, this property is a list + of key-value pairs on the same format as [data.customData](../customization/custom-data.md). + That being said, there are three questions that + typically need to be answered: what is the item + under test, in what kind of environment is it + to be tested, and what are the test parameters?' + type: array + items: + type: object + properties: + key: + _description: The key name of constraint. + type: string + value: + _description: The value of the constraint. + required: + - key + - value + additionalProperties: false + required: + - id + - testCase + additionalProperties: false + dependencies: + _description: A list of test case execution dependencies. + Ideally, test cases are atomic and can be executed + in isolation. In cases where a test case assumes that + another test case has been executed previously in the + same environment, however, this property can be used + to specify that. It serves as an instruction to the + test executor to place two executions subsequent to + one another in the same environment. + type: array + items: + type: object + properties: + dependent: + _description: The UUID of the dependent execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed only after that of the + dependency. + type: string + dependency: + _description: The UUID of the dependency execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed prior to that of the + dependent. + type: string + required: + - dependent + - dependency + additionalProperties: false + required: + - priority + - recipes + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - selectionStrategy + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.0.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 2.0.0 + introduced_in: Current version. + changes: Changed syntax of data.batches.recipes.constraints from + an uncontrolled object to a list of key-value pairs to comply + with design guidelines. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Example using data.batches + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches.json + - title: Example using data.batches (1.0.0 syntax) + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches-1.0.0.json + - title: Example using data.batchesUri + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batchesUri.json diff --git a/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/2.1.0.yml b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/2.1.0.yml new file mode 100644 index 00000000..76096932 --- /dev/null +++ b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/2.1.0.yml @@ -0,0 +1,248 @@ +# 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: TERCC +_description: |- + The EiffelTestExecutionRecipeCollectionCreatedEvent declares that a collection of test execution recipes has been created. In order to clarify what that means, several concepts need to be explained. + + Just as Eiffel is an opinionated protocol, EiffelTestExecutionRecipeCollectionCreatedEvent is an opinionated event, and to a certain extent that opinion goes against the grain of traditional test management. This event assumes that activity configurations and test scope definitions are two separate things. To exemplify, when one's CI server triggers the Acceptance Test activity in the pipeline, there is nothing in that activity that says which tests to execute where or with what parameters: that is a separate concern. Instead, it will query a test selection service for that information. This information is encapsulated by the EiffelTestExecutionRecipeCollectionCreatedEvent, which contains all the information needed to configure and execute the tests. + + How the test selection service generates the recipe collection is, from the point of view of the Eiffel protocol, irrelevant. It may very well be from a statically defined list of test cases, or from an elaborate test selection algorithm weighing together a host of factors to determine the optimal set of test cases to execute at any particular time, or a combination of the two. + + The __data__ object consists of two main parts. __data.selectionStrategy__ identifies the strategy used to select the test cases and generate the recipe collection, while __data.batches__ or __data.batchesUri__ contain or reference, respectively, the recipes. The recipes are grouped in batches, which are used to control the order of execution of test cases. Every batch has a priority to let the test executor order them in sequence, but within each batch no assumptions are made as to the execution order the test cases. This way the recipe collection can either allow the executor a high degree of freedom in scheduling the test executions, and/or prescribe the exact sequential order in which they must be executed. Each event SHALL include one and only one of __data.batches__ and __data.batchesUri__. + + Finally, each recipe (__data.batches.recipes__) consists of two parts: the test case to execute, and the constraints of that execution. The EiffelTestExecutionRecipeCollectionCreatedEvent does not control the syntax of these constraints, as the nature of such constraints are highly dependent on technology domain and test execution framework. That being said, there are three questions that typically need to be answered: what is the item under test, in what kind of environment is it to be tested, and what are the test parameters? Note the distinction between test case and test execution: it is perfectly legal for a single test case to appear multiple times within the same EiffelTestExecutionRecipeCollectionCreatedEvent, but (presumably) with different constraints. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + selectionStrategy: + _description: The strategy used to select the test cases and + generate the recipe collection. + type: object + properties: + tracker: + _description: The name of the selection strategy that generated + the test execution recipe collection. + type: string + id: + _description: The unique identity of the selection strategy + that generated the test execution recipe collection. + type: string + uri: + _description: The URI at which the the selection strategy + that generated the test execution recipe collection can + be retrieved. + type: string + required: + - id + additionalProperties: false + batchesUri: + _description: 'A URI at which at which the array of test execution + batches can be fetched. The format of the document at this + URI SHALL be on the format prescribed by __data.batches__ + (i.e. ``` [ { "name": "Batch 1", ...}, {...}] ```). Each + event SHALL include one and only one of __data.batches__ + and __data.batchesUri__.' + type: string + batches: + _description: A list of batches of recipes. Each event SHALL + include one and only one of __data.batches__ and __data.batchesUri__. + In the interest of keeping message sizes small, it is recommended + to use __data.batches__ only for limited numbers of test + cases (on the order of ten executions). For larger numbers + of executions, __data.batchesUri__ SHOULD be used instead. + type: array + items: + type: object + properties: + name: + _description: The name of the recipe batch. + type: string + priority: + _description: The execution priority of the batch, as + compared to other batches in the collection. A lower + value SHALL be interpreted as a higher priority. + type: integer + recipes: + _description: The collection of test execution recipes + within the batch. + type: array + items: + type: object + properties: + id: + _description: A UUID identifying the unique execution. + Note that this is different from the id of a + test case, in two ways. First, a test case is + a (presumably) persistnent entity, whereas an + execution is transient in nature. Second, a test + case may be executed any number of times in any + given recipe collection. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + testCase: + _description: The test case to be executed in this + execution recipe. + type: object + properties: + tracker: + _description: The name of the test case tracker + - typically a test management system. + type: string + id: + _description: The unique identity of the test + case. + type: string + uri: + _description: A location where a description + of the test case can be retrieved. + type: string + required: + - id + additionalProperties: false + constraints: + _description: 'Any constraints of the execution. + The nature of such constraints is highly dependent + on technology domain and test execution framework. + Consequently, there are no pre-defined or required + constraints. Instead, this property is a list + of key-value pairs on the same format as [data.customData](../customization/custom-data.md). + That being said, there are three questions that + typically need to be answered: what is the item + under test, in what kind of environment is it + to be tested, and what are the test parameters?' + type: array + items: + type: object + properties: + key: + _description: The key name of constraint. + type: string + value: + _description: The value of the constraint. + required: + - key + - value + additionalProperties: false + required: + - id + - testCase + additionalProperties: false + dependencies: + _description: A list of test case execution dependencies. + Ideally, test cases are atomic and can be executed + in isolation. In cases where a test case assumes that + another test case has been executed previously in the + same environment, however, this property can be used + to specify that. It serves as an instruction to the + test executor to place two executions subsequent to + one another in the same environment. + type: array + items: + type: object + properties: + dependent: + _description: The UUID of the dependent execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed only after that of the + dependency. + type: string + dependency: + _description: The UUID of the dependency execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed prior to that of the + dependent. + type: string + required: + - dependent + - dependency + additionalProperties: false + required: + - priority + - recipes + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - selectionStrategy + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.0.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 2.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 2.0.0 + introduced_in: '[f92e001](../../../blob/f92e001c88d1139a62f8ace976958e0a30d8f9c5/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Changed syntax of data.batches.recipes.constraints from + an uncontrolled object to a list of key-value pairs to comply + with design guidelines. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Example using data.batches + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches.json + - title: Example using data.batches (1.0.0 syntax) + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches-1.0.0.json + - title: Example using data.batchesUri + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batchesUri.json diff --git a/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/3.0.0.yml b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/3.0.0.yml new file mode 100644 index 00000000..ce3cbb16 --- /dev/null +++ b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/3.0.0.yml @@ -0,0 +1,252 @@ +# 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: TERCC +_description: |- + The EiffelTestExecutionRecipeCollectionCreatedEvent declares that a collection of test execution recipes has been created. In order to clarify what that means, several concepts need to be explained. + + Just as Eiffel is an opinionated protocol, EiffelTestExecutionRecipeCollectionCreatedEvent is an opinionated event, and to a certain extent that opinion goes against the grain of traditional test management. This event assumes that activity configurations and test scope definitions are two separate things. To exemplify, when one's CI server triggers the Acceptance Test activity in the pipeline, there is nothing in that activity that says which tests to execute where or with what parameters: that is a separate concern. Instead, it will query a test selection service for that information. This information is encapsulated by the EiffelTestExecutionRecipeCollectionCreatedEvent, which contains all the information needed to configure and execute the tests. + + How the test selection service generates the recipe collection is, from the point of view of the Eiffel protocol, irrelevant. It may very well be from a statically defined list of test cases, or from an elaborate test selection algorithm weighing together a host of factors to determine the optimal set of test cases to execute at any particular time, or a combination of the two. + + The __data__ object consists of two main parts. __data.selectionStrategy__ identifies the strategy used to select the test cases and generate the recipe collection, while __data.batches__ or __data.batchesUri__ contain or reference, respectively, the recipes. The recipes are grouped in batches, which are used to control the order of execution of test cases. Every batch has a priority to let the test executor order them in sequence, but within each batch no assumptions are made as to the execution order the test cases. This way the recipe collection can either allow the executor a high degree of freedom in scheduling the test executions, and/or prescribe the exact sequential order in which they must be executed. Each event SHALL include one and only one of __data.batches__ and __data.batchesUri__. + + Finally, each recipe (__data.batches.recipes__) consists of two parts: the test case to execute, and the constraints of that execution. The EiffelTestExecutionRecipeCollectionCreatedEvent does not control the syntax of these constraints, as the nature of such constraints are highly dependent on technology domain and test execution framework. That being said, there are three questions that typically need to be answered: what is the item under test, in what kind of environment is it to be tested, and what are the test parameters? Note the distinction between test case and test execution: it is perfectly legal for a single test case to appear multiple times within the same EiffelTestExecutionRecipeCollectionCreatedEvent, but (presumably) with different constraints. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + selectionStrategy: + _description: The strategy used to select the test cases and + generate the recipe collection. + type: object + properties: + tracker: + _description: The name of the selection strategy that generated + the test execution recipe collection. + type: string + id: + _description: The unique identity of the selection strategy + that generated the test execution recipe collection. + type: string + uri: + _description: The URI at which the the selection strategy + that generated the test execution recipe collection can + be retrieved. + type: string + required: + - id + additionalProperties: false + batchesUri: + _description: 'A URI at which at which the array of test execution + batches can be fetched. The format of the document at this + URI SHALL be on the format prescribed by __data.batches__ + (i.e. ``` [ { "name": "Batch 1", ...}, {...}] ```). Each + event SHALL include one and only one of __data.batches__ + and __data.batchesUri__.' + type: string + batches: + _description: A list of batches of recipes. Each event SHALL + include one and only one of __data.batches__ and __data.batchesUri__. + In the interest of keeping message sizes small, it is recommended + to use __data.batches__ only for limited numbers of test + cases (on the order of ten executions). For larger numbers + of executions, __data.batchesUri__ SHOULD be used instead. + type: array + items: + type: object + properties: + name: + _description: The name of the recipe batch. + type: string + priority: + _description: The execution priority of the batch, as + compared to other batches in the collection. A lower + value SHALL be interpreted as a higher priority. + type: integer + recipes: + _description: The collection of test execution recipes + within the batch. + type: array + items: + type: object + properties: + id: + _description: A UUID identifying the unique execution. + Note that this is different from the id of a + test case, in two ways. First, a test case is + a (presumably) persistnent entity, whereas an + execution is transient in nature. Second, a test + case may be executed any number of times in any + given recipe collection. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + testCase: + _description: The test case to be executed in this + execution recipe. + type: object + properties: + tracker: + _description: The name of the test case tracker + - typically a test management system. + type: string + id: + _description: The unique identity of the test + case. + type: string + uri: + _description: A location where a description + of the test case can be retrieved. + type: string + required: + - id + additionalProperties: false + constraints: + _description: 'Any constraints of the execution. + The nature of such constraints is highly dependent + on technology domain and test execution framework. + Consequently, there are no pre-defined or required + constraints. Instead, this property is a list + of key-value pairs on the same format as [data.customData](../customization/custom-data.md). + That being said, there are three questions that + typically need to be answered: what is the item + under test, in what kind of environment is it + to be tested, and what are the test parameters?' + type: array + items: + type: object + properties: + key: + _description: The key name of constraint. + type: string + value: + _description: The value of the constraint. + required: + - key + - value + additionalProperties: false + required: + - id + - testCase + additionalProperties: false + dependencies: + _description: A list of test case execution dependencies. + Ideally, test cases are atomic and can be executed + in isolation. In cases where a test case assumes that + another test case has been executed previously in the + same environment, however, this property can be used + to specify that. It serves as an instruction to the + test executor to place two executions subsequent to + one another in the same environment. + type: array + items: + type: object + properties: + dependent: + _description: The UUID of the dependent execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed only after that of the + dependency. + type: string + dependency: + _description: The UUID of the dependency execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed prior to that of the + dependent. + type: string + required: + - dependent + - dependency + additionalProperties: false + required: + - priority + - recipes + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - selectionStrategy + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.0.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 3.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 2.0.0 + introduced_in: '[f92e001](../../../blob/f92e001c88d1139a62f8ace976958e0a30d8f9c5/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Changed syntax of data.batches.recipes.constraints from + an uncontrolled object to a list of key-value pairs to comply + with design guidelines. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Example using data.batches + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches.json + - title: Example using data.batches (1.0.0 syntax) + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches-1.0.0.json + - title: Example using data.batchesUri + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batchesUri.json diff --git a/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.0.0.yml b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.0.0.yml new file mode 100644 index 00000000..e45c294f --- /dev/null +++ b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.0.0.yml @@ -0,0 +1,255 @@ +# 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: TERCC +_description: |- + The EiffelTestExecutionRecipeCollectionCreatedEvent declares that a collection of test execution recipes has been created. In order to clarify what that means, several concepts need to be explained. + + Just as Eiffel is an opinionated protocol, EiffelTestExecutionRecipeCollectionCreatedEvent is an opinionated event, and to a certain extent that opinion goes against the grain of traditional test management. This event assumes that activity configurations and test scope definitions are two separate things. To exemplify, when one's CI server triggers the Acceptance Test activity in the pipeline, there is nothing in that activity that says which tests to execute where or with what parameters: that is a separate concern. Instead, it will query a test selection service for that information. This information is encapsulated by the EiffelTestExecutionRecipeCollectionCreatedEvent, which contains all the information needed to configure and execute the tests. + + How the test selection service generates the recipe collection is, from the point of view of the Eiffel protocol, irrelevant. It may very well be from a statically defined list of test cases, or from an elaborate test selection algorithm weighing together a host of factors to determine the optimal set of test cases to execute at any particular time, or a combination of the two. + + The __data__ object consists of two main parts. __data.selectionStrategy__ identifies the strategy used to select the test cases and generate the recipe collection, while __data.batches__ or __data.batchesUri__ contain or reference, respectively, the recipes. The recipes are grouped in batches, which are used to control the order of execution of test cases. Every batch has a priority to let the test executor order them in sequence, but within each batch no assumptions are made as to the execution order the test cases. This way the recipe collection can either allow the executor a high degree of freedom in scheduling the test executions, and/or prescribe the exact sequential order in which they must be executed. Each event SHALL include one and only one of __data.batches__ and __data.batchesUri__. + + Finally, each recipe (__data.batches.recipes__) consists of two parts: the test case to execute, and the constraints of that execution. The EiffelTestExecutionRecipeCollectionCreatedEvent does not control the syntax of these constraints, as the nature of such constraints are highly dependent on technology domain and test execution framework. That being said, there are three questions that typically need to be answered: what is the item under test, in what kind of environment is it to be tested, and what are the test parameters? Note the distinction between test case and test execution: it is perfectly legal for a single test case to appear multiple times within the same EiffelTestExecutionRecipeCollectionCreatedEvent, but (presumably) with different constraints. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + selectionStrategy: + _description: The strategy used to select the test cases and + generate the recipe collection. + type: object + properties: + tracker: + _description: The name of the selection strategy that generated + the test execution recipe collection. + type: string + id: + _description: The unique identity of the selection strategy + that generated the test execution recipe collection. + type: string + uri: + _description: The URI at which the the selection strategy + that generated the test execution recipe collection can + be retrieved. + type: string + required: + - id + additionalProperties: false + batchesUri: + _description: 'A URI at which at which the array of test execution + batches can be fetched. The format of the document at this + URI SHALL be on the format prescribed by __data.batches__ + (i.e. ``` [ { "name": "Batch 1", ...}, {...}] ```). Each + event SHALL include one and only one of __data.batches__ + and __data.batchesUri__.' + type: string + batches: + _description: A list of batches of recipes. Each event SHALL + include one and only one of __data.batches__ and __data.batchesUri__. + In the interest of keeping message sizes small, it is recommended + to use __data.batches__ only for limited numbers of test + cases (on the order of ten executions). For larger numbers + of executions, __data.batchesUri__ SHOULD be used instead. + type: array + items: + type: object + properties: + name: + _description: The name of the recipe batch. + type: string + priority: + _description: The execution priority of the batch, as + compared to other batches in the collection. A lower + value SHALL be interpreted as a higher priority. + type: integer + recipes: + _description: The collection of test execution recipes + within the batch. + type: array + items: + type: object + properties: + id: + _description: A UUID identifying the unique execution. + Note that this is different from the id of a + test case, in two ways. First, a test case is + a (presumably) persistnent entity, whereas an + execution is transient in nature. Second, a test + case may be executed any number of times in any + given recipe collection. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + testCase: + _description: The test case to be executed in this + execution recipe. + type: object + properties: + tracker: + _description: The name of the test case tracker + - typically a test management system. + type: string + id: + _description: The unique identity of the test + case. + type: string + uri: + _description: A location where a description + of the test case can be retrieved. + type: string + required: + - id + additionalProperties: false + constraints: + _description: 'Any constraints of the execution. + The nature of such constraints is highly dependent + on technology domain and test execution framework. + Consequently, there are no pre-defined or required + constraints. Instead, this property is a list + of key-value pairs on the same format as [data.customData](../customization/custom-data.md). + That being said, there are three questions that + typically need to be answered: what is the item + under test, in what kind of environment is it + to be tested, and what are the test parameters?' + type: array + items: + type: object + properties: + key: + _description: The key name of constraint. + type: string + value: + _description: The value of the constraint. + required: + - key + - value + additionalProperties: false + required: + - id + - testCase + additionalProperties: false + dependencies: + _description: A list of test case execution dependencies. + Ideally, test cases are atomic and can be executed + in isolation. In cases where a test case assumes that + another test case has been executed previously in the + same environment, however, this property can be used + to specify that. It serves as an instruction to the + test executor to place two executions subsequent to + one another in the same environment. + type: array + items: + type: object + properties: + dependent: + _description: The UUID of the dependent execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed only after that of the + dependency. + type: string + dependency: + _description: The UUID of the dependency execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed prior to that of the + dependent. + type: string + required: + - dependent + - dependency + additionalProperties: false + required: + - priority + - recipes + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - selectionStrategy + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.0.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 4.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 3.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 2.0.0 + introduced_in: '[f92e001](../../../blob/f92e001c88d1139a62f8ace976958e0a30d8f9c5/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Changed syntax of data.batches.recipes.constraints from + an uncontrolled object to a list of key-value pairs to comply + with design guidelines. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Example using data.batches + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches.json + - title: Example using data.batches (1.0.0 syntax) + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches-1.0.0.json + - title: Example using data.batchesUri + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batchesUri.json diff --git a/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.1.0.yml b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.1.0.yml new file mode 100644 index 00000000..54d4cc5f --- /dev/null +++ b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.1.0.yml @@ -0,0 +1,258 @@ +# 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: TERCC +_description: |- + The EiffelTestExecutionRecipeCollectionCreatedEvent declares that a collection of test execution recipes has been created. In order to clarify what that means, several concepts need to be explained. + + Just as Eiffel is an opinionated protocol, EiffelTestExecutionRecipeCollectionCreatedEvent is an opinionated event, and to a certain extent that opinion goes against the grain of traditional test management. This event assumes that activity configurations and test scope definitions are two separate things. To exemplify, when one's CI server triggers the Acceptance Test activity in the pipeline, there is nothing in that activity that says which tests to execute where or with what parameters: that is a separate concern. Instead, it will query a test selection service for that information. This information is encapsulated by the EiffelTestExecutionRecipeCollectionCreatedEvent, which contains all the information needed to configure and execute the tests. + + How the test selection service generates the recipe collection is, from the point of view of the Eiffel protocol, irrelevant. It may very well be from a statically defined list of test cases, or from an elaborate test selection algorithm weighing together a host of factors to determine the optimal set of test cases to execute at any particular time, or a combination of the two. + + The __data__ object consists of two main parts. __data.selectionStrategy__ identifies the strategy used to select the test cases and generate the recipe collection, while __data.batches__ or __data.batchesUri__ contain or reference, respectively, the recipes. The recipes are grouped in batches, which are used to control the order of execution of test cases. Every batch has a priority to let the test executor order them in sequence, but within each batch no assumptions are made as to the execution order the test cases. This way the recipe collection can either allow the executor a high degree of freedom in scheduling the test executions, and/or prescribe the exact sequential order in which they must be executed. Each event SHALL include one and only one of __data.batches__ and __data.batchesUri__. + + Finally, each recipe (__data.batches.recipes__) consists of two parts: the test case to execute, and the constraints of that execution. The EiffelTestExecutionRecipeCollectionCreatedEvent does not control the syntax of these constraints, as the nature of such constraints are highly dependent on technology domain and test execution framework. That being said, there are three questions that typically need to be answered: what is the item under test, in what kind of environment is it to be tested, and what are the test parameters? Note the distinction between test case and test execution: it is perfectly legal for a single test case to appear multiple times within the same EiffelTestExecutionRecipeCollectionCreatedEvent, but (presumably) with different constraints. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + selectionStrategy: + _description: The strategy used to select the test cases and + generate the recipe collection. + type: object + properties: + tracker: + _description: The name of the selection strategy that generated + the test execution recipe collection. + type: string + id: + _description: The unique identity of the selection strategy + that generated the test execution recipe collection. + type: string + uri: + _description: The URI at which the the selection strategy + that generated the test execution recipe collection can + be retrieved. + type: string + required: + - id + additionalProperties: false + batchesUri: + _description: 'A URI at which at which the array of test execution + batches can be fetched. The format of the document at this + URI SHALL be on the format prescribed by __data.batches__ + (i.e. ``` [ { "name": "Batch 1", ...}, {...}] ```). Each + event SHALL include one and only one of __data.batches__ + and __data.batchesUri__.' + type: string + batches: + _description: A list of batches of recipes. Each event SHALL + include one and only one of __data.batches__ and __data.batchesUri__. + In the interest of keeping message sizes small, it is recommended + to use __data.batches__ only for limited numbers of test + cases (on the order of ten executions). For larger numbers + of executions, __data.batchesUri__ SHOULD be used instead. + type: array + items: + type: object + properties: + name: + _description: The name of the recipe batch. + type: string + priority: + _description: The execution priority of the batch, as + compared to other batches in the collection. A lower + value SHALL be interpreted as a higher priority. + type: integer + recipes: + _description: The collection of test execution recipes + within the batch. + type: array + items: + type: object + properties: + id: + _description: A UUID identifying the unique execution. + Note that this is different from the id of a + test case, in two ways. First, a test case is + a (presumably) persistnent entity, whereas an + execution is transient in nature. Second, a test + case may be executed any number of times in any + given recipe collection. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + testCase: + _description: The test case to be executed in this + execution recipe. + type: object + properties: + tracker: + _description: The name of the test case tracker + - typically a test management system. + type: string + id: + _description: The unique identity of the test + case. + type: string + uri: + _description: A location where a description + of the test case can be retrieved. + type: string + required: + - id + additionalProperties: false + constraints: + _description: 'Any constraints of the execution. + The nature of such constraints is highly dependent + on technology domain and test execution framework. + Consequently, there are no pre-defined or required + constraints. Instead, this property is a list + of key-value pairs on the same format as [data.customData](../customization/custom-data.md). + That being said, there are three questions that + typically need to be answered: what is the item + under test, in what kind of environment is it + to be tested, and what are the test parameters?' + type: array + items: + type: object + properties: + key: + _description: The key name of constraint. + type: string + value: + _description: The value of the constraint. + required: + - key + - value + additionalProperties: false + required: + - id + - testCase + additionalProperties: false + dependencies: + _description: A list of test case execution dependencies. + Ideally, test cases are atomic and can be executed + in isolation. In cases where a test case assumes that + another test case has been executed previously in the + same environment, however, this property can be used + to specify that. It serves as an instruction to the + test executor to place two executions subsequent to + one another in the same environment. + type: array + items: + type: object + properties: + dependent: + _description: The UUID of the dependent execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed only after that of the + dependency. + type: string + dependency: + _description: The UUID of the dependency execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed prior to that of the + dependent. + type: string + required: + - dependent + - dependency + additionalProperties: false + required: + - priority + - recipes + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - selectionStrategy + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.0.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 4.1.0 + introduced_in: Current version + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 4.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 3.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 2.0.0 + introduced_in: '[f92e001](../../../blob/f92e001c88d1139a62f8ace976958e0a30d8f9c5/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Changed syntax of data.batches.recipes.constraints from + an uncontrolled object to a list of key-value pairs to comply + with design guidelines. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Example using data.batches + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches.json + - title: Example using data.batches (1.0.0 syntax) + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches-1.0.0.json + - title: Example using data.batchesUri + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batchesUri.json diff --git a/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.1.1.yml b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.1.1.yml new file mode 100644 index 00000000..d9b9145d --- /dev/null +++ b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.1.1.yml @@ -0,0 +1,262 @@ +# 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: TERCC +_description: |- + The EiffelTestExecutionRecipeCollectionCreatedEvent declares that a collection of test execution recipes has been created. In order to clarify what that means, several concepts need to be explained. + + Just as Eiffel is an opinionated protocol, EiffelTestExecutionRecipeCollectionCreatedEvent is an opinionated event, and to a certain extent that opinion goes against the grain of traditional test management. This event assumes that activity configurations and test scope definitions are two separate things. To exemplify, when one's CI server triggers the Acceptance Test activity in the pipeline, there is nothing in that activity that says which tests to execute where or with what parameters: that is a separate concern. Instead, it will query a test selection service for that information. This information is encapsulated by the EiffelTestExecutionRecipeCollectionCreatedEvent, which contains all the information needed to configure and execute the tests. + + How the test selection service generates the recipe collection is, from the point of view of the Eiffel protocol, irrelevant. It may very well be from a statically defined list of test cases, or from an elaborate test selection algorithm weighing together a host of factors to determine the optimal set of test cases to execute at any particular time, or a combination of the two. + + The __data__ object consists of two main parts. __data.selectionStrategy__ identifies the strategy used to select the test cases and generate the recipe collection, while __data.batches__ or __data.batchesUri__ contain or reference, respectively, the recipes. The recipes are grouped in batches, which are used to control the order of execution of test cases. Every batch has a priority to let the test executor order them in sequence, but within each batch no assumptions are made as to the execution order the test cases. This way the recipe collection can either allow the executor a high degree of freedom in scheduling the test executions, and/or prescribe the exact sequential order in which they must be executed. Each event SHALL include one and only one of __data.batches__ and __data.batchesUri__. + + Finally, each recipe (__data.batches.recipes__) consists of two parts: the test case to execute, and the constraints of that execution. The EiffelTestExecutionRecipeCollectionCreatedEvent does not control the syntax of these constraints, as the nature of such constraints are highly dependent on technology domain and test execution framework. That being said, there are three questions that typically need to be answered: what is the item under test, in what kind of environment is it to be tested, and what are the test parameters? Note the distinction between test case and test execution: it is perfectly legal for a single test case to appear multiple times within the same EiffelTestExecutionRecipeCollectionCreatedEvent, but (presumably) with different constraints. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + selectionStrategy: + _description: The strategy used to select the test cases and + generate the recipe collection. + type: object + properties: + tracker: + _description: The name of the selection strategy that generated + the test execution recipe collection. + type: string + id: + _description: The unique identity of the selection strategy + that generated the test execution recipe collection. + type: string + uri: + _description: The URI at which the the selection strategy + that generated the test execution recipe collection can + be retrieved. + type: string + required: + - id + additionalProperties: false + batchesUri: + _description: 'A URI at which at which the array of test execution + batches can be fetched. The format of the document at this + URI SHALL be on the format prescribed by __data.batches__ + (i.e. ``` [ { "name": "Batch 1", ...}, {...}] ```). Each + event SHALL include one and only one of __data.batches__ + and __data.batchesUri__.' + type: string + batches: + _description: A list of batches of recipes. Each event SHALL + include one and only one of __data.batches__ and __data.batchesUri__. + In the interest of keeping message sizes small, it is recommended + to use __data.batches__ only for limited numbers of test + cases (on the order of ten executions). For larger numbers + of executions, __data.batchesUri__ SHOULD be used instead. + type: array + items: + type: object + properties: + name: + _description: The name of the recipe batch. + type: string + priority: + _description: The execution priority of the batch, as + compared to other batches in the collection. A lower + value SHALL be interpreted as a higher priority. + type: integer + recipes: + _description: The collection of test execution recipes + within the batch. + type: array + items: + type: object + properties: + id: + _description: A UUID identifying the unique execution. + Note that this is different from the id of a + test case, in two ways. First, a test case is + a (presumably) persistnent entity, whereas an + execution is transient in nature. Second, a test + case may be executed any number of times in any + given recipe collection. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + testCase: + _description: The test case to be executed in this + execution recipe. + type: object + properties: + tracker: + _description: The name of the test case tracker + - typically a test management system. + type: string + id: + _description: The unique identity of the test + case. + type: string + uri: + _description: A location where a description + of the test case can be retrieved. + type: string + required: + - id + additionalProperties: false + constraints: + _description: 'Any constraints of the execution. + The nature of such constraints is highly dependent + on technology domain and test execution framework. + Consequently, there are no pre-defined or required + constraints. Instead, this property is a list + of key-value pairs on the same format as [data.customData](../customization/custom-data.md). + That being said, there are three questions that + typically need to be answered: what is the item + under test, in what kind of environment is it + to be tested, and what are the test parameters?' + type: array + items: + type: object + properties: + key: + _description: The key name of constraint. + type: string + value: + _description: The value of the constraint. + required: + - key + - value + additionalProperties: false + required: + - id + - testCase + additionalProperties: false + dependencies: + _description: A list of test case execution dependencies. + Ideally, test cases are atomic and can be executed + in isolation. In cases where a test case assumes that + another test case has been executed previously in the + same environment, however, this property can be used + to specify that. It serves as an instruction to the + test executor to place two executions subsequent to + one another in the same environment. + type: array + items: + type: object + properties: + dependent: + _description: The UUID of the dependent execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed only after that of the + dependency. + type: string + dependency: + _description: The UUID of the dependency execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed prior to that of the + dependent. + type: string + required: + - dependent + - dependency + additionalProperties: false + required: + - priority + - recipes + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - selectionStrategy + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 4.1.1 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add missing validation pattern to links.target member + (see [Issue 271](https://github.com/eiffel-community/eiffel/issues/271)). + - version: 4.1.0 + introduced_in: No edition set + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 4.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 3.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 2.0.0 + introduced_in: '[f92e001](../../../blob/f92e001c88d1139a62f8ace976958e0a30d8f9c5/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Changed syntax of data.batches.recipes.constraints from + an uncontrolled object to a list of key-value pairs to comply + with design guidelines. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Example using data.batches + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches.json + - title: Example using data.batches (1.0.0 syntax) + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches-1.0.0.json + - title: Example using data.batchesUri + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batchesUri.json diff --git a/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.2.0.yml b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.2.0.yml new file mode 100644 index 00000000..3d3e5ef6 --- /dev/null +++ b/definitions/EiffelTestExecutionRecipeCollectionCreatedEvent/4.2.0.yml @@ -0,0 +1,275 @@ +# 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: TERCC +_description: |- + The EiffelTestExecutionRecipeCollectionCreatedEvent declares that a collection of test execution recipes has been created. In order to clarify what that means, several concepts need to be explained. + + Just as Eiffel is an opinionated protocol, EiffelTestExecutionRecipeCollectionCreatedEvent is an opinionated event, and to a certain extent that opinion goes against the grain of traditional test management. This event assumes that activity configurations and test scope definitions are two separate things. To exemplify, when one's CI server triggers the Acceptance Test activity in the pipeline, there is nothing in that activity that says which tests to execute where or with what parameters: that is a separate concern. Instead, it will query a test selection service for that information. This information is encapsulated by the EiffelTestExecutionRecipeCollectionCreatedEvent, which contains all the information needed to configure and execute the tests. + + How the test selection service generates the recipe collection is, from the point of view of the Eiffel protocol, irrelevant. It may very well be from a statically defined list of test cases, or from an elaborate test selection algorithm weighing together a host of factors to determine the optimal set of test cases to execute at any particular time, or a combination of the two. + + The __data__ object consists of two main parts. __data.selectionStrategy__ identifies the strategy used to select the test cases and generate the recipe collection, while __data.batches__ or __data.batchesUri__ contain or reference, respectively, the recipes. The recipes are grouped in batches, which are used to control the order of execution of test cases. Every batch has a priority to let the test executor order them in sequence, but within each batch no assumptions are made as to the execution order the test cases. This way the recipe collection can either allow the executor a high degree of freedom in scheduling the test executions, and/or prescribe the exact sequential order in which they must be executed. Each event SHALL include one and only one of __data.batches__ and __data.batchesUri__. + + Finally, each recipe (__data.batches.recipes__) consists of two parts: the test case to execute, and the constraints of that execution. The EiffelTestExecutionRecipeCollectionCreatedEvent does not control the syntax of these constraints, as the nature of such constraints are highly dependent on technology domain and test execution framework. That being said, there are three questions that typically need to be answered: what is the item under test, in what kind of environment is it to be tested, and what are the test parameters? Note the distinction between test case and test execution: it is perfectly legal for a single test case to appear multiple times within the same EiffelTestExecutionRecipeCollectionCreatedEvent, but (presumably) with different constraints. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + selectionStrategy: + _description: The strategy used to select the test cases and + generate the recipe collection. + type: object + properties: + tracker: + _description: The name of the selection strategy that generated + the test execution recipe collection. + type: string + id: + _description: The unique identity of the selection strategy + that generated the test execution recipe collection. + type: string + uri: + _description: The URI at which the the selection strategy + that generated the test execution recipe collection can + be retrieved. + type: string + required: + - id + additionalProperties: false + batchesUri: + _description: 'A URI at which at which the array of test execution + batches can be fetched. The format of the document at this + URI SHALL be on the format prescribed by __data.batches__ + (i.e. ``` [ { "name": "Batch 1", ...}, {...}] ```). Each + event SHALL include one and only one of __data.batches__ + and __data.batchesUri__.' + type: string + batches: + _description: A list of batches of recipes. Each event SHALL + include one and only one of __data.batches__ and __data.batchesUri__. + In the interest of keeping message sizes small, it is recommended + to use __data.batches__ only for limited numbers of test + cases (on the order of ten executions). For larger numbers + of executions, __data.batchesUri__ SHOULD be used instead. + type: array + items: + type: object + properties: + name: + _description: The name of the recipe batch. + type: string + priority: + _description: The execution priority of the batch, as + compared to other batches in the collection. A lower + value SHALL be interpreted as a higher priority. + type: integer + recipes: + _description: The collection of test execution recipes + within the batch. + type: array + items: + type: object + properties: + id: + _description: A UUID identifying the unique execution. + Note that this is different from the id of a + test case, in two ways. First, a test case is + a (presumably) persistnent entity, whereas an + execution is transient in nature. Second, a test + case may be executed any number of times in any + given recipe collection. + type: string + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + testCase: + _description: The test case to be executed in this + execution recipe. + type: object + properties: + tracker: + _description: The name of the test case tracker + - typically a test management system. + type: string + id: + _description: The unique identity of the test + case to be executed. + type: string + version: + _description: The unique version of the identified + test case to be executed. Where this property + is not used it is assumed that test cases + are not version controlled. + type: string + uri: + _description: A location where a description + of the test case can be retrieved. To the + extent that multiple versions of the same + test case co-exist, this property SHALL identify + the exact version to be executed. + type: string + required: + - id + additionalProperties: false + constraints: + _description: 'Any constraints of the execution. + The nature of such constraints is highly dependent + on technology domain and test execution framework. + Consequently, there are no pre-defined or required + constraints. Instead, this property is a list + of key-value pairs on the same format as [data.customData](../customization/custom-data.md). + That being said, there are three questions that + typically need to be answered: what is the item + under test, in what kind of environment is it + to be tested, and what are the test parameters?' + type: array + items: + type: object + properties: + key: + _description: The key name of constraint. + type: string + value: + _description: The value of the constraint. + required: + - key + - value + additionalProperties: false + required: + - id + - testCase + additionalProperties: false + dependencies: + _description: A list of test case execution dependencies. + Ideally, test cases are atomic and can be executed + in isolation. In cases where a test case assumes that + another test case has been executed previously in the + same environment, however, this property can be used + to specify that. It serves as an instruction to the + test executor to place two executions subsequent to + one another in the same environment. + type: array + items: + type: object + properties: + dependent: + _description: The UUID of the dependent execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed only after that of the + dependency. + type: string + dependency: + _description: The UUID of the dependency execution + (__data.batches.recipes.id__), i.e. the execution + that shall be performed prior to that of the + dependent. + type: string + required: + - dependent + - dependency + additionalProperties: false + required: + - priority + - recipes + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - selectionStrategy + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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: 4.2.0 + introduced_in: No edition set + changes: Add missing testCase.version member (see [Issue 288](https://github.com/eiffel-community/eiffel/issues/288)). + - version: 4.1.1 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add missing validation pattern to links.target member + (see [Issue 271](https://github.com/eiffel-community/eiffel/issues/271)). + - version: 4.1.0 + introduced_in: No edition set + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 4.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 3.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - version: 2.1.0 + introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)' + changes: Multiple links of type FLOW_CONTEXT allowed. + - version: 2.0.0 + introduced_in: '[f92e001](../../../blob/f92e001c88d1139a62f8ace976958e0a30d8f9c5/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)' + changes: Changed syntax of data.batches.recipes.constraints from + an uncontrolled object to a list of key-value pairs to comply + with design guidelines. + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Example using data.batches + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches.json + - title: Example using data.batches (1.0.0 syntax) + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches-1.0.0.json + - title: Example using data.batchesUri + url: ../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batchesUri.json diff --git a/definitions/EiffelTestSuiteFinishedEvent/1.0.0.yml b/definitions/EiffelTestSuiteFinishedEvent/1.0.0.yml new file mode 100644 index 00000000..61b8756a --- /dev/null +++ b/definitions/EiffelTestSuiteFinishedEvent/1.0.0.yml @@ -0,0 +1,144 @@ +# 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: TSF +_description: |- + The EiffelTestSuiteFinishedEvent declares that a previously started test suite (declared by [EiffelTestSuiteStartedEvent](./EiffelTestSuiteStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test suite reports not only the conclusion of the test suite execution - whether the tests were successfully executed - but also passes a verdict on the item or items under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test suite. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the verdict of the test suite as a whole, but may be skipped. + PASSED signifies that the item or items under test successfully passed the test suite. + FAILED signifies that the item or items under test failed to pass the test suite. + INCONCLUSIVE signifies that the verdict of the test suite was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test suite, designed to be machine readable. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the conclusion of the test suite as a whole, but may be skipped. + SUCCESSFUL signifies that the test suite was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test suite could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test suite was aborted before it could be concluded. + TIMED_OUT signifies that the test suite did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test suite could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test suite outcome, + designed to provide human readers with further information. + type: string + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_SUITE_EXECUTION: + description: Identifies the relevant test suite execution. In other + words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) + acts as a handle for a particular test suite execution. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelTestSuiteStartedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestSuiteFinishedEvent/simple.json diff --git a/definitions/EiffelTestSuiteFinishedEvent/1.1.0.yml b/definitions/EiffelTestSuiteFinishedEvent/1.1.0.yml new file mode 100644 index 00000000..af5ac1de --- /dev/null +++ b/definitions/EiffelTestSuiteFinishedEvent/1.1.0.yml @@ -0,0 +1,147 @@ +# 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: TSF +_description: |- + The EiffelTestSuiteFinishedEvent declares that a previously started test suite (declared by [EiffelTestSuiteStartedEvent](./EiffelTestSuiteStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test suite reports not only the conclusion of the test suite execution - whether the tests were successfully executed - but also passes a verdict on the item or items under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test suite. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the verdict of the test suite as a whole, but may be skipped. + PASSED signifies that the item or items under test successfully passed the test suite. + FAILED signifies that the item or items under test failed to pass the test suite. + INCONCLUSIVE signifies that the verdict of the test suite was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test suite, designed to be machine readable. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the conclusion of the test suite as a whole, but may be skipped. + SUCCESSFUL signifies that the test suite was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test suite could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test suite was aborted before it could be concluded. + TIMED_OUT signifies that the test suite did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test suite could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test suite outcome, + designed to provide human readers with further information. + type: string + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_SUITE_EXECUTION: + description: Identifies the relevant test suite execution. In other + words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) + acts as a handle for a particular test suite execution. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelTestSuiteStartedEvent +_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/EiffelTestSuiteFinishedEvent/simple.json diff --git a/definitions/EiffelTestSuiteFinishedEvent/2.0.0.yml b/definitions/EiffelTestSuiteFinishedEvent/2.0.0.yml new file mode 100644 index 00000000..ad5248dd --- /dev/null +++ b/definitions/EiffelTestSuiteFinishedEvent/2.0.0.yml @@ -0,0 +1,151 @@ +# 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: TSF +_description: |- + The EiffelTestSuiteFinishedEvent declares that a previously started test suite (declared by [EiffelTestSuiteStartedEvent](./EiffelTestSuiteStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test suite reports not only the conclusion of the test suite execution - whether the tests were successfully executed - but also passes a verdict on the item or items under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test suite. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the verdict of the test suite as a whole, but may be skipped. + PASSED signifies that the item or items under test successfully passed the test suite. + FAILED signifies that the item or items under test failed to pass the test suite. + INCONCLUSIVE signifies that the verdict of the test suite was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test suite, designed to be machine readable. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the conclusion of the test suite as a whole, but may be skipped. + SUCCESSFUL signifies that the test suite was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test suite could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test suite was aborted before it could be concluded. + TIMED_OUT signifies that the test suite did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test suite could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test suite outcome, + designed to provide human readers with further information. + type: string + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_SUITE_EXECUTION: + description: Identifies the relevant test suite execution. In other + words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) + acts as a handle for a particular test suite execution. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelTestSuiteStartedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestSuiteFinishedEvent/simple.json diff --git a/definitions/EiffelTestSuiteFinishedEvent/3.0.0.yml b/definitions/EiffelTestSuiteFinishedEvent/3.0.0.yml new file mode 100644 index 00000000..adf20497 --- /dev/null +++ b/definitions/EiffelTestSuiteFinishedEvent/3.0.0.yml @@ -0,0 +1,154 @@ +# 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: TSF +_description: |- + The EiffelTestSuiteFinishedEvent declares that a previously started test suite (declared by [EiffelTestSuiteStartedEvent](./EiffelTestSuiteStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test suite reports not only the conclusion of the test suite execution - whether the tests were successfully executed - but also passes a verdict on the item or items under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test suite. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the verdict of the test suite as a whole, but may be skipped. + PASSED signifies that the item or items under test successfully passed the test suite. + FAILED signifies that the item or items under test failed to pass the test suite. + INCONCLUSIVE signifies that the verdict of the test suite was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test suite, designed to be machine readable. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the conclusion of the test suite as a whole, but may be skipped. + SUCCESSFUL signifies that the test suite was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test suite could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test suite was aborted before it could be concluded. + TIMED_OUT signifies that the test suite did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test suite could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test suite outcome, + designed to provide human readers with further information. + type: string + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_SUITE_EXECUTION: + description: Identifies the relevant test suite execution. In other + words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) + acts as a handle for a particular test suite execution. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelTestSuiteStartedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestSuiteFinishedEvent/simple.json diff --git a/definitions/EiffelTestSuiteFinishedEvent/3.1.0.yml b/definitions/EiffelTestSuiteFinishedEvent/3.1.0.yml new file mode 100644 index 00000000..31c2e77c --- /dev/null +++ b/definitions/EiffelTestSuiteFinishedEvent/3.1.0.yml @@ -0,0 +1,170 @@ +# 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: TSF +_description: |- + The EiffelTestSuiteFinishedEvent declares that a previously started test suite (declared by [EiffelTestSuiteStartedEvent](./EiffelTestSuiteStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test suite reports not only the conclusion of the test suite execution - whether the tests were successfully executed - but also passes a verdict on the item or items under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test suite. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the verdict of the test suite as a whole, but may be skipped. + PASSED signifies that the item or items under test successfully passed the test suite. + FAILED signifies that the item or items under test failed to pass the test suite. + INCONCLUSIVE signifies that the verdict of the test suite was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test suite, designed to be machine readable. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the conclusion of the test suite as a whole, but may be skipped. + SUCCESSFUL signifies that the test suite was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test suite could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test suite was aborted before it could be concluded. + TIMED_OUT signifies that the test suite did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test suite could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test suite outcome, + designed to provide human readers with further information. + type: string + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + 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 +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_SUITE_EXECUTION: + description: Identifies the relevant test suite execution. In other + words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) + acts as a handle for a particular test suite execution. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelTestSuiteStartedEvent +_history: + - version: 3.1.0 + introduced_in: Current version + changes: Add `data.persistentLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestSuiteFinishedEvent/simple.json diff --git a/definitions/EiffelTestSuiteFinishedEvent/3.2.0.yml b/definitions/EiffelTestSuiteFinishedEvent/3.2.0.yml new file mode 100644 index 00000000..d5a93ec2 --- /dev/null +++ b/definitions/EiffelTestSuiteFinishedEvent/3.2.0.yml @@ -0,0 +1,174 @@ +# 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: TSF +_description: |- + The EiffelTestSuiteFinishedEvent declares that a previously started test suite (declared by [EiffelTestSuiteStartedEvent](./EiffelTestSuiteStartedEvent.md)) has finished and reports the outcome. + + Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test suite reports not only the conclusion of the test suite execution - whether the tests were successfully executed - but also passes a verdict on the item or items under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + outcome: + _description: The outcome of the test suite. + type: object + properties: + verdict: + _description: |- + A terse standardized verdict on the item or items under test. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the verdict of the test suite as a whole, but may be skipped. + PASSED signifies that the item or items under test successfully passed the test suite. + FAILED signifies that the item or items under test failed to pass the test suite. + INCONCLUSIVE signifies that the verdict of the test suite was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. + type: string + enum: + - PASSED + - FAILED + - INCONCLUSIVE + conclusion: + _description: |- + A terse standardized conclusion of the test suite, designed to be machine readable. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the conclusion of the test suite as a whole, but may be skipped. + SUCCESSFUL signifies that the test suite was successfully concluded. Note that this does not imply that the item under test passed the tests. + FAILED signifies that the test suite could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. + ABORTED signifies that the test suite was aborted before it could be concluded. + TIMED_OUT signifies that the test suite did not conclude within the allowed time frame. + INCONCLUSIVE signifies that the outcome of the test suite could not be determined. + type: string + enum: + - SUCCESSFUL + - FAILED + - ABORTED + - TIMED_OUT + - INCONCLUSIVE + description: + _description: A verbose description of the test suite outcome, + designed to provide human readers with further information. + type: string + additionalProperties: false + persistentLogs: + _description: An array of persistent log files generated during + execution. + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TEST_SUITE_EXECUTION: + description: Identifies the relevant test suite execution. In other + words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) + acts as a handle for a particular test suite execution. + required: true + multiple: false + targets: + any_type: false + types: + - EiffelTestSuiteStartedEvent +_history: + - version: 3.2.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.1.0 + introduced_in: No edition set + changes: Add `data.persistentLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestSuiteFinishedEvent/simple.json diff --git a/definitions/EiffelTestSuiteStartedEvent/1.0.0.yml b/definitions/EiffelTestSuiteStartedEvent/1.0.0.yml new file mode 100644 index 00000000..caa496bd --- /dev/null +++ b/definitions/EiffelTestSuiteStartedEvent/1.0.0.yml @@ -0,0 +1,151 @@ +# 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: TSS +_description: |- + The EiffelTestSuiteStartedEvent declares that the execution of a test suite has started. This can either be declared stand-alone or as part of an activity or other test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + In Eiffel, a test suite is nothing more or less than a collection of test case executions (see [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) and/or other test suite executions. The executed test suite may be an ad-hoc transient grouping of test cases that were executed at a particular time or place or for a particular purpose or a persistent entity tracked in a test management system - Eiffel makes no distinction or assumptions either way. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the test suite. Uniqueness is not + required or checked, but is useful. + type: string + categories: + _description: The category or categories of the test suite. + This can be used to group multiple similar test suites for + analysis and visualization purposes. Example usage is to + categorize test suites required before release as "Pre-release + tests". + type: array + items: + type: string + types: + _description: The type or types of testing performed by the + test suite, as [defined by ISO 29119](http://www.softwaretestingstandard.org). + type: array + items: + type: string + enum: + - ACCESSIBILITY + - BACKUP_RECOVERY + - COMPATIBILITY + - CONVERSION + - DISASTER_RECOVERY + - FUNCTIONAL + - INSTALLABILITY + - INTEROPERABILITY + - LOCALIZATION + - MAINTAINABILITY + - PERFORMANCE + - PORTABILITY + - PROCEDURE + - RELIABILITY + - SECURITY + - STABILITY + - USABILITY + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test suite has finished there is no + guarantee that these links are valid. Persistently stored + logs shall be (re-)declared by [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TERC: + description: This link signifies that the test suite represented + by this event groups all test case executions resulting from + the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). + required: false + multiple: false + targets: + any_type: false + types: + - EiffelTestExecutionRecipeCollectionCreatedEvent +_history: + - version: 1.0.0 + introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelTestSuiteStartedEvent/simple.json diff --git a/definitions/EiffelTestSuiteStartedEvent/1.1.0.yml b/definitions/EiffelTestSuiteStartedEvent/1.1.0.yml new file mode 100644 index 00000000..50417e1c --- /dev/null +++ b/definitions/EiffelTestSuiteStartedEvent/1.1.0.yml @@ -0,0 +1,154 @@ +# 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: TSS +_description: |- + The EiffelTestSuiteStartedEvent declares that the execution of a test suite has started. This can either be declared stand-alone or as part of an activity or other test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + In Eiffel, a test suite is nothing more or less than a collection of test case executions (see [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) and/or other test suite executions. The executed test suite may be an ad-hoc transient grouping of test cases that were executed at a particular time or place or for a particular purpose or a persistent entity tracked in a test management system - Eiffel makes no distinction or assumptions either way. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/1.0.0.yml + data: + type: object + properties: + name: + _description: The name of the test suite. Uniqueness is not + required or checked, but is useful. + type: string + categories: + _description: The category or categories of the test suite. + This can be used to group multiple similar test suites for + analysis and visualization purposes. Example usage is to + categorize test suites required before release as "Pre-release + tests". + type: array + items: + type: string + types: + _description: The type or types of testing performed by the + test suite, as [defined by ISO 29119](http://www.softwaretestingstandard.org). + type: array + items: + type: string + enum: + - ACCESSIBILITY + - BACKUP_RECOVERY + - COMPATIBILITY + - CONVERSION + - DISASTER_RECOVERY + - FUNCTIONAL + - INSTALLABILITY + - INTEROPERABILITY + - LOCALIZATION + - MAINTAINABILITY + - PERFORMANCE + - PORTABILITY + - PROCEDURE + - RELIABILITY + - SECURITY + - STABILITY + - USABILITY + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test suite has finished there is no + guarantee that these links are valid. Persistently stored + logs shall be (re-)declared by [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TERC: + description: This link signifies that the test suite represented + by this event groups all test case executions resulting from + the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). + required: false + multiple: false + targets: + any_type: false + types: + - EiffelTestExecutionRecipeCollectionCreatedEvent +_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/EiffelTestSuiteStartedEvent/simple.json diff --git a/definitions/EiffelTestSuiteStartedEvent/2.0.0.yml b/definitions/EiffelTestSuiteStartedEvent/2.0.0.yml new file mode 100644 index 00000000..ab47221a --- /dev/null +++ b/definitions/EiffelTestSuiteStartedEvent/2.0.0.yml @@ -0,0 +1,158 @@ +# 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: TSS +_description: |- + The EiffelTestSuiteStartedEvent declares that the execution of a test suite has started. This can either be declared stand-alone or as part of an activity or other test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + In Eiffel, a test suite is nothing more or less than a collection of test case executions (see [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) and/or other test suite executions. The executed test suite may be an ad-hoc transient grouping of test cases that were executed at a particular time or place or for a particular purpose or a persistent entity tracked in a test management system - Eiffel makes no distinction or assumptions either way. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/2.0.0.yml + data: + type: object + properties: + name: + _description: The name of the test suite. Uniqueness is not + required or checked, but is useful. + type: string + categories: + _description: The category or categories of the test suite. + This can be used to group multiple similar test suites for + analysis and visualization purposes. Example usage is to + categorize test suites required before release as "Pre-release + tests". + type: array + items: + type: string + types: + _description: The type or types of testing performed by the + test suite, as [defined by ISO 29119](http://www.softwaretestingstandard.org). + type: array + items: + type: string + enum: + - ACCESSIBILITY + - BACKUP_RECOVERY + - COMPATIBILITY + - CONVERSION + - DISASTER_RECOVERY + - FUNCTIONAL + - INSTALLABILITY + - INTEROPERABILITY + - LOCALIZATION + - MAINTAINABILITY + - PERFORMANCE + - PORTABILITY + - PROCEDURE + - RELIABILITY + - SECURITY + - STABILITY + - USABILITY + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test suite has finished there is no + guarantee that these links are valid. Persistently stored + logs shall be (re-)declared by [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TERC: + description: This link signifies that the test suite represented + by this event groups all test case executions resulting from + the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). + required: false + multiple: false + targets: + any_type: false + types: + - EiffelTestExecutionRecipeCollectionCreatedEvent +_history: + - version: 2.0.0 + introduced_in: Current version + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestSuiteStartedEvent/simple.json diff --git a/definitions/EiffelTestSuiteStartedEvent/3.0.0.yml b/definitions/EiffelTestSuiteStartedEvent/3.0.0.yml new file mode 100644 index 00000000..07e9129e --- /dev/null +++ b/definitions/EiffelTestSuiteStartedEvent/3.0.0.yml @@ -0,0 +1,161 @@ +# 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: TSS +_description: |- + The EiffelTestSuiteStartedEvent declares that the execution of a test suite has started. This can either be declared stand-alone or as part of an activity or other test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + In Eiffel, a test suite is nothing more or less than a collection of test case executions (see [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) and/or other test suite executions. The executed test suite may be an ad-hoc transient grouping of test cases that were executed at a particular time or place or for a particular purpose or a persistent entity tracked in a test management system - Eiffel makes no distinction or assumptions either way. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the test suite. Uniqueness is not + required or checked, but is useful. + type: string + categories: + _description: The category or categories of the test suite. + This can be used to group multiple similar test suites for + analysis and visualization purposes. Example usage is to + categorize test suites required before release as "Pre-release + tests". + type: array + items: + type: string + types: + _description: The type or types of testing performed by the + test suite, as [defined by ISO 29119](http://www.softwaretestingstandard.org). + type: array + items: + type: string + enum: + - ACCESSIBILITY + - BACKUP_RECOVERY + - COMPATIBILITY + - CONVERSION + - DISASTER_RECOVERY + - FUNCTIONAL + - INSTALLABILITY + - INTEROPERABILITY + - LOCALIZATION + - MAINTAINABILITY + - PERFORMANCE + - PORTABILITY + - PROCEDURE + - RELIABILITY + - SECURITY + - STABILITY + - USABILITY + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test suite has finished there is no + guarantee that these links are valid. Persistently stored + logs shall be (re-)declared by [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md). + type: array + items: + type: object + properties: + name: + _description: The name of the log file. + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TERC: + description: This link signifies that the test suite represented + by this event groups all test case executions resulting from + the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). + required: false + multiple: false + targets: + any_type: false + types: + - EiffelTestExecutionRecipeCollectionCreatedEvent +_history: + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestSuiteStartedEvent/simple.json diff --git a/definitions/EiffelTestSuiteStartedEvent/3.1.0.yml b/definitions/EiffelTestSuiteStartedEvent/3.1.0.yml new file mode 100644 index 00000000..096ee9ff --- /dev/null +++ b/definitions/EiffelTestSuiteStartedEvent/3.1.0.yml @@ -0,0 +1,177 @@ +# 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: TSS +_description: |- + The EiffelTestSuiteStartedEvent declares that the execution of a test suite has started. This can either be declared stand-alone or as part of an activity or other test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + In Eiffel, a test suite is nothing more or less than a collection of test case executions (see [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) and/or other test suite executions. The executed test suite may be an ad-hoc transient grouping of test cases that were executed at a particular time or place or for a particular purpose or a persistent entity tracked in a test management system - Eiffel makes no distinction or assumptions either way. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the test suite. Uniqueness is not + required or checked, but is useful. + type: string + categories: + _description: The category or categories of the test suite. + This can be used to group multiple similar test suites for + analysis and visualization purposes. Example usage is to + categorize test suites required before release as "Pre-release + tests". + type: array + items: + type: string + types: + _description: The type or types of testing performed by the + test suite, as [defined by ISO 29119](http://www.softwaretestingstandard.org). + type: array + items: + type: string + enum: + - ACCESSIBILITY + - BACKUP_RECOVERY + - COMPATIBILITY + - CONVERSION + - DISASTER_RECOVERY + - FUNCTIONAL + - INSTALLABILITY + - INTEROPERABILITY + - LOCALIZATION + - MAINTAINABILITY + - PERFORMANCE + - PORTABILITY + - PROCEDURE + - RELIABILITY + - SECURITY + - STABILITY + - USABILITY + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test suite has finished there is no + guarantee that these links are valid. Persistently stored + logs shall be (re-)declared by [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md). + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.0.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + TERC: + description: This link signifies that the test suite represented + by this event groups all test case executions resulting from + the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). + required: false + multiple: false + targets: + any_type: false + types: + - EiffelTestExecutionRecipeCollectionCreatedEvent +_history: + - version: 3.1.0 + introduced_in: Current version + changes: Add `data.liveLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestSuiteStartedEvent/simple.json diff --git a/definitions/EiffelTestSuiteStartedEvent/3.2.0.yml b/definitions/EiffelTestSuiteStartedEvent/3.2.0.yml new file mode 100644 index 00000000..62eb5012 --- /dev/null +++ b/definitions/EiffelTestSuiteStartedEvent/3.2.0.yml @@ -0,0 +1,195 @@ +# 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: TSS +_description: |- + The EiffelTestSuiteStartedEvent declares that the execution of a test suite has started. This can either be declared stand-alone or as part of an activity or other test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. + + In Eiffel, a test suite is nothing more or less than a collection of test case executions (see [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) and/or other test suite executions. The executed test suite may be an ad-hoc transient grouping of test cases that were executed at a particular time or place or for a particular purpose or a persistent entity tracked in a test management system - Eiffel makes no distinction or assumptions either way. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + name: + _description: The name of the test suite. Uniqueness is not + required or checked, but is useful. + type: string + categories: + _description: The category or categories of the test suite. + This can be used to group multiple similar test suites for + analysis and visualization purposes. Example usage is to + categorize test suites required before release as "Pre-release + tests". + type: array + items: + type: string + types: + _description: The type or types of testing performed by the + test suite, as [defined by ISO 29119](http://www.softwaretestingstandard.org). + type: array + items: + type: string + enum: + - ACCESSIBILITY + - BACKUP_RECOVERY + - COMPATIBILITY + - CONVERSION + - DISASTER_RECOVERY + - FUNCTIONAL + - INSTALLABILITY + - INTEROPERABILITY + - LOCALIZATION + - MAINTAINABILITY + - PERFORMANCE + - PORTABILITY + - PROCEDURE + - RELIABILITY + - SECURITY + - STABILITY + - USABILITY + liveLogs: + _description: An array of live log files available during execution. + These shall not be presumed to be stored persistently; in + other words, once the test suite has finished there is no + guarantee that these links are valid. Persistently stored + logs shall be (re-)declared by [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md). + type: array + items: + type: object + properties: + mediaType: + _description: The [media type](https://en.wikipedia.org/wiki/Media_type) + of the URI's payload. Can be used to differentiate + between various representations of the same log, e.g. + text/html for human consumption and text/plain or application/json + for the machine-readable form. + type: string + name: + _description: The name of the log file. + type: string + tags: + _description: Arbitrary tags and keywords that describe + this log. + type: array + items: + type: string + uri: + _description: The URI at which the log can be retrieved. + type: string + required: + - name + - uri + additionalProperties: false + customData: + type: array + items: + $ref: ../EiffelCustomDataProperty/1.0.0.yml + required: + - name + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: 'Identifies a cause of the event occurring. SHOULD + not be used in conjunction with __CONTEXT__: individual events + providing __CAUSE__ within a larger context gives rise to ambiguity. + It is instead recommended to let the root event of the context + declare __CAUSE__.' + 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 + PRECURSOR: + description: 'Used to declare temporal relationships between + [activities](../eiffel-syntax-and-usage/glossary.md#activity) in a + [pipeline](../eiffel-syntax-and-usage/glossary.md#pipeline), i.e. what + other activity/activities preceded this activity. This link type applies + primarily to non event-triggered activities. For more information on + the usage of this link type please see + [Activity Linking](../eiffel-syntax-and-usage/activity-linking.md).' + required: false + multiple: true + targets: + any_type: false + types: + - EiffelTestSuiteStartedEvent + TERC: + description: This link signifies that the test suite represented + by this event groups all test case executions resulting from + the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). + required: false + multiple: false + targets: + any_type: false + types: + - EiffelTestExecutionRecipeCollectionCreatedEvent +_history: + - version: 3.2.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). + - version: 3.1.0 + introduced_in: No edition set + changes: Add `data.liveLogs.{mediaType,tags}`. + - version: 3.0.0 + introduced_in: '[edition-agen](../../../tree/edition-agen)' + changes: Improved information integrity protection (see [Issue + 185](https://github.com/eiffel-community/eiffel/issues/185)). + - version: 2.0.0 + introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)' + changes: Introduced purl identifiers instead of GAVs (see [Issue + 182](https://github.com/eiffel-community/eiffel/issues/182)) + - 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/EiffelTestSuiteStartedEvent/simple.json diff --git a/eiffel-syntax-and-usage/event-schemas.md b/eiffel-syntax-and-usage/event-schemas.md new file mode 100644 index 00000000..a7f36ea4 --- /dev/null +++ b/eiffel-syntax-and-usage/event-schemas.md @@ -0,0 +1,123 @@ + + +# Event Schemas + +Eiffel events are defined using [JSON schemas](https://json-schema.org/) and stored in this repository along with their documentation. Each schema version gets its own file so you can access all schemas from a single source code tree. Schema files have predictable paths based on the event name and its version, e.g. [schemas/EiffelCompositionDefinedEvent/3.2.0.json](../schemas/EiffelCompositionDefinedEvent/3.2.0.json). + +The documentation of each event is available in a Markdown file that covers the latest version of the event, e.g. [eiffel-vocabulary/EiffelCompositionDefinedEvent.md](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md). + +Both schemas and documentation files are generated from _schema definition files_; YAML files with a custom schema based on the JSON schema specification. Like the schema files themselves there's one file per event and version, e.g. [definitions/EiffelCompositionDefinedEvent/3.2.0.yml](../definitions/EiffelCompositionDefinedEvent/3.2.0.yml). The main difference between these files and normal JSON schema files, apart from the YAML representation, is an additional set of keys with an underscore prefix that contains additional metadata that can't be part of the JSON schema itself. Those keys are used when generating the documentation and are simply ignored when the schema definition files are turned into schema files. The following table describes these additional top-level keys. + +| Key | Description | +| --------------- | ----------------------- | +| `_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. | +| `_links..description` | A description of the link type. | +| `_links..required` | A boolean value indicating whether a link of this type is required. Optional, default false. | +| `_links..multiple` | A boolean value indicating whether multiple links of this type is allowed. Optional, default false. | +| `_links..targets.any_type` | A boolean value indicating whether the link can point to an event of any type. | +| `_links..targets.types` | A string array of event names that the link type may point to. Must be non-empty if `any_type` is false, and must be empty if `any_type` is true. | +| `_history` | An array of objects describing the event type's version history, up to and including the current version. The items should be sorted in reverse order. | +| `_history.version` | The event version described in this item. | +| `_history.introduced_in` | A description of the edition in which this item's event version was introduced. | +| `_history.changes` | A short description of the changes in this item's event version. | +| `_examples` | An array of objects describing examples of this event. | +| `_examples.title` | The name of the example. | +| `_examples.url` | The URL of the example. | + +In addition, the object that describes each property in the schema supports a few additional keys that are specific to the schema definition format and will be omitted when the schema file is produced: + +| Key | Description | +| --------------- | ----------------------- | +| `_description` | A description of the property. | +| `_format` | A description of the expected form of the values, in addition to what's prescribed by the data type. For example, a string property could be expected to contain a URI or a UUID. Optional. | + +## Sharing subschemas between events +Another feature of schema definition files is that they may contain references to other schema definition files via standard [JSON references](https://json-spec.readthedocs.io/reference.html). This is used to reuse common definitions like the meta member in all events. Doing so reduces the maintenance burden when making changes to the common parts of the schemas, makes sure there are no unintentional differences between events, and makes it possible for programs reading the files to understand that a subset of the schema actually is common to more than one event. The latter can e.g. be used by programs to generate types for an SDK from the schema definition files. + +For example, the definition of __meta__ is found among one of the EiffelMetaProperty subschemas like [definitions/EiffelMetaProperty/3.0.0.yml](../definitions/EiffelMetaProperty/3.0.0.yml). Defining this member and referencing it from the event's schema is done like this: + +``` +meta: + $ref: ../EiffelMetaProperty/3.0.0.yml +``` + +Changing a non-event schema definition that's referenced by actual events, like EiffelMetaProperty, fundamentally works in the same way as changing the event schemas directly. The new event version should be updated according to the [normal patch/minor/major rules](versioning.md), which in practice means that the version number increase should match the change of the referenced schema; if EiffelMetaProperty gets a minor update then all events that update to that version should receive a minor version bump too. + +## Example +Here's a minimal example of a schema definition file: + +``` +$schema: http://json-schema.org/draft-04/schema# +_abbrev: SH +_description: The EiffelSomethingHappenedEvent declares that something happened. +type: object +properties: + meta: + $ref: ../EiffelMetaProperty/3.0.0.yml + data: + type: object + properties: + what: + _description: A description of what happened. + _format: A well-formed sentence. + type: string + customData: + type: array + items: + type: object + properties: + key: + type: string + value: {} + required: + - key + - value + additionalProperties: false + required: + - what + additionalProperties: false + links: + type: array + items: + $ref: ../EiffelEventLink/1.1.1.yml +required: + - meta + - data + - links +additionalProperties: false +_links: + CAUSE: + description: Identifies a cause of the event occurring. + required: false + multiple: true + targets: + any_type: true + types: [] +_history: + - version: 1.0.0 + introduced_in: '[edition-lyon](../../../tree/edition-lyon)' + changes: Initial version. +_examples: + - title: Simple example + url: ../examples/events/EiffelSomethingHappenedEvent/simple.json +``` + +## Generating schemas and documentation +Schema and documentation files should never by updated by hand. Instead, modify the schema definition files and use the [generate_docs.py](../generate_docs.py) and [generate_schemas.py](../generate_schemas.py) Python scripts to regenerate all schemas and documentation. The included [makefile](../Makefile) calls the scripts with the required arguments. Just make sure you have installed the Python dependencies specified in [requirements.txt](../requirements.txt) before running the scripts. Package installations are typically done within a Python virtualenv, but you can also reuse one of the virtualenvs created by tox. The schema definition files and the generated files must always be consistent, i.e. all changes to these files should be committed together. This is enforced via a GitHub Actions workflow when pushing to a branch or creating a PR. diff --git a/eiffel-syntax-and-usage/versioning.md b/eiffel-syntax-and-usage/versioning.md index 2248232b..73dffde0 100644 --- a/eiffel-syntax-and-usage/versioning.md +++ b/eiffel-syntax-and-usage/versioning.md @@ -43,6 +43,7 @@ That being said, to facilitate compatibility and consistency, the Eiffel protoco In the case of a communication protocol, applying Semantic Versioning is not as straight-forward as for a regular software implementation. The ground rule is to consider backwards compatibility from the perspective of the consumer of an event. Below are rules and examples of how this applies to the Eiffel protocol. * Mere documentation updates with no impact on event schemas require no stepping of the version at all. Indeed, the version is best understood as a _schema_ versions. Or, conversely, documentation SHALL NOT be updated in such a way as to change the semantics of event types or their properties without also making a change to the schema. To exemplify, changing the meaning of a property without changing its name or format is not allowed, as this introduces hidden compatibility issues. +* An exception to the prior rule is changes in the allowed link types and their properties (e.g. if multiple links of a particular type are allowed). Even though the link types currently aren't covered by the schemas we version the schemas as if the opposite were true. Consequently, adding a new link type SHALL result in a minor version increment and a removed link type SHALL result in a major version increment. * __patch:__ The patch version is incremented for changes that do not affect event structure, do not carry semantic significance and do not introduce additional legal values. To exemplify, narrowing a string pattern in a schema (e.g. from `[a-zA-Z_]` to `[a-zA-Z]`) would require the patch version to be stepped. * __minor:__ The minor version is incremented for changes to event structure or other changes that carry semantic significance but are backwards compatible from a consumer's point of view. To exemplify, adding a property to an event type without changing the syntax of existing properties would require the minor version to be stepped. Note that existing _producers_ may not be able to produce the new event type version, but a _consumer_ SHALL be able to derive the same information as from the previous version. Note that this means that consumers SHOULD be prepared to handle (and disregard) unrecognized properties in higher minor versions than they are familiar with. * __major:__ The major version is incremented for changes that are not backwards compatible from the consumer's point of view. To exemplify, removing or renaming an existing property would require the major version to be stepped. Similarly, broadening a string pattern to allow additional legal values (e.g. from `[a-zA-Z]` to `[a-zA-Z_]`) requires the major version to be stepped. diff --git a/eiffel-vocabulary/EiffelActivityCanceledEvent.md b/eiffel-vocabulary/EiffelActivityCanceledEvent.md index c16ade24..ca455747 100644 --- a/eiffel-vocabulary/EiffelActivityCanceledEvent.md +++ b/eiffel-vocabulary/EiffelActivityCanceledEvent.md @@ -1,24 +1,13 @@ # EiffelActivityCanceledEvent (ActC) 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. ## Data Members + ### data.reason __Type:__ String __Required:__ No @@ -42,8 +31,7 @@ __Description:__ While for most events it is recommended that __CAUSE__ SHOULD n ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -54,6 +42,7 @@ __Multiple allowed:__ Yes __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. ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -86,7 +75,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -122,7 +110,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -134,59 +121,61 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityCanceledEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityCanceledEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelActivityCanceledEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelActivityFinishedEvent.md b/eiffel-vocabulary/EiffelActivityFinishedEvent.md index 10e1234d..3357ea9d 100644 --- a/eiffel-vocabulary/EiffelActivityFinishedEvent.md +++ b/eiffel-vocabulary/EiffelActivityFinishedEvent.md @@ -1,24 +1,13 @@ # EiffelActivityFinishedEvent (ActF) The EiffelActivityFinishedEvent declares that a previously started activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md) followed by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)) has finished. ## Data Members + ### data.outcome __Type:__ Object __Required:__ Yes @@ -28,7 +17,7 @@ __Description:__ The outcome of the activity. __Type:__ String __Required:__ Yes __Legal values:__ SUCCESSFUL, UNSUCCESSFUL, FAILED, ABORTED, TIMED_OUT, INCONCLUSIVE -__Description:__ A terse standardized conclusion of the activity, designed to be machine readable. +__Description:__ A terse standardized conclusion of the activity, designed to be machine readable. SUCCESSFUL signifies that the activity was concluded and the outcome matched expectations. UNSUCCESSFUL signifies that the activity was concluded, but the outcome did not match expectations. To exemplify, a compilation job was successfully invoked, but compilation failed. FAILED signifies that the activity could not be successfully executed. To exemplify, a compilation could not be invoked, e.g. due to misconfiguration or environment issues. @@ -80,12 +69,11 @@ __Description:__ Declares the activity execution that was finished. In other wor __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -96,6 +84,7 @@ __Multiple allowed:__ Yes __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. ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -128,7 +117,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -164,7 +152,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -176,60 +163,62 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.1.0 | No edition set | Add `data.persistentLogs.{mediaType,tags}`. | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityFinishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.1.0 | No edition set | Add `data.persistentLogs.{mediaType,tags}`. | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityFinishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelActivityFinishedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelActivityStartedEvent.md b/eiffel-vocabulary/EiffelActivityStartedEvent.md index 20082c96..81e3b453 100644 --- a/eiffel-vocabulary/EiffelActivityStartedEvent.md +++ b/eiffel-vocabulary/EiffelActivityStartedEvent.md @@ -1,24 +1,13 @@ # EiffelActivityStartedEvent (ActS) The EiffelActivityStartedEvent declares that a previously triggered activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md)) has started. ## Data Members + ### data.executionUri __Type:__ String __Required:__ No @@ -59,22 +48,15 @@ __Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelAct __Multiple allowed:__ No __Description:__ Declares the activity execution that was started. 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). -### PREVIOUS_ACTIVITY_EXECUTION -__Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the latest previous execution of the activity. - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -84,7 +66,14 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### PREVIOUS_ACTIVITY_EXECUTION +__Required:__ No +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the latest previous execution of the activity. + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -117,7 +106,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -153,7 +141,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -165,61 +152,63 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 4.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 4.1.0 | No edition set | Add `data.liveLogs.{mediaType,tags}`. | -| 4.0.0 | [edition-agen-1](../../../tree/edition-agen-1) | Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityStartedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 4.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 4.1.0 | No edition set | Add `data.liveLogs.{mediaType,tags}`. | +| 4.0.0 | [edition-agen-1](../../../tree/edition-agen-1) | Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityStartedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelActivityStartedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelActivityTriggeredEvent.md b/eiffel-vocabulary/EiffelActivityTriggeredEvent.md index 3c1747ec..55708910 100644 --- a/eiffel-vocabulary/EiffelActivityTriggeredEvent.md +++ b/eiffel-vocabulary/EiffelActivityTriggeredEvent.md @@ -1,18 +1,6 @@ # EiffelActivityTriggeredEvent (ActT) @@ -21,6 +9,7 @@ The EiffelActivityTriggeredEvent declares that a certain activity - typically a In a situation where execution follows immediately upon triggering these two events should be sent together. Where that is not the case (e.g. due to queuing) the time delta between EiffelActivityTriggeredEvent and EiffelActivityStartedEvent constitutes the queue time. ## Data Members + ### data.name __Type:__ String __Required:__ Yes @@ -40,7 +29,7 @@ __Description:__ The circumstances triggering the activity. __Type:__ String __Required:__ Yes __Legal values:__ MANUAL, EIFFEL_EVENT, SOURCE_CHANGE, TIMER, OTHER -__Description:__ The type of trigger. +__Description:__ The type of trigger. MANUAL signifies that the activity was manually triggered. EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. SOURCE_CHANGE signifies that the activity was triggered as a consequence of a detected source change __not__ represented by Eiffel events. @@ -66,28 +55,28 @@ This section describes which link types are valid for this event type. For detai __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the [activity](../eiffel-syntax-and-usage/glossary.md#activity) or test suite of which this event constitutes a part. -### PRECURSOR -__Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) -__Multiple allowed:__ Yes -__Description:__ Used to declare temporal relationships between [activities](../eiffel-syntax-and-usage/glossary.md#activity) in a [pipeline](../eiffel-syntax-and-usage/glossary.md#pipeline), i.e. what other activity/activities preceded this activity. This link type applies primarily to non event-triggered activities. For more information on the usage of this link type please see [Activity Linking](../eiffel-syntax-and-usage/activity-linking.md). - ### FLOW_CONTEXT __Required:__ No __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) __Multiple allowed:__ Yes __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. +### PRECURSOR +__Required:__ No +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) +__Multiple allowed:__ Yes +__Description:__ Used to declare temporal relationships between [activities](../eiffel-syntax-and-usage/glossary.md#activity) in a [pipeline](../eiffel-syntax-and-usage/glossary.md#pipeline), i.e. what other activity/activities preceded this activity. This link type applies primarily to non event-triggered activities. For more information on the usage of this link type please see [Activity Linking](../eiffel-syntax-and-usage/activity-linking.md). + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -120,7 +109,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -156,7 +144,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -168,61 +155,63 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 4.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 4.0.0 | [edition-agen-1](../../../tree/edition-agen-1) | Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityTriggeredEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 4.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 4.0.0 | [edition-agen-1](../../../tree/edition-agen-1) | Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityTriggeredEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelActivityTriggeredEvent/simple.json) * [Example containing custom data](../examples/events/EiffelActivityTriggeredEvent/simple-customdata.json) diff --git a/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md b/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md index ddab6c37..dd344ecc 100644 --- a/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md +++ b/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md @@ -1,24 +1,13 @@ # EiffelAnnouncementPublishedEvent (AnnP) The EiffelAnnouncementPublishedEvent represents an announcement, technically regarding any topic but typically used to communicate any incidents or status updates regarding the continuous integration and delivery pipeline. This information can then be favorably displayed in visualization and dashboarding applications. ## Data Members + ### data.heading __Type:__ String __Required:__ Yes @@ -44,22 +33,15 @@ __Description:__ The severity of the announcement. The CLOSED and CANCELED value This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### MODIFIED_ANNOUNCEMENT -__Required:__ No -__Legal targets:__ [EiffelAnnouncementPublishedEvent](../eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies an announcement of which this event represents an update or modification, if any. Example usage is to declare the end to a previously announced situation. - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -69,7 +51,14 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### MODIFIED_ANNOUNCEMENT +__Required:__ No +__Legal targets:__ [EiffelAnnouncementPublishedEvent](../eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies an announcement of which this event represents an update or modification, if any. Example usage is to declare the end to a previously announced situation. + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -102,7 +91,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -138,7 +126,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -150,59 +137,61 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelAnnouncementPublishedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelArtifactCreatedEvent.md b/eiffel-vocabulary/EiffelArtifactCreatedEvent.md index 95ab1679..ee4c8c8e 100644 --- a/eiffel-vocabulary/EiffelArtifactCreatedEvent.md +++ b/eiffel-vocabulary/EiffelArtifactCreatedEvent.md @@ -1,24 +1,13 @@ # EiffelArtifactCreatedEvent (ArtC) The EiffelArtifactCreatedEvent declares that a software artifact has been created, what its coordinates are, what it contains and how it was created. ## Data Members + ### data.identity __Type:__ String __Format:__ [purl specification](https://github.com/package-url/purl-spec) @@ -49,23 +38,23 @@ __Description:__ The command used to build the artifact within the identified en __Type:__ String __Required:__ No __Legal values:__ NONE, ANY, EXACTLY_ONE, AT_LEAST_ONE -__Description:__ Defines whether this artifact requires an implementing artifact. This is typically used for interfaces requiring some backend implementation, although the interface does not presume to define _which_ implementation. Implicitly interpreted as "ANY" if undefined. +__Description:__ Defines whether this artifact requires an implementing artifact. This is typically used for interfaces requiring some backend implementation, although the interface does not presume to define _which_ implementation. Implicitly interpreted as "ANY" if undefined. NONE signifies that there SHALL no implementations of this artifact. In other words, a composition containing another artifact identifying it in __data.implements__ would be illegal. ANY signifies that there may or may not be implementations of this artifact. EXACTLY_ONE signifies that a legal composition must contain one and only one implementation of this artifact. AT_LEAST_ONE signifies that a legal composition must contain one or more implementations of this artifact. -### data.implements +### data.dependsOn __Type:__ String[] __Format:__ [purl specification](https://github.com/package-url/purl-spec) __Required:__ No -__Description:__ An array of [purl identified](https://github.com/package-url/purl-spec) entities this artifact implements. The typical use case of this is to identify interfaces implemented by this artifact. While not included in the purl specification itself, the Eiffel protocol allows version range notation according to [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) to be used for the version component of the package identity. Note that the purl specification always requires the version component to be percent-encoded. +__Description:__ An array of [purl identified](https://github.com/package-url/purl-spec) entities this artifact depends on. While not included in the purl specification itself, the Eiffel protocol allows version range notation according to [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) to be used for the version component of the package identity. Note that the purl specification always requires the version component to be percent-encoded. -### data.dependsOn +### data.implements __Type:__ String[] __Format:__ [purl specification](https://github.com/package-url/purl-spec) __Required:__ No -__Description:__ An array of [purl identified](https://github.com/package-url/purl-spec) entities this artifact depends on. While not included in the purl specification itself, the Eiffel protocol allows version range notation according to [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) to be used for the version component of the package identity. Note that the purl specification always requires the version component to be percent-encoded. +__Description:__ An array of [purl identified](https://github.com/package-url/purl-spec) entities this artifact implements. The typical use case of this is to identify interfaces implemented by this artifact. While not included in the purl specification itself, the Eiffel protocol allows version range notation according to [Maven syntax](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) to be used for the version component of the package identity. Note that the purl specification always requires the version component to be percent-encoded. ### data.name __Type:__ String @@ -76,36 +65,29 @@ __Description:__ Any (colloquial) name of the artifact. Unlike __data.identity__ This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). +### CAUSE +__Required:__ No +__Legal targets:__ Any +__Multiple allowed:__ Yes +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. + ### COMPOSITION __Required:__ No __Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the composition from which this artifact was built. -### ENVIRONMENT +### CONTEXT __Required:__ No -__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No -__Description:__ Identifies the environment in which this artifact was built. - -### PREVIOUS_VERSION -__Required:__ No -__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the artifact the event represents. - -### CAUSE -__Required:__ No -__Legal targets:__ Any -__Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies the activity or test suite of which this event constitutes a part. -### CONTEXT +### ENVIRONMENT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) __Multiple allowed:__ No -__Description:__ Identifies the activity or test suite of which this event constitutes a part. +__Description:__ Identifies the environment in which this artifact was built. ### FLOW_CONTEXT __Required:__ No @@ -113,7 +95,14 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### PREVIOUS_VERSION +__Required:__ No +__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) +__Multiple allowed:__ Yes +__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the artifact the event represents. + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -146,7 +135,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -182,7 +170,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -194,61 +181,63 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelArtifactCreatedEvent/simple.json) * [Interface example](../examples/events/EiffelArtifactCreatedEvent/interface.json) * [Backend example](../examples/events/EiffelArtifactCreatedEvent/backend.json) diff --git a/eiffel-vocabulary/EiffelArtifactPublishedEvent.md b/eiffel-vocabulary/EiffelArtifactPublishedEvent.md index 231a035e..76958736 100644 --- a/eiffel-vocabulary/EiffelArtifactPublishedEvent.md +++ b/eiffel-vocabulary/EiffelArtifactPublishedEvent.md @@ -1,24 +1,13 @@ # EiffelArtifactPublishedEvent (ArtP) The EiffelArtifactPublishedEvent declares that a software artifact (declared by [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md)) has been published and is consequently available for retrieval at one or more locations. ## Data Members + ### data.locations __Type:__ Object[] __Required:__ Yes @@ -33,7 +22,7 @@ __Description:__ Identifies the name of the file within the artifact for which t __Type:__ String __Required:__ Yes __Legal values:__ ARTIFACTORY, NEXUS, PLAIN, OTHER -__Description:__ The type of location. May be used by (automated) readers to understand the method of retrieval, particularly with regards to authentication. +__Description:__ The type of location. May be used by (automated) readers to understand the method of retrieval, particularly with regards to authentication. ARTIFACTORY signifies an [Artifactory](https://www.jfrog.com/artifactory/) NEXUS signifies a [Nexus](http://www.sonatype.org/nexus/) PLAIN signifies a plain HTTP GET request. @@ -58,12 +47,11 @@ __Description:__ Identifies the artifact that was published. __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -74,6 +62,7 @@ __Multiple allowed:__ Yes __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. ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -106,7 +95,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -142,7 +130,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -154,60 +141,62 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.1.0 | [edition-paris](../../../tree/edition-paris) | Added name qualifier for artifact locations (see [Issue 248](https://github.com/eiffel-community/eiffel/issues/248)) | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactPublishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.1.0 | [edition-paris](../../../tree/edition-paris) | Added name qualifier for artifact locations (see [Issue 248](https://github.com/eiffel-community/eiffel/issues/248)) | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactPublishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelArtifactPublishedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelArtifactReusedEvent.md b/eiffel-vocabulary/EiffelArtifactReusedEvent.md index 9504b476..852be19e 100644 --- a/eiffel-vocabulary/EiffelArtifactReusedEvent.md +++ b/eiffel-vocabulary/EiffelArtifactReusedEvent.md @@ -1,18 +1,6 @@ # EiffelArtifactReusedEvent (ArtR) @@ -26,28 +14,21 @@ The event has no data members, but solely relies on its two required link types This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). +### CAUSE +__Required:__ No +__Legal targets:__ Any +__Multiple allowed:__ Yes +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. + ### COMPOSITION __Required:__ Yes __Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the composition for which an already existing artifact (identified by __REUSED_ARTIFACT__) is declared reused. -### REUSED_ARTIFACT -__Required:__ Yes -__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) -__Multiple allowed:__ No -__Description:__ This link identifies the [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) that is reused for the composition identified by __COMPOSITION__; in other words, the artifact that is not rebuilt for a that composition. - -### CAUSE -__Required:__ No -__Legal targets:__ Any -__Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. - ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -57,7 +38,14 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### REUSED_ARTIFACT +__Required:__ Yes +__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) +__Multiple allowed:__ No +__Description:__ This link identifies the [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) that is reused for the composition identified by __COMPOSITION__; in other words, the artifact that is not rebuilt for a that composition. + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -90,7 +78,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -126,7 +113,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -138,59 +124,61 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactReusedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactReusedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelArtifactReusedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelCompositionDefinedEvent.md b/eiffel-vocabulary/EiffelCompositionDefinedEvent.md index 48e5f379..f31c1c3b 100644 --- a/eiffel-vocabulary/EiffelCompositionDefinedEvent.md +++ b/eiffel-vocabulary/EiffelCompositionDefinedEvent.md @@ -1,24 +1,13 @@ # EiffelCompositionDefinedEvent (CD) The EiffelCompositionDefinedEvent declares a composition of items (artifacts, sources and other compositions) has been defined, typically with the purpose of enabling further downstream artifacts to be generated. ## Data Members + ### data.name __Type:__ String __Required:__ Yes @@ -33,40 +22,38 @@ __Description:__ The version of the composition, if any. This is in a sense redu This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### ELEMENT -__Required:__ No -__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md), -[EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md), [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md), -[EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies an element and/or sub-composition of this composition. The latter is particularly useful for documenting large and potentially decentralized compositions, and may be used to reduce the need to repeat large compositions in which only small parts are subject to frequent change. - -### PREVIOUS_VERSION -__Required:__ No -__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the composition. - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. +### ELEMENT +__Required:__ No +__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md), [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md), [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) +__Multiple allowed:__ Yes +__Description:__ Identifies an element and/or sub-composition of this composition. The latter is particularly useful for documenting large and potentially decentralized compositions, and may be used to reduce the need to repeat large compositions in which only small parts are subject to frequent change. + ### FLOW_CONTEXT __Required:__ No __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) __Multiple allowed:__ Yes __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. +### PREVIOUS_VERSION +__Required:__ No +__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) +__Multiple allowed:__ Yes +__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the composition. + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -99,7 +86,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -135,7 +121,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -147,60 +132,62 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.1.0 | [edition-paris](../../../tree/edition-paris) | Added SCC as valid target for ELEMENT links (see [Issue 218](https://github.com/eiffel-community/eiffel/issues/218)) | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelCompositionDefinedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.1.0 | [edition-paris](../../../tree/edition-paris) | Added SCC as valid target for ELEMENT links (see [Issue 218](https://github.com/eiffel-community/eiffel/issues/218)) | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelCompositionDefinedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelCompositionDefinedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md b/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md index 692b3c74..34360356 100644 --- a/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md +++ b/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md @@ -1,18 +1,6 @@ # EiffelConfidenceLevelModifiedEvent (CLM) @@ -21,6 +9,7 @@ The EiffelConfidenceLevelModifiedEvent declares that an entity has achieved (or Confidence levels may operate at high or low levels of abstraction - ranging from "smokeTestsOk" to "releasable" or "released" - and they may group other confidence levels of lower abstraction levels. They may also be general or very niched, e.g. "releasable" or "reseabableToCustomerX". Confidence levels frequently figure in automated delivery interfaces within a tiered system context: lower level tiers issue an agreed confidence level signaling that a new version is ready for integration in a higher level tier. ## Data Members + ### data.name __Type:__ String __Required:__ Yes @@ -30,7 +19,7 @@ __Description:__ The name of the confidence level. It is recommended for confide __Type:__ String __Required:__ Yes __Legal values:__ SUCCESS, FAILURE, INCONCLUSIVE -__Description:__ The value of the confidence level. +__Description:__ The value of the confidence level. SUCCESS signifies that the confidence level has been successfully achieved. FAILURE signifies that the confidence level could not be achieved. INCONCLUSIVE signifies that achievement of the confidence level could not be determined. @@ -64,32 +53,15 @@ __Description:__ Any group, such as a development team, committee or test group, This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### SUBJECT -__Required:__ Yes -__Optional in:__ None -__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md), -[EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), -[EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md), -[EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies a subject of the confidence level; in other words, what the confidence level applies to. - -### SUB_CONFIDENCE_LEVEL -__Required:__ No -__Legal targets:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Used in events summarizing multiple confidence levels. Example use case: the confidence level "allTestsOk" summarizes the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", and consequently links to them via __SUB_CONFIDENCE_LEVEL__. This is intended for purely descriptive, rather than prescriptive, use. - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -99,7 +71,20 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### SUBJECT +__Required:__ Yes +__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md), [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md), [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) +__Multiple allowed:__ Yes +__Description:__ Identifies a subject of the confidence level; in other words, what the confidence level applies to. + +### SUB_CONFIDENCE_LEVEL +__Required:__ No +__Legal targets:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md) +__Multiple allowed:__ Yes +__Description:__ Used in events summarizing multiple confidence levels. Example use case: the confidence level "allTestsOk" summarizes the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", and consequently links to them via __SUB_CONFIDENCE_LEVEL__. This is intended for purely descriptive, rather than prescriptive, use. + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -132,7 +117,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -168,7 +152,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -180,59 +163,61 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelConfidenceLevelModifiedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md b/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md index 62610bf3..0550b766 100644 --- a/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md +++ b/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md @@ -1,18 +1,6 @@ # EiffelEnvironmentDefinedEvent (ED) @@ -21,6 +9,7 @@ The EiffelEnvironmentDefinedEvent declares an environment which may be reference From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__, or a __RUNTIME_ENVIRONMENT__ link to another event that provides a more comprehensive description. Unless a link of the latter kind is used exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties or a RUNTIME_ENVIRONMENT link; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones. ## Data Members + ### data.name __Type:__ String __Required:__ Yes @@ -60,22 +49,15 @@ __Description:__ A URI identifying the environment description. This is the catc This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### PREVIOUS_VERSION -__Required:__ No -__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the environment. - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -85,13 +67,20 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### PREVIOUS_VERSION +__Required:__ No +__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) +__Multiple allowed:__ Yes +__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the environment. + ### RUNTIME_ENVIRONMENT __Required:__ No -__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) +__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) __Multiple allowed:__ Yes __Description:__ Identifies a description of a runtime environment within which an activity has taken place. The target event could e.g. identify a [Docker](https://www.docker.com/) image, a JVM distribution archive, or a composition of operating system packages that were installed on the host system. This link type has the same purpose as the `data.image` member but allows richer and less ambiguous descriptions. ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -124,7 +113,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -160,7 +148,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -172,62 +159,64 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.1.0 | No edition set | Added RUNTIME_ENVIRONMENT link type. | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.1.0 | No edition set | Added RUNTIME_ENVIRONMENT link type. | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [URI example](../examples/events/EiffelEnvironmentDefinedEvent/uri.json) * [Host example](../examples/events/EiffelEnvironmentDefinedEvent/host.json) * [Image example](../examples/events/EiffelEnvironmentDefinedEvent/image.json) diff --git a/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md b/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md index 98e6aa66..f6895b52 100644 --- a/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md +++ b/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md @@ -1,18 +1,6 @@ # EiffelFlowContextDefinedEvent (FCD) @@ -21,6 +9,7 @@ The EiffelFlowContextDefinedEvent describes the context of other events, answeri The nature of the described context can vary. The event consequently offers a high degree of flexibility in its description, and none of its member fields are mandatory. Instead they can picked and mixed to fit the situation. ## Data Members + ### data.product __Type:__ String __Required:__ No @@ -54,12 +43,11 @@ This section describes which link types are valid for this event type. For detai __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -70,6 +58,7 @@ __Multiple allowed:__ Yes __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. ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -102,7 +91,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -138,7 +126,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -150,59 +137,61 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelFlowContextDefinedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelIssueDefinedEvent.md b/eiffel-vocabulary/EiffelIssueDefinedEvent.md index 761185fa..4a807179 100644 --- a/eiffel-vocabulary/EiffelIssueDefinedEvent.md +++ b/eiffel-vocabulary/EiffelIssueDefinedEvent.md @@ -1,25 +1,10 @@ # EiffelIssueDefinedEvent (ID) -The EiffelIssueDefinedEvent declares that an issue has been created in some -external issue management software. ID is semantically similar to -[EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) -and [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md). +The EiffelIssueDefinedEvent declares that an issue has been created in some external issue management software. ID is semantically similar to [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) and [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md). ## Data Members @@ -27,7 +12,7 @@ and [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefine __Type:__ String __Required:__ Yes __Legal values:__ BUG, IMPROVEMENT, FEATURE, WORK_ITEM, REQUIREMENT, OTHER -__Description:__ The type of issue. +__Description:__ The type of issue. ### data.tracker __Type:__ String @@ -45,7 +30,7 @@ correctly interpreted. __Type:__ String __Required:__ Yes __Description:__ The identity of the issue. This is tracker dependent - most -trackers have their own issue naming schemes. +trackers have their own issue naming schemes. ### data.uri __Type:__ String @@ -69,52 +54,39 @@ This section describes which link types are valid for this event type. For detai __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be -used in conjunction with __CONTEXT__: individual events providing __CAUSE__ -within a larger context gives rise to ambiguity. It is instead recommended to -let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ -[EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No -__Description:__ Identifies the activity or test suite of which this event -constitutes a part. +__Description:__ Identifies the activity or test suite of which this event constitutes a part. ### FLOW_CONTEXT __Required:__ No -__Legal targets:__ -[EiffelFlowContextDefinedEvent](./EiffelFlowContextDefinedEvent.md) +__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) __Multiple allowed:__ No -__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. +__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. ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) __Required:__ Yes -__Description:__ The unique identity of the event, generated at event -creation. +__Description:__ The unique identity of the event, generated at event creation. ### meta.type __Type:__ String __Format:__ An event type name __Required:__ Yes -__Description:__ The type of event. This field is required by the recipient -of the event, as each event type has a specific meaning and a specific set of -members in the __data__ and __links__ objects. +__Description:__ The type of event. This field is required by the recipient of the event, as each event type has a specific meaning and a specific set of members in the __data__ and __links__ objects. ### meta.version __Type:__ String __Format:__ [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html) __Required:__ Yes -__Description:__ The version of the event type. This field is required by the -recipient of the event to interpret the contents. Please see -[Versioning](../eiffel-syntax-and-usage/versioning.md) for more information. +__Description:__ The version of the event type. This field is required by the recipient of the event to interpret the contents. Please see [Versioning](../eiffel-syntax-and-usage/versioning.md) for more information. ### meta.time __Type:__ Integer @@ -126,19 +98,12 @@ __Description:__ The event creation timestamp. __Type:__ String[] __Format:__ Free text __Required:__ No -__Description:__ Any tags or keywords associated with the events, for -searchability purposes. +__Description:__ Any tags or keywords associated with the events, for searchability purposes. ### meta.source __Type:__ Object -__Format:__ __Required:__ No -__Description:__ A description of the source of the event. This object is -primarily for traceability purposes, and while optional, some form of -identification of the source is __HIGHLY RECOMMENDED__. It offers multiple -methods of identifying the source of the event, techniques which may be -select from based on the technology domain and needs in any particular use -case. +__Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. #### meta.source.domainId __Type:__ String @@ -172,7 +137,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -184,58 +148,60 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelIssueDefinedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.0.0 | [0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueDefinedEvent.md) | Initial version | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelIssueDefinedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.0.0 | [0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueDefinedEvent.md) | Initial version | + ## Examples + * [Simple example](../examples/events/EiffelIssueDefinedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelIssueVerifiedEvent.md b/eiffel-vocabulary/EiffelIssueVerifiedEvent.md index 73d08f7d..7346f511 100644 --- a/eiffel-vocabulary/EiffelIssueVerifiedEvent.md +++ b/eiffel-vocabulary/EiffelIssueVerifiedEvent.md @@ -1,18 +1,6 @@ # EiffelIssueVerifiedEvent (IV) @@ -26,11 +14,23 @@ EiffelIssueVerifiedEvent has no data members, instead relying on its required li This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### SUCCESSFUL_ISSUE +### CAUSE __Required:__ No -__Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md) +__Legal targets:__ Any +__Multiple allowed:__ Yes +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. + +### CONTEXT +__Required:__ No +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No -__Description:__ Identifies an issue that has been successfully verified. +__Description:__ Identifies the activity or test suite of which this event constitutes a part. + +### ENVIRONMENT +__Required:__ No +__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the environment in which the issue was verified. ### FAILED_ISSUE __Required:__ No @@ -38,6 +38,12 @@ __Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDef __Multiple allowed:__ No __Description:__ Identifies an issue that has failed verification. +### FLOW_CONTEXT +__Required:__ No +__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) +__Multiple allowed:__ Yes +__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. + ### INCONCLUSIVE_ISSUE __Required:__ No __Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md) @@ -46,44 +52,24 @@ __Description:__ Identifies an issue for which this verification was inconclusiv ### IUT __Required:__ Yes -__Optional in:__ None -__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), -[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) +__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the Item Under Test; in other words, the entity for which the issue has been verified. -### VERIFICATION_BASIS -__Required:__ No -__Legal targets:__ [EiffelTestCaseFinishedEvent](../eiffel-vocabulary/EiffelTestCaseFinishedEvent.md), [EiffelTestSuiteFinishedEvent](../eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Used to declare the basis on which the verification statement(s) of this event have been issued. - -### ENVIRONMENT -__Required:__ No -__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the environment in which the issue was verified. - -### CAUSE -__Required:__ No -__Legal targets:__ Any -__Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. - -### CONTEXT +### SUCCESSFUL_ISSUE __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md) __Multiple allowed:__ No -__Description:__ Identifies the activity or test suite of which this event constitutes a part. +__Description:__ Identifies an issue that has been successfully verified. -### FLOW_CONTEXT +### VERIFICATION_BASIS __Required:__ No -__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) +__Legal targets:__ [EiffelTestCaseFinishedEvent](../eiffel-vocabulary/EiffelTestCaseFinishedEvent.md), [EiffelTestSuiteFinishedEvent](../eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md) __Multiple allowed:__ Yes -__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. +__Description:__ Used to declare the basis on which the verification statement(s) of this event have been issued. ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -116,7 +102,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -152,7 +137,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -164,60 +148,62 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 4.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 4.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 3.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelIssueVerifiedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 2.0.0 | [0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueVerifiedEvent.md) | Replaced data.issues with links | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 4.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 4.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 3.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelIssueVerifiedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 2.0.0 | [0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelIssueVerifiedEvent.md) | Replaced data.issues with links | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelIssueVerifiedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md b/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md index 60065411..361a1c19 100644 --- a/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md +++ b/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md @@ -1,18 +1,6 @@ # EiffelSourceChangeCreatedEvent (SCC) @@ -21,6 +9,7 @@ The EiffelSourceChangeCreatedEvent declares that a change to sources has been ma Where changes are integrated (or "submitted") directly on a shared branch of interest (e.g. "master", "dev" or "mainline") both EiffelSourceChangeCreatedEvent and EiffelSourceChangeSubmittedEvent are sent together. ## Data Members + ### data.author __Type:__ Object __Required:__ No @@ -91,17 +80,17 @@ __Type:__ String __Required:__ Yes __Description:__ The commit identity (hash) of the change. -#### data.gitIdentifier.branch +#### data.gitIdentifier.branch __Type:__ String __Required:__ No __Description:__ The name of the branch where the change was made. -#### data.gitIdentifier.repoName +#### data.gitIdentifier.repoName __Type:__ String __Required:__ No __Description:__ The name of the repository containing the change. -#### data.gitIdentifier.repoUri +#### data.gitIdentifier.repoUri __Type:__ String __Required:__ Yes __Description:__ The URI of the repository containing the change. @@ -116,17 +105,17 @@ __Type:__ Integer __Required:__ Yes __Description:__ The revision of the change. -#### data.svnIdentifier.directory +#### data.svnIdentifier.directory __Type:__ String __Required:__ Yes __Description:__ The directory (branch/tag) of the change. -#### data.svnIdentifier.repoName +#### data.svnIdentifier.repoName __Type:__ String __Required:__ No __Description:__ The name of the repository containing the change. -#### data.svnIdentifier.repoUri +#### data.svnIdentifier.repoUri __Type:__ String __Required:__ Yes __Description:__ The URI of the repository containing the change. @@ -186,50 +175,50 @@ __Legal targets:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/Eiffe __Multiple allowed:__ No __Description:__ Identifies the base revision of the created source change. -### PREVIOUS_VERSION +### CAUSE __Required:__ No -__Legal targets:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) +__Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the created source change. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. -### PARTIALLY_RESOLVED_ISSUE +### CONTEXT __Required:__ No -__Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies an issue that this event partially resolves. That is, this SCC introduces some change that has advanced an issue towards a resolved state, but not completely resolved. +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the activity or test suite of which this event constitutes a part. -### RESOLVED_ISSUE +### DERESOLVED_ISSUE __Required:__ No __Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md) __Multiple allowed:__ Yes -__Description:__ Identifies an issue that this SCC is claiming it has done enough to resolve. This is not an authoritative resolution, only a claim. The issue may or may not change status as a consequence this, e.g. through a [successful verification](../eiffel-vocabular/EiffelIssueVerifiedEvent.md) or a manual update on the issue tracker. +__Description:__ Identifies an issue which was previously resolved, but that this SCC claims it has made changes to warrant removing the resolved status. For example, if an issue "Feature X" was resolved, but this SCC removed the implmentation that led to "Feature X" being resolved, that issue should no longer be considered resolved. -### DERESOLVED_ISSUE +### FLOW_CONTEXT __Required:__ No -__Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md) +__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) __Multiple allowed:__ Yes -__Description:__ Identifies an issue which was previously resolved, but that this SCC claims it has made changes to warrant removing the resolved status. For example, if an issue "Feature X" was resolved, but this SCC removed the implmentation that led to "Feature X" being resolved, that issue should no longer be considered resolved. +__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. -### CAUSE +### PARTIALLY_RESOLVED_ISSUE __Required:__ No -__Legal targets:__ Any +__Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md) __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies an issue that this event partially resolves. That is, this SCC introduces some change that has advanced an issue towards a resolved state, but not completely resolved. -### CONTEXT +### PREVIOUS_VERSION __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the activity or test suite of which this event constitutes a part. +__Legal targets:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) +__Multiple allowed:__ Yes +__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the created source change. -### FLOW_CONTEXT +### RESOLVED_ISSUE __Required:__ No -__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) +__Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md) __Multiple allowed:__ Yes -__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. +__Description:__ Identifies an issue that this SCC is claiming it has done enough to resolve. This is not an authoritative resolution, only a claim. The issue may or may not change status as a consequence this, e.g. through a [successful verification](../eiffel-vocabular/EiffelIssueVerifiedEvent.md) or a manual update on the issue tracker. ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -262,7 +251,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -298,7 +286,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -310,60 +297,62 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 4.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 4.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 3.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 2.0.0 | [0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) | Replaced data.issues with links | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 4.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 4.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 3.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 2.0.0 | [0706840](../../../blob/070684053ceb1da5fb42d9f0ef21df816961d6bc/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) | Replaced data.issues with links | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelSourceChangeCreatedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md b/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md index b93cd1bf..d985f4b8 100644 --- a/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md +++ b/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md @@ -1,18 +1,6 @@ # EiffelSourceChangeSubmittedEvent (SCS) @@ -23,6 +11,7 @@ Typical use cases for EiffelSourceChangeSubmittedEvent is to signal that a patch Even though multiple types of identifiers are available (see below), the event SHOULD include one and SHALL not include more than one; changes to multiple repositories are represented by multiple events. ## Data Members + ### data.submitter __Type:__ Object __Required:__ No @@ -58,17 +47,17 @@ __Type:__ String __Required:__ Yes __Description:__ The commit identity (hash) of the change. -#### data.gitIdentifier.branch +#### data.gitIdentifier.branch __Type:__ String __Required:__ No __Description:__ The name of the branch where the change was made. -#### data.gitIdentifier.repoName +#### data.gitIdentifier.repoName __Type:__ String __Required:__ No __Description:__ The name of the repository containing the change. -#### data.gitIdentifier.repoUri +#### data.gitIdentifier.repoUri __Type:__ String __Required:__ Yes __Description:__ The URI of the repository containing the change. @@ -83,17 +72,17 @@ __Type:__ Integer __Required:__ Yes __Description:__ The revision of the change. -#### data.svnIdentifier.directory +#### data.svnIdentifier.directory __Type:__ String __Required:__ Yes __Description:__ The directory (branch/tag) of the change. -#### data.svnIdentifier.repoName +#### data.svnIdentifier.repoName __Type:__ String __Required:__ No __Description:__ The name of the repository containing the change. -#### data.svnIdentifier.repoUri +#### data.svnIdentifier.repoUri __Type:__ String __Required:__ Yes __Description:__ The URI of the repository containing the change. @@ -147,28 +136,21 @@ __Description:__ The URI of the repo. This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). +### CAUSE +__Required:__ No +__Legal targets:__ Any +__Multiple allowed:__ Yes +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. + ### CHANGE __Required:__ No __Legal targets:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the change that was submitted. -### PREVIOUS_VERSION -__Required:__ No -__Legal targets:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the submitted source change. - -### CAUSE -__Required:__ No -__Legal targets:__ Any -__Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. - ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -178,7 +160,14 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### PREVIOUS_VERSION +__Required:__ No +__Legal targets:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) +__Multiple allowed:__ Yes +__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the submitted source change. + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -211,7 +200,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -247,7 +235,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -259,59 +246,61 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelSourceChangeSubmittedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md b/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md index 1e027936..dd846e66 100644 --- a/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md +++ b/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md @@ -1,24 +1,13 @@ # EiffelTestCaseCanceledEvent (TCC) The EiffelTestCaseCanceledEvent declares that a previously triggered test case execution (represented by [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md)) 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. ## Data Members + ### data.reason __Type:__ String __Required:__ No @@ -28,12 +17,6 @@ __Description:__ Any human readable information as to the reason for dequeueing. This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### TEST_CASE_EXECUTION -__Required:__ Yes -__Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) acts as a handle for a particular test case execution. This differs from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries information pertaining to the target (i.e. the test case execution 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). - ### CAUSE __Required:__ No __Legal targets:__ Any @@ -42,8 +25,7 @@ __Description:__ While for most events it is recommended that __CAUSE__ SHOULD n ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -53,7 +35,14 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### TEST_CASE_EXECUTION +__Required:__ Yes +__Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) acts as a handle for a particular test case execution. This differs from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries information pertaining to the target (i.e. the test case execution 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). + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -86,7 +75,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -122,7 +110,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -134,60 +121,61 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. - ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelTestCaseCanceledEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md b/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md index 991cae8a..41485938 100644 --- a/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md +++ b/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md @@ -1,18 +1,6 @@ # EiffelTestCaseFinishedEvent (TCF) @@ -23,6 +11,7 @@ Note that while similar, the __data.outcome__ object is different from that of [ Also note that unlike [EiffelTestSuiteFinishedEvent](./EiffelTestSuiteFinishedEvent.md), EiffelTestCaseFinishedEvent must report both __data.outcome.verdict__ and __data.outcome.conclusion__. ## Data Members + ### data.outcome __Type:__ Object __Required:__ Yes @@ -32,7 +21,7 @@ __Description:__ The outcome of the test case. __Type:__ String __Required:__ Yes __Legal values:__ PASSED, FAILED, INCONCLUSIVE -__Description:__ A terse standardized verdict on the item or items under test. +__Description:__ A terse standardized verdict on the item or items under test. PASSED signifies that the item or items under test successfully passed the test case. FAILED signifies that the item or items under test failed to pass the test case. INCONCLUSIVE signifies that the verdict of the test case was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. @@ -41,7 +30,7 @@ INCONCLUSIVE signifies that the verdict of the test case was inconclusive. This __Type:__ String __Required:__ Yes __Legal values:__ SUCCESSFUL, FAILED, ABORTED, TIMED_OUT, INCONCLUSIVE -__Description:__ A terse standardized conclusion of the test case, designed to be machine readable. +__Description:__ A terse standardized conclusion of the test case, designed to be machine readable. SUCCESSFUL signifies that the test case was successfully concluded. Note that this does not imply that the item under test passed the tests. FAILED signifies that the test case could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. ABORTED signifies that the test case was aborted before it could be concluded. @@ -97,22 +86,15 @@ __Description:__ The URI at which the log can be retrieved. This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### TEST_CASE_EXECUTION -__Required:__ Yes -__Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) acts as a handle for a particular test case execution. This differs from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries information pertaining to the target (i.e. the test case execution 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). - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -122,7 +104,14 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### TEST_CASE_EXECUTION +__Required:__ Yes +__Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) acts as a handle for a particular test case execution. This differs from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries information pertaining to the target (i.e. the test case execution 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). + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -155,7 +144,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -191,7 +179,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -203,61 +190,63 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.1.0 | No edition set | Add `data.persistentLogs.{mediaType,tags}`. | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.1 | [0a2f9ef](../../../blob/0a2f9ef139fe6ead2493e5deddf1337ffb3dd4af/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md) | data.outcome.metrics.value and data.outcome.metrics.name made mandatory. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.1.0 | No edition set | Add `data.persistentLogs.{mediaType,tags}`. | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.1 | [0a2f9ef](../../../blob/0a2f9ef139fe6ead2493e5deddf1337ffb3dd4af/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md) | data.outcome.metrics.value and data.outcome.metrics.name made mandatory. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelTestCaseFinishedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelTestCaseStartedEvent.md b/eiffel-vocabulary/EiffelTestCaseStartedEvent.md index d4cac5a8..890e7177 100644 --- a/eiffel-vocabulary/EiffelTestCaseStartedEvent.md +++ b/eiffel-vocabulary/EiffelTestCaseStartedEvent.md @@ -1,24 +1,13 @@ # EiffelTestCaseStartedEvent (TCS) The EiffelTestCaseStartedEvent declares that the execution of a test case has commenced. This event SHALL be preceded by a [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md), and appropriately linked to via __TEST_CASE_EXECUTION__. ## Data Members + ### data.executor __Type:__ String __Required:__ No @@ -53,39 +42,38 @@ __Description:__ The URI at which the log can be retrieved. This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### TEST_CASE_EXECUTION -__Required:__ Yes -__Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) acts as a handle for a particular test case execution. This differs from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries information pertaining to the target (i.e. the test case execution 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). - -### ENVIRONMENT -__Required:__ No -__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the environment in which the test case is being executed. - - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. +### ENVIRONMENT +__Required:__ No +__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the environment in which the test case is being executed. + ### FLOW_CONTEXT __Required:__ No __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) __Multiple allowed:__ Yes __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. +### TEST_CASE_EXECUTION +__Required:__ Yes +__Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) acts as a handle for a particular test case execution. This differs from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries information pertaining to the target (i.e. the test case execution 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). + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -118,7 +106,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -154,7 +141,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -166,60 +152,62 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.1.0 | No edition set | Add `data.liveLogs.{mediaType,tags}`. | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseStartedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.1.0 | No edition set | Add `data.liveLogs.{mediaType,tags}`. | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseStartedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelTestCaseStartedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md b/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md index 9bb6d51a..4b557be1 100644 --- a/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md +++ b/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md @@ -1,18 +1,6 @@ # EiffelTestCaseTriggeredEvent (TCT) @@ -21,6 +9,7 @@ The EiffelTestCaseTriggeredEvent declares that the execution of a test case has This event is used to communicate intent, and thereby serves a similar purpose to that of [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md). A triggered test case execution is expected to either be started (represented by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) or canceled (represented by [EiffelTestCaseCanceledEvent](./EiffelTestCaseCanceledEvent.md)). Consequently, any delay between triggering and execution can be assumed to imply queuing time (e.g. waiting for available test resources) and monitored as such. ## Data Members + ### data.testCase __Type:__ Object __Required:__ Yes @@ -60,7 +49,7 @@ __Description:__ The circumstances triggering the test case execution. __Type:__ String __Required:__ Yes __Legal values:__ MANUAL, EIFFEL_EVENT, SOURCE_CHANGE, TIMER, OTHER -__Description:__ The type of trigger. +__Description:__ The type of trigger. MANUAL signifies that the test case execution was manually triggered. EIFFEL_EVENT signifies that the test case execution was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links. SOURCE_CHANGE signifies that the test case execution was triggered as a consequence of a detected source change __not__ represented by Eiffel events. @@ -97,39 +86,38 @@ __Description:__ The value of the parameter. This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### IUT -__Required:__ Yes -__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), -[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the Item Under Test; in other words, the entity that is about to be tested. - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. -### PRECURSOR -__Required:__ No -__Legal targets:__ [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md) -__Multiple allowed:__ Yes -__Description:__ Used to declare temporal relationships between [activities](../eiffel-syntax-and-usage/glossary.md#activity) in a [pipeline](../eiffel-syntax-and-usage/glossary.md#pipeline), i.e. what other activity/activities preceded this activity. This link type applies primarily to non event-triggered activities. For more information on the usage of this link type please see [Activity Linking](../eiffel-syntax-and-usage/activity-linking.md). - ### FLOW_CONTEXT __Required:__ No __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) __Multiple allowed:__ Yes __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. +### IUT +__Required:__ Yes +__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the Item Under Test; in other words, the entity that is about to be tested. + +### PRECURSOR +__Required:__ No +__Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) +__Multiple allowed:__ Yes +__Description:__ Used to declare temporal relationships between [activities](../eiffel-syntax-and-usage/glossary.md#activity) in a [pipeline](../eiffel-syntax-and-usage/glossary.md#pipeline), i.e. what other activity/activities preceded this activity. This link type applies primarily to non event-triggered activities. For more information on the usage of this link type please see [Activity Linking](../eiffel-syntax-and-usage/activity-linking.md). + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -162,7 +150,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -198,7 +185,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -210,60 +196,62 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.1.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelTestCaseTriggeredEvent/simple.json) * [Simple example using pre-3.0.0 meta.security object](../examples/events/EiffelTestCaseTriggeredEvent/simple-2.0.0.json) diff --git a/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md b/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md index a8110c59..ffa976f5 100644 --- a/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md +++ b/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md @@ -1,18 +1,6 @@ # EiffelTestExecutionRecipeCollectionCreatedEvent (TERCC) @@ -27,6 +15,7 @@ The __data__ object consists of two main parts. __data.selectionStrategy__ ident Finally, each recipe (__data.batches.recipes__) consists of two parts: the test case to execute, and the constraints of that execution. The EiffelTestExecutionRecipeCollectionCreatedEvent does not control the syntax of these constraints, as the nature of such constraints are highly dependent on technology domain and test execution framework. That being said, there are three questions that typically need to be answered: what is the item under test, in what kind of environment is it to be tested, and what are the test parameters? Note the distinction between test case and test execution: it is perfectly legal for a single test case to appear multiple times within the same EiffelTestExecutionRecipeCollectionCreatedEvent, but (presumably) with different constraints. ## Data Members + ### data.selectionStrategy __Type:__ Object __Required:__ Yes @@ -122,15 +111,15 @@ __Type:__ Object[] __Required:__ No __Description:__ A list of test case execution dependencies. Ideally, test cases are atomic and can be executed in isolation. In cases where a test case assumes that another test case has been executed previously in the same environment, however, this property can be used to specify that. It serves as an instruction to the test executor to place two executions subsequent to one another in the same environment. -##### data.batches.dependencies.dependency +##### data.batches.dependencies.dependent __Type:__ String __Required:__ Yes -__Description:__ The UUID of the dependency execution (__data.batches.recipes.id__), i.e. the execution that shall be performed prior to that of the dependent. +__Description:__ The UUID of the dependent execution (__data.batches.recipes.id__), i.e. the execution that shall be performed only after that of the dependency. -##### data.batches.dependencies.dependent +##### data.batches.dependencies.dependency __Type:__ String __Required:__ Yes -__Description:__ The UUID of the dependent execution (__data.batches.recipes.id__), i.e. the execution that shall be performed only after that of the dependency. +__Description:__ The UUID of the dependency execution (__data.batches.recipes.id__), i.e. the execution that shall be performed prior to that of the dependent. ## Links @@ -140,12 +129,11 @@ This section describes which link types are valid for this event type. For detai __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -156,6 +144,7 @@ __Multiple allowed:__ Yes __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. ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -188,7 +177,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -224,7 +212,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -236,64 +223,66 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 4.2.0 | No edition set | Add missing testCase.version member (see [Issue 288](https://github.com/eiffel-community/eiffel/issues/288)). | -| 4.1.1 | [edition-lyon](../../../tree/edition-lyon) | Add missing validation pattern to links.target member (see [Issue 271](https://github.com/eiffel-community/eiffel/issues/271)). | -| 4.1.0 | No edition set | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 4.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 3.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 2.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 2.0.0 | [f92e001](../../../blob/f92e001c88d1139a62f8ace976958e0a30d8f9c5/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md) | Changed syntax of data.batches.recipes.constraints from an uncontrolled object to a list of key-value pairs to comply with design guidelines. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 4.2.0 | No edition set | Add missing testCase.version member (see [Issue 288](https://github.com/eiffel-community/eiffel/issues/288)). | +| 4.1.1 | [edition-lyon](../../../tree/edition-lyon) | Add missing validation pattern to links.target member (see [Issue 271](https://github.com/eiffel-community/eiffel/issues/271)). | +| 4.1.0 | No edition set | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 4.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 3.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 2.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 2.0.0 | [f92e001](../../../blob/f92e001c88d1139a62f8ace976958e0a30d8f9c5/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md) | Changed syntax of data.batches.recipes.constraints from an uncontrolled object to a list of key-value pairs to comply with design guidelines. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Example using data.batches](../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches.json) * [Example using data.batches (1.0.0 syntax)](../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batches-1.0.0.json) * [Example using data.batchesUri](../examples/events/EiffelTestExecutionRecipeCollectionCreatedEvent/batchesUri.json) diff --git a/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md b/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md index 17d5ddda..378f5de9 100644 --- a/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md +++ b/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md @@ -1,18 +1,6 @@ # EiffelTestSuiteFinishedEvent (TSF) @@ -21,6 +9,7 @@ The EiffelTestSuiteFinishedEvent declares that a previously started test suite ( Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test suite reports not only the conclusion of the test suite execution - whether the tests were successfully executed - but also passes a verdict on the item or items under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included. ## Data Members + ### data.outcome __Type:__ Object __Required:__ No @@ -30,7 +19,7 @@ __Description:__ The outcome of the test suite. __Type:__ String __Required:__ No __Legal values:__ PASSED, FAILED, INCONCLUSIVE -__Description:__ A terse standardized verdict on the item or items under test. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the verdict of the test suite as a whole, but may be skipped. +__Description:__ A terse standardized verdict on the item or items under test. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the verdict of the test suite as a whole, but may be skipped. PASSED signifies that the item or items under test successfully passed the test suite. FAILED signifies that the item or items under test failed to pass the test suite. INCONCLUSIVE signifies that the verdict of the test suite was inconclusive. This SHOULD be the case if __data.outcome.conclusion__ is not __SUCCESSFUL__, but may in combination with a __SUCCESSFUL__ conclusion be used to represent unreliability or flakiness. @@ -39,7 +28,7 @@ INCONCLUSIVE signifies that the verdict of the test suite was inconclusive. This __Type:__ String __Required:__ No __Legal values:__ SUCCESSFUL, FAILED, ABORTED, TIMED_OUT, INCONCLUSIVE -__Description:__ A terse standardized conclusion of the test suite, designed to be machine readable. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the conclusion of the test suite as a whole, but may be skipped. +__Description:__ A terse standardized conclusion of the test suite, designed to be machine readable. Unlike in [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md), this property is optional. It offers a method of summarizing the conclusion of the test suite as a whole, but may be skipped. SUCCESSFUL signifies that the test suite was successfully concluded. Note that this does not imply that the item under test passed the tests. FAILED signifies that the test suite could not be successfully executed. To exemplify, one or more tests failed to run due to required environments being unavailable. ABORTED signifies that the test suite was aborted before it could be concluded. @@ -80,22 +69,15 @@ __Description:__ The URI at which the log can be retrieved. This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### TEST_SUITE_EXECUTION -__Required:__ Yes -__Legal targets:__ [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the relevant test suite execution. In other words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) acts as a handle for a particular test suite execution. - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. @@ -105,7 +87,14 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl __Multiple allowed:__ Yes __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. +### TEST_SUITE_EXECUTION +__Required:__ Yes +__Legal targets:__ [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the relevant test suite execution. In other words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) acts as a handle for a particular test suite execution. + ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -138,7 +127,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -174,7 +162,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -186,60 +173,62 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.1.0 | No edition set | Add `data.persistentLogs.{mediaType,tags}`. | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.1.0 | No edition set | Add `data.persistentLogs.{mediaType,tags}`. | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelTestSuiteFinishedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md b/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md index f18e09f5..b267e414 100644 --- a/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md +++ b/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md @@ -1,18 +1,6 @@ # EiffelTestSuiteStartedEvent (TSS) @@ -21,6 +9,7 @@ The EiffelTestSuiteStartedEvent declares that the execution of a test suite has In Eiffel, a test suite is nothing more or less than a collection of test case executions (see [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) and/or other test suite executions. The executed test suite may be an ad-hoc transient grouping of test cases that were executed at a particular time or place or for a particular purpose or a persistent entity tracked in a test management system - Eiffel makes no distinction or assumptions either way. ## Data Members + ### data.name __Type:__ String __Required:__ Yes @@ -66,38 +55,38 @@ __Description:__ The URI at which the log can be retrieved. This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). -### TERC -__Required:__ No -__Legal targets:__ [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md) -__Multiple allowed:__ No -__Description:__ This link signifies that the test suite represented by this event groups all test case executions resulting from the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). - ### CAUSE __Required:__ No __Legal targets:__ Any __Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. ### CONTEXT __Required:__ No -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ No __Description:__ Identifies the activity or test suite of which this event constitutes a part. +### FLOW_CONTEXT +__Required:__ No +__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) +__Multiple allowed:__ Yes +__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. + ### PRECURSOR __Required:__ No -__Legal targets:__ [EiffelTestSuiteStartedEvent](./EiffelTestSuiteStartedEvent.md) +__Legal targets:__ [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) __Multiple allowed:__ Yes __Description:__ Used to declare temporal relationships between [activities](../eiffel-syntax-and-usage/glossary.md#activity) in a [pipeline](../eiffel-syntax-and-usage/glossary.md#pipeline), i.e. what other activity/activities preceded this activity. This link type applies primarily to non event-triggered activities. For more information on the usage of this link type please see [Activity Linking](../eiffel-syntax-and-usage/activity-linking.md). -### FLOW_CONTEXT +### TERC __Required:__ No -__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) -__Multiple allowed:__ Yes -__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. +__Legal targets:__ [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md) +__Multiple allowed:__ No +__Description:__ This link signifies that the test suite represented by this event groups all test case executions resulting from the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). ## Meta Members + ### meta.id __Type:__ String __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) @@ -130,7 +119,6 @@ __Description:__ Any tags or keywords associated with the events, for searchabil ### meta.source __Type:__ Object -__Format:__ __Required:__ No __Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. @@ -166,7 +154,6 @@ __Description:__ The URI of, related to or describing the event sender. ### meta.security __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. @@ -178,60 +165,62 @@ __Description:__ The identity of the author of the event. This property is inten #### meta.security.integrityProtection __Type:__ Object -__Format:__ __Required:__ No __Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object: -1. Generate the entire event, but with the __meta.security.integrityProtection.signature__ value set to an empty string. -1. Serialize the event on [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). -1. Generate the signature using the __meta.security.integrityProtection.alg__ algorithm. -1. Set the __meta.security.integrityProtection.signature__ value to the resulting signature while maintaining Canonical JSON Form. + 1. Generate the entire event, but with the + __meta.security.integrityProtection.signature__ value set to + an empty string. + 1. Serialize the event on + [Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00). + 1. Generate the signature using the + __meta.security.integrityProtection.alg__ algorithm. + 1. Set the __meta.security.integrityProtection.signature__ value to + the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets __meta.security.integrityProtection.signature__ to an empty string and ensures Canonical JSON Form before verifying the signature. -##### meta.security.integrityProtection.alg +##### meta.security.integrityProtection.signature __Type:__ String -__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". +__Description:__ The signature produced by the signing algorithm. -##### meta.security.integrityProtection.signature +##### meta.security.integrityProtection.alg __Type:__ String -__Format:__ +__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none" __Required:__ Yes -__Description:__ The signature produced by the signing algorithm. +__Description:__ The cryptographic algorithm used to digitally sign the event. If no signing is performed, the __meta.security.integrityProtection__ SHALL be omitted rather than setting __meta.security.integrityProtection.alg__ to "none". ##### meta.security.integrityProtection.publicKey __Type:__ String -__Format:__ __Required:__ No __Description:__ The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via __meta.security.integrityProtection__. #### meta.security.sequenceProtection __Type:__ Object[] -__Format:__ __Required:__ No __Description:__ An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment __meta.security.sequenceProtection.position__ by 1. The first event produced in a given named sequence SHALL numbered 1. ##### meta.security.sequenceProtection.sequenceName __Type:__ String -__Format:__ __Required:__ Yes __Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event. ##### meta.security.sequenceProtection.position __Type:__ Integer -__Format:__ __Required:__ Yes __Description:__ The number of the event within the named sequence. ## Version History -| Version | Introduced in | Changes | -| --------- | ------------------------------------------------------ | --------------------------------------- | -| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | -| 3.1.0 | No edition set | Add `data.liveLogs.{mediaType,tags}`. | -| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | -| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | -| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | -| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +| 3.2.0 | [edition-lyon](../../../tree/edition-lyon) | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). | +| 3.1.0 | No edition set | Add `data.liveLogs.{mediaType,tags}`. | +| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)). | +| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) | +| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. | +| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | + ## Examples + * [Simple example](../examples/events/EiffelTestSuiteStartedEvent/simple.json) diff --git a/event_docs.md.j2 b/event_docs.md.j2 new file mode 100644 index 00000000..dea7bc23 --- /dev/null +++ b/event_docs.md.j2 @@ -0,0 +1,60 @@ + + +# {{ type }} ({{ abbrev }}) +{{ description }} + +## Data Members +{%- for field, field_data in data_members.items() %} + +{{ field | member_heading}} +__Type:__ {{ field_data.typ }} +{% if field_data.format -%} +__Format:__ {{ field_data.format }} +{% endif -%} +__Required:__ {{ field_data.required | yes_or_no }} +{% if field_data.legal_values -%} +__Legal values:__ {% for value in field_data.legal_values %}{{ value }}{{ ", " if not loop.last else "" }}{% endfor %} +{% endif -%} +__Description:__ {{ field_data.description }} +{%- endfor %} + +## Links + +This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md). +{%- for link_type, link_data in links.items() %} + +### {{ link_type }} +__Required:__ {{ link_data.required | yes_or_no }} +__Legal targets:__ {% if link_data.targets.any_type %}Any{% else %}{% for target_type in link_data.targets.types %}{{ target_type | event_link }}{{ ", " if not loop.last else "" }}{% endfor %}{% endif %} +__Multiple allowed:__ {{ link_data.multiple | yes_or_no }} +__Description:__ {{ link_data.description }} +{%- endfor %} + +## Meta Members +{%- for field, field_data in meta_members.items() %} + +{{ field | member_heading}} +__Type:__ {{ field_data.typ }} +{% if field_data.format -%} +__Format:__ {{ field_data.format }} +{% endif -%} +__Required:__ {{ field_data.required | yes_or_no }} +__Description:__ {{ field_data.description }} +{%- endfor %} + +## Version History + +| Version | Introduced in | Changes | +| ------- | ------------- | ------- | +{% for item in history -%} +| {{ item.version }} | {{ item.introduced_in }} | {{ item.changes }} | +{% endfor %} + +## Examples + +{% for ex in examples -%} +* [{{ ex.title }}]({{ ex.url }}) +{% endfor %} diff --git a/generate_docs.py b/generate_docs.py new file mode 100755 index 00000000..9bd721f8 --- /dev/null +++ b/generate_docs.py @@ -0,0 +1,167 @@ +#!/usr/bin/env python3 + +# 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. + +"""Reads an event definition file and transforms it into a +documentation Markdown file. + +Example: + + ./generate_docs.py definitions/EiffelCompositionDefinedEvent/3.2.0.yml +""" + +import dataclasses +import os.path +import sys +from pathlib import Path +from typing import Any +from typing import Dict +from typing import List +from typing import Optional +from typing import Set + +import jinja2 + +import definition_loader + +_OUTPUT_ROOT_PATH = Path("eiffel-vocabulary") + +# Optional list of field names that should be omitted from the documentation. +_SKIP_DOC_FIELDS = {"data.customData"} + + +@dataclasses.dataclass +class Member: + description: str + format: str + legal_values: List[Any] + name: str + typ: str + required: bool + + +def _filter_event_link(input: str) -> str: + """Jinja2 filter that transforms an event type name to a links to + the documentation of that event. + """ + if input.startswith("Eiffel") and input.endswith("Event"): + return f"[{input}](../eiffel-vocabulary/{input}.md)" + return input + + +def _filter_member_heading(input: str) -> str: + """Jinja2 filter that transforms an event member name to a section + heading with an appropriate depth. + """ + return (2 + input.count(".")) * "#" + " " + input + + +def _filter_yes_or_no(input: bool) -> str: + """Jinja2 filter that tranforms a boolean value into either "Yes" or "No".""" + return "Yes" if input else "No" + + +def _get_field_enum_values(field: Dict) -> Optional[List[Any]]: + """Returns a list of valid enum values if the given property is an + enum, otherwise None. + """ + try: + return field["enum"] + except KeyError: + try: + return field["items"]["enum"] + except KeyError: + return None + + +def _get_field_type(field: Dict) -> str: + """Returns the type of a field given its property definition. Scalar + types are simply titlecased and array properties are expressed as + "InnerType[]" where InnerType is the type of each item. + """ + if "type" not in field: + return "Any" + if field["type"] == "array": + return field["items"].get("type", "object").title() + "[]" + return field["type"].title() + + +def _get_members( + field_prefix: str, definitions: Dict, skip: Set[str] +) -> Dict[str, Member]: + """Returns a dict of Member objects, keyed by the full field name + (e.g. data.name or meta.source.name). Fields whose full name is + included in the skip set will be omitted from the result. + """ + result = {} + required = definitions.get("required", []) + for prop, prop_def in definitions.get("properties", {}).items(): + if "$ref" in prop_def: + continue + full_name = field_prefix + prop + if full_name in skip: + continue + result[full_name] = Member( + description=prop_def.get("_description", ""), + format=prop_def.get("_format"), + legal_values=_get_field_enum_values(prop_def), + name=full_name, + typ=_get_field_type(prop_def), + required=prop in required, + ) + if prop_def.get("type") == "object": + result.update(_get_members(field_prefix + prop + ".", prop_def, skip)) + elif prop_def.get("type") == "array": + result.update( + _get_members(field_prefix + prop + ".", prop_def["items"], skip) + ) + return result + + +def _main(): + env = jinja2.Environment(loader=jinja2.FileSystemLoader(".")) + env.filters["event_link"] = _filter_event_link + env.filters["member_heading"] = _filter_member_heading + env.filters["yes_or_no"] = _filter_yes_or_no + templ = env.get_template("event_docs.md.j2") + + for filename in sys.argv[1:]: + print(filename) + input_path = Path(filename) + schema = definition_loader.load(input_path) + output_path = (_OUTPUT_ROOT_PATH / input_path.parent.name).with_suffix(".md") + context = { + "type": input_path.parent.name, + "version": input_path.stem, + "description": schema.get("_description", ""), + "abbrev": schema.get("_abbrev", ""), + "links": schema.get("_links", {}), + "data_members": _get_members( + "data.", schema["properties"]["data"], _SKIP_DOC_FIELDS + ), + "meta_members": _get_members( + "meta.", schema["properties"]["meta"], _SKIP_DOC_FIELDS + ), + "examples": schema.get("_examples"), + "history": schema.get("_history"), + "source_file": os.path.relpath(input_path, output_path.parent), + } + with output_path.open(mode="w") as output_file: + output_file.write(templ.render(**context)) + + +if __name__ == "__main__": + _main() diff --git a/generate_schemas.py b/generate_schemas.py new file mode 100755 index 00000000..b06af51a --- /dev/null +++ b/generate_schemas.py @@ -0,0 +1,74 @@ +#!/usr/bin/env python3 + +# 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. + +"""Reads an event definition file and transforms it into a flat +schema file with all JSON references resolved and inlined. + +Example: + + ./generate_schemas.py definitions/EiffelCompositionDefinedEvent/3.2.0.yml +""" + +import json +import sys +from pathlib import Path +from typing import Dict + +import definition_loader + +_OUTPUT_ROOT_PATH = Path("schemas") + + +def _strip_extra_keys(data: Dict) -> None: + """Recursively remove all dict keys that begin with an underscore.""" + for key in list(data.keys()): + if key.startswith("_"): + del data[key] + continue + if isinstance(data[key], dict): + _strip_extra_keys(data[key]) + + +def _main(): + for filename in sys.argv[1:]: + print(filename) + input_path = Path(filename) + event_def = definition_loader.load(input_path) + + # At this point the event has been flattened to contain + # 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_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") + with output_path.open(mode="w") as output_file: + json.dump(event_def, output_file, indent=2) + output_file.write("\n") + + +if __name__ == "__main__": + _main() diff --git a/requirements.txt b/requirements.txt index 6babdf95..ef626dfd 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,5 @@ +Jinja2==3.0.3 +jsonref==0.2 jsonschema +ruamel.yaml==0.17.21 semver diff --git a/test_generate_doc.py b/test_generate_doc.py new file mode 100644 index 00000000..295e7b36 --- /dev/null +++ b/test_generate_doc.py @@ -0,0 +1,342 @@ +# 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. + +import generate_docs + +# +# _filter_event_link +# + + +def test_filter_event_link_eventname(): + assert ( + generate_docs._filter_event_link("EiffelCompositionDefinedEvent") + == "[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)" + ) + + +def test_filter_event_link_other_text(): + assert generate_docs._filter_event_link("random text") == "random text" + + +# +# _filter_member_heading +# + + +def test_filter_member_heading_level1_member(): + assert generate_docs._filter_member_heading("data.name") == "### data.name" + + +def test_filter_member_heading_level2_member(): + assert ( + generate_docs._filter_member_heading("meta.source.name") + == "#### meta.source.name" + ) + + +# +# _get_field_enum_values +# + + +def test_get_field_enum_values_non_enum(): + assert ( + generate_docs._get_field_enum_values( + { + "type": "string", + } + ) + is None + ) + + +def test_get_field_enum_values_plain_num(): + assert generate_docs._get_field_enum_values( + { + "type": "string", + "enum": ["A", "B", "C"], + } + ) == ["A", "B", "C"] + + +def test_get_field_enum_values_array(): + assert generate_docs._get_field_enum_values( + { + "type": "array", + "items": { + "type": "string", + "enum": ["A", "B", "C"], + }, + } + ) == ["A", "B", "C"] + + +# +# _get_field_type +# + + +def test_get_field_type_plain_scalar(): + assert ( + generate_docs._get_field_type( + { + "type": "string", + } + ) + == "String" + ) + + +def test_get_field_type_array_of_scalars(): + assert ( + generate_docs._get_field_type( + { + "type": "array", + "items": { + "type": "string", + }, + } + ) + == "String[]" + ) + + +def test_get_field_type_missing_type(): + assert generate_docs._get_field_type({}) == "Any" + + +# +# _get_members +# + + +def test_get_members_skips_refs(): + """Normally we'd resolve all JSON references, but if any of them are + still around we'll just skip them. + """ + assert ( + generate_docs._get_members( + "", + { + "properties": { + "random_field": { + "$ref": "foo/bar.json", + }, + }, + }, + set(), + ) + == {} + ) + + +def test_get_members_respects_skipped_fields(): + """Fields included in the skip set aren't included in the returned dict.""" + assert generate_docs._get_members( + "", + { + "properties": { + "meta": { + "type": "object", + "properties": { + "id": { + "type": "string", + }, + }, + }, + "data": { + "type": "object", + "properties": { + "name": { + "type": "string", + }, + "version": { + "type": "string", + }, + }, + }, + }, + }, + { + "meta", # Skips top-level field and all subfields. + "data.name", # Skips leaf field but leaves others alone. + }, + ) == { + "data": generate_docs.Member( + description="", + format=None, + legal_values=None, + name="data", + typ="Object", + required=False, + ), + "data.version": generate_docs.Member( + description="", + format=None, + legal_values=None, + name="data.version", + typ="String", + required=False, + ), + } + + +def test_get_members_plain_scalar_field(): + assert generate_docs._get_members( + "", + { + "properties": { + "foo": { + "_description": "This is a foo.", + "_format": "URL", + "type": "string", + }, + }, + }, + set(), + ) == { + "foo": generate_docs.Member( + description="This is a foo.", + format="URL", + legal_values=None, + name="foo", + typ="String", + required=False, + ), + } + + +def test_get_members_recursive_fields(): + assert generate_docs._get_members( + "", + { + "properties": { + "foo": { + "_description": "This is a foo.", + "_format": "URL", + "type": "object", + "properties": { + "bar": { + "_description": "This is a bar.", + "_format": "UUID", + "type": "string", + }, + }, + }, + }, + }, + set(), + ) == { + "foo": generate_docs.Member( + description="This is a foo.", + format="URL", + legal_values=None, + name="foo", + typ="Object", + required=False, + ), + "foo.bar": generate_docs.Member( + description="This is a bar.", + format="UUID", + legal_values=None, + name="foo.bar", + typ="String", + required=False, + ), + } + + +def test_get_members_enumerated_field(): + assert generate_docs._get_members( + "", + { + "properties": { + "foo": { + "_description": "This is a foo.", + "_format": "URL", + "type": "string", + "enum": [ + "foo", + "bar", + ], + }, + }, + }, + set(), + ) == { + "foo": generate_docs.Member( + description="This is a foo.", + format="URL", + legal_values=["foo", "bar"], + name="foo", + typ="String", + required=False, + ), + } + + +def test_get_members_required_field(): + assert generate_docs._get_members( + "", + { + "properties": { + "foo": { + "_description": "This is a foo.", + "_format": "URL", + "type": "string", + }, + }, + "required": ["foo"], + }, + set(), + ) == { + "foo": generate_docs.Member( + description="This is a foo.", + format="URL", + legal_values=None, + name="foo", + typ="String", + required=True, + ), + } + + +def test_get_members_scalar_arrays(): + assert generate_docs._get_members( + "", + { + "properties": { + "foo": { + "_description": "This is a foo.", + "_format": "URL", + "type": "array", + "items": { + "type": "string", + }, + }, + }, + }, + set(), + ) == { + "foo": generate_docs.Member( + description="This is a foo.", + format="URL", + legal_values=None, + name="foo", + typ="String[]", + required=False, + ), + } diff --git a/tox.ini b/tox.ini index 2248331e..aadab5c6 100644 --- a/tox.ini +++ b/tox.ini @@ -20,6 +20,7 @@ envlist = black isort jsonformat + pytest skip_missing_interpreters = True skipsdist = True @@ -44,7 +45,13 @@ commands = isort --check-only --diff . [testenv:jsonformat] deps = pytest==6.2.5 -commands = pytest +commands = pytest test_jsonformat.py {posargs} + +[testenv:pytest] +deps = + -rrequirements.txt + pytest==6.2.5 +commands = pytest --ignore=test_jsonformat.py {posargs} [testenv:validate] deps = -rrequirements.txt @@ -53,8 +60,12 @@ commands = python3 examples/validate.py [flake8] # Ignore a few formatting aspects that we let Black take care of. ignore = + E211 + E302 E501 + W293 W503 + W391 [isort] atomic = True