Skip to content

Commit 68106cf

Browse files
magnusbaeckmagnusbaeck
committed
Demonstration of experimental event version
1 parent e72d305 commit 68106cf

File tree

6 files changed

+768
-1
lines changed

6 files changed

+768
-1
lines changed

‎definitions/EiffelCompositionDefinedEvent/3.4.0.yml‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Copyright 2017-2022 Ericsson AB and others.
2+
# For a full list of individual contributors, please see the commit history.
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
---
16+
$schema: http://json-schema.org/draft-04/schema#
17+
_abbrev: CD
18+
_description: The EiffelCompositionDefinedEvent declares a composition
19+
of items (artifacts, sources and other compositions) has been defined,
20+
typically with the purpose of enabling further downstream artifacts
21+
to be generated.
22+
type: object
23+
properties:
24+
meta:
25+
$ref: ../EiffelMetaProperty/3.1.0.yml
26+
data:
27+
type: object
28+
properties:
29+
name:
30+
_description: The name of the composition.
31+
type: string
32+
version:
33+
_description: The version of the composition, if any. This
34+
is in a sense redundant, as relationships between compositions
35+
can be tracked via the __PREVIOUS_VERSION__ link type, but
36+
can be used for improved clarity and semantics.
37+
type: string
38+
customData:
39+
type: array
40+
items:
41+
$ref: ../EiffelCustomDataProperty/1.0.0.yml
42+
required:
43+
- name
44+
additionalProperties: false
45+
links:
46+
type: array
47+
items:
48+
$ref: ../EiffelEventLink/1.1.1.yml
49+
required:
50+
- meta
51+
- data
52+
- links
53+
additionalProperties: false
54+
_links:
55+
FOO:
56+
description: Lorum ipsum.
57+
required: false
58+
multiple: false
59+
experimental: true
60+
targets:
61+
any_type: false
62+
types:
63+
- EiffelExperimentalEvent
64+
CAUSE:
65+
description: 'Identifies a cause of the event occurring. SHOULD
66+
not be used in conjunction with __CONTEXT__: individual events
67+
providing __CAUSE__ within a larger context gives rise to ambiguity.
68+
It is instead recommended to let the root event of the context
69+
declare __CAUSE__.'
70+
required: false
71+
multiple: true
72+
targets:
73+
any_type: true
74+
types: []
75+
CONTEXT:
76+
description: Identifies the activity or test suite of which this
77+
event constitutes a part.
78+
required: false
79+
multiple: false
80+
targets:
81+
any_type: false
82+
types:
83+
- EiffelActivityTriggeredEvent
84+
- EiffelTestSuiteStartedEvent
85+
ELEMENT:
86+
description: Identifies an element and/or sub-composition of this
87+
composition. The latter is particularly useful for documenting
88+
large and potentially decentralized compositions, and may be
89+
used to reduce the need to repeat large compositions in which
90+
only small parts are subject to frequent change.
91+
required: false
92+
multiple: true
93+
targets:
94+
any_type: false
95+
types:
96+
- EiffelArtifactCreatedEvent
97+
- EiffelCompositionDefinedEvent
98+
- EiffelSourceChangeCreatedEvent
99+
- EiffelSourceChangeSubmittedEvent
100+
FLOW_CONTEXT:
101+
description: 'Identifies the flow context of the event: which is
102+
the continuous integration and delivery flow in which this occurred
103+
– e.g. which product, project, track or version this is applicable
104+
to.'
105+
required: false
106+
multiple: true
107+
targets:
108+
any_type: false
109+
types:
110+
- EiffelFlowContextDefinedEvent
111+
PREVIOUS_VERSION:
112+
description: Identifies a latest previous version (there may be
113+
more than one in case of merges) of the composition.
114+
required: false
115+
multiple: true
116+
targets:
117+
any_type: false
118+
types:
119+
- EiffelCompositionDefinedEvent
120+
_history:
121+
- version: 3.3.0
122+
introduced_in: '[edition-arica](../../../tree/edition-arica)'
123+
changes: Add schema URL to the meta object (see [Issue 280](https://github.com/eiffel-community/eiffel/issues/280)).
124+
- version: 3.2.0
125+
introduced_in: '[edition-lyon](../../../tree/edition-lyon)'
126+
changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)).
127+
- version: 3.1.0
128+
introduced_in: '[edition-paris](../../../tree/edition-paris)'
129+
changes: Added SCC as valid target for ELEMENT links (see [Issue
130+
218](https://github.com/eiffel-community/eiffel/issues/218))
131+
- version: 3.0.0
132+
introduced_in: '[edition-agen](../../../tree/edition-agen)'
133+
changes: Improved information integrity protection (see [Issue
134+
185](https://github.com/eiffel-community/eiffel/issues/185)).
135+
- version: 2.0.0
136+
introduced_in: '[dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelCompositionDefinedEvent.md)'
137+
changes: Introduced purl identifiers instead of GAVs (see [Issue
138+
182](https://github.com/eiffel-community/eiffel/issues/182))
139+
- version: 1.1.0
140+
introduced_in: '[edition-toulouse](../../../tree/edition-toulouse)'
141+
changes: Multiple links of type FLOW_CONTEXT allowed.
142+
- version: 1.0.0
143+
introduced_in: '[edition-bordeaux](../../../tree/edition-bordeaux)'
144+
changes: Initial version.
145+
_examples:
146+
- title: Simple example
147+
url: ../examples/events/EiffelCompositionDefinedEvent/simple.json

‎definitions/EiffelExperimentalEvent/0.1.0.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Copyright 2017-2022 Ericsson AB and others.
2+
# For a full list of individual contributors, please see the commit history.
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
---
16+
$schema: http://json-schema.org/draft-04/schema#
17+
_abbrev: CD
18+
_description: >
19+
This is an experimental event type created for entertainment purpoes.
20+
type: object
21+
properties:
22+
meta:
23+
$ref: ../EiffelMetaProperty/3.1.0.yml
24+
data:
25+
type: object
26+
properties:
27+
name:
28+
_description: The name of something.
29+
type: string
30+
customData:
31+
type: array
32+
items:
33+
$ref: ../EiffelCustomDataProperty/1.0.0.yml
34+
required:
35+
- name
36+
additionalProperties: false
37+
links:
38+
type: array
39+
items:
40+
$ref: ../EiffelEventLink/1.1.1.yml
41+
required:
42+
- meta
43+
- data
44+
- links
45+
additionalProperties: false
46+
_links:
47+
CAUSE:
48+
description: 'Identifies a cause of the event occurring. SHOULD
49+
not be used in conjunction with __CONTEXT__: individual events
50+
providing __CAUSE__ within a larger context gives rise to ambiguity.
51+
It is instead recommended to let the root event of the context
52+
declare __CAUSE__.'
53+
required: false
54+
multiple: true
55+
targets:
56+
any_type: true
57+
types: []
58+
_history:
59+
- version: 0.1.0
60+
introduced_in: No edition set.
61+
changes: Initial version.
62+
_examples: []

‎eiffel-vocabulary/EiffelCompositionDefinedEvent.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
This file was generated from ../definitions/EiffelCompositionDefinedEvent/3.3.0.yml.
2+
This file was generated from ../definitions/EiffelCompositionDefinedEvent/3.4.0.yml.
33
See that file for a copyright notice.
44
--->
55

@@ -23,6 +23,12 @@ __Description:__ The version of the composition, if any. This is in a sense redu
2323

2424
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).
2525

26+
### FOO
27+
__Required:__ No
28+
__Legal targets:__ [EiffelExperimentalEvent](../eiffel-vocabulary/EiffelExperimentalEvent.md)
29+
__Multiple allowed:__ No
30+
__Description:__ Lorum ipsum. This link type is experimental and may be removed in a future version of the event.
31+
2632
### CAUSE
2733
__Required:__ No
2834
__Legal targets:__ Any

‎eiffel-vocabulary/EiffelExperimentalEvent.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
<!---
2+
This file was generated from ../definitions/EiffelExperimentalEvent/0.1.0.yml.
3+
See that file for a copyright notice.
4+
--->
5+
6+
# EiffelExperimentalEvent (CD)
7+
> :warning: This event type is currently at version 0.1.0 and is therefore experimental. Until it has reached version 1.0.0 it may undergo any number of backwards incomptaible changes. It might also be deprecated and never reach 1.0.0.
8+
9+
This is an experimental event type created for entertainment purpoes.
10+
11+
12+
## Data Members
13+
14+
### data.name
15+
__Type:__ String
16+
__Required:__ Yes
17+
__Description:__ The name of something.
18+
19+
## Links
20+
21+
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).
22+
23+
### CAUSE
24+
__Required:__ No
25+
__Legal targets:__ Any
26+
__Multiple allowed:__ Yes
27+
__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__.
28+
29+
## Meta Members
30+
31+
### meta.id
32+
__Type:__ String
33+
__Format:__ [UUID](http://tools.ietf.org/html/rfc4122)
34+
__Required:__ Yes
35+
__Description:__ The unique identity of the event, generated at event creation.
36+
37+
### meta.type
38+
__Type:__ String
39+
__Format:__ An event type name
40+
__Required:__ Yes
41+
__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.
42+
43+
### meta.version
44+
__Type:__ String
45+
__Format:__ [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html)
46+
__Required:__ Yes
47+
__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.
48+
49+
### meta.time
50+
__Type:__ Integer
51+
__Format:__ UNIX Epoch time, in milliseconds.
52+
__Required:__ Yes
53+
__Description:__ The event creation timestamp.
54+
55+
### meta.tags
56+
__Type:__ String[]
57+
__Format:__ Free text
58+
__Required:__ No
59+
__Description:__ Any tags or keywords associated with the events, for searchability purposes.
60+
61+
### meta.source
62+
__Type:__ Object
63+
__Required:__ No
64+
__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.
65+
66+
#### meta.source.domainId
67+
__Type:__ String
68+
__Format:__ Free text
69+
__Required:__ No
70+
__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
71+
72+
#### meta.source.host
73+
__Type:__ String
74+
__Format:__ Hostname
75+
__Required:__ No
76+
__Description:__ The hostname of the event sender.
77+
78+
#### meta.source.name
79+
__Type:__ String
80+
__Format:__ Free text
81+
__Required:__ No
82+
__Description:__ The name of the event sender.
83+
84+
#### meta.source.serializer
85+
__Type:__ String
86+
__Format:__ [purl specification](https://github.com/package-url/purl-spec)
87+
__Required:__ No
88+
__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
89+
90+
#### meta.source.uri
91+
__Type:__ String
92+
__Format:__ URI
93+
__Required:__ No
94+
__Description:__ The URI of, related to or describing the event sender.
95+
96+
### meta.security
97+
__Type:__ Object
98+
__Required:__ No
99+
__Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information.
100+
101+
#### meta.security.authorIdentity
102+
__Type:__ String
103+
__Format:__ [Distinguished Name](https://tools.ietf.org/html/rfc2253)
104+
__Required:__ Yes
105+
__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.
106+
107+
#### meta.security.integrityProtection
108+
__Type:__ Object
109+
__Required:__ No
110+
__Description:__ An optional object for enabling information integrity protection via cryptographic signing. To generate a correct __meta.security.integrityProtection__ object:
111+
1. Generate the entire event, but with the
112+
__meta.security.integrityProtection.signature__ value set to
113+
an empty string.
114+
1. Serialize the event on
115+
[Canonical JSON Form](https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00).
116+
1. Generate the signature using the
117+
__meta.security.integrityProtection.alg__ algorithm.
118+
1. Set the __meta.security.integrityProtection.signature__ value to
119+
the resulting signature while maintaining Canonical JSON Form.
120+
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.
121+
122+
##### meta.security.integrityProtection.signature
123+
__Type:__ String
124+
__Required:__ Yes
125+
__Description:__ The signature produced by the signing algorithm.
126+
127+
##### meta.security.integrityProtection.alg
128+
__Type:__ String
129+
__Format:__ [A valid JWA RFC 7518 alg parameter value](https://tools.ietf.org/html/rfc7518#section-3.1), excluding "none"
130+
__Required:__ Yes
131+
__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".
132+
133+
##### meta.security.integrityProtection.publicKey
134+
__Type:__ String
135+
__Required:__ No
136+
__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__.
137+
138+
#### meta.security.sequenceProtection
139+
__Type:__ Object[]
140+
__Required:__ No
141+
__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.
142+
143+
##### meta.security.sequenceProtection.sequenceName
144+
__Type:__ String
145+
__Required:__ Yes
146+
__Description:__ The name of the sequence. There MUST not be two identical __meta.security.sequenceProtection.sequenceName__ values in the same event.
147+
148+
##### meta.security.sequenceProtection.position
149+
__Type:__ Integer
150+
__Required:__ Yes
151+
__Description:__ The number of the event within the named sequence.
152+
153+
### meta.schemaUri
154+
__Type:__ String
155+
__Format:__ URI
156+
__Required:__ No
157+
__Description:__ A URI pointing at a location from where the schema used when creating this event can be retrieved. It can be used to parse event data for validation and extraction purposes, for example. Note, that the schema on that URI should be considered immutable.
158+
159+
## Version History
160+
161+
| Version | Introduced in | Changes |
162+
| ------- | ------------- | ------- |
163+
| 0.1.0 | No edition set. | Initial version. |
164+
165+
166+
## Examples
167+

0 commit comments

Comments
 (0)