-
Notifications
You must be signed in to change notification settings - Fork 10
/
traits.yml
325 lines (282 loc) · 12.1 KB
/
traits.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
# yaml-language-server: $schema=https://raw.githubusercontent.com/OpenAssetIO/OpenAssetIO-TraitGen/main/python/openassetio_traitgen/schema.json
# yamllint disable-line rule:document-start
package: openassetio-mediacreation
description: Well-known Traits and Specifications for use in OpenAssetIO
hosts and managers.
traits:
usage:
description: >
Base traits that scope a trait set for use within a specific
context, such as resolution or relationship queries. Exactly
one of these should be included in any given Specification.
members:
Entity:
description: The trait set defines qualities of an entity.
usage:
- entity
Relationship:
description: >
The trait set defines a relationship between one or more
entities.
usage:
- relationship
content:
description: Traits related to abstract content.
members:
LocatableContent:
description: >
This trait characterizes an entity whose data is persisted
externally to the API through data accessible via a valid
URL.
The `location` property holds the most applicable location
of the entity's content for the current process environment
- considering platform, host, etc. Location is in the form
of a URL.
usage:
- entity
properties:
location:
type: string
description: >
The location of the entity's external content.
This must be a valid URL, so special characters need to
be encoded accordingly.
identity:
description: Traits that aid the identification of an entity.
members:
DisplayName:
description: >
Names that can be presented to a user in order to identify
and/or disambiguate the entity. These strings are potentially
unstable and should not be used as a UUID or other persistent
anchor.
usage:
- entity
properties:
name:
type: string
description: >
The humanized name of entity itself, not including any
hierarchy or classification.
For example:
- `"Cuttlefish v1"` - for a version of an asset
- `"seq003"` - for a sequence in a hierarchy
qualifiedName:
type: string
description: >
An unambiguous, humanized name for the entity.
The display name may want to consider the host, and any other
relevant Context information to form a display name for an
entity that can uniquely identify the entity in that context.
For example:
- `"dive / build / cuttlefish / model / v1"` for a version
of an asset in an 'open recent' menu.
- `"Sequence 003 [ Dive / Episode 1 ]"` for a sequence in
a hierarchy as a window title.
lifecycle:
description: >
Traits that are concerned with describing aspects of the lifecycle
of an entity, such as versioning.
members:
Version:
description: >
Describes a specific version of an entity.
A version is defined as a revision or iteration of what is
otherwise the same logical entity. If supported by a manager,
versions are created when new data is published to an existing
entity. Not all managers may version all types of entity.
There is no requirement for version to be a singular atomic
series, managers may wish to support "meta versions", such as
'vLatest' or similar, or provide multiple parallel versioning
streams.
This trait can be used in several places:
- When resolved, the manager should provide information about
the version of the referenced entity. This trait should only
be imbued if the target entity is considered versioned by the
manager, and it can populate the stableTag property.
- When responding to managementPolicy for an entity trait set,
the manager should imbue this trait if that type of entity
is version managed by the manager (not all managers version
all types of entity).
- When used within a relationship query, this trait indicates
that the returned entities should be constrained to other
versions of the logical entity targeted by the reference.
usage:
- entity
- relationship
- managementPolicy
properties:
specifiedTag:
type: string
description: >
An unambiguous identifier (tag) for the specific version of
an entity targeted by a specific reference.
Examples of version tags include "1", "v2", "latest".
If the reference itself does not contain a version
specifier and relies on dynamic behaviour, then this should
be left empty.
stableTag:
type: string
description: >
The tag (see 'specifiedTag') targeted by the reference once
meta-versions or other dynamic behaviour is applied.
If, for example, references without an explicit version
yield the most recent, then this should be set to
the tag of that version. When referencing some other
semantic state (eg. approval), this should be set to the
tag of the concrete version that matches the specific
state.
Examples of stable version tags include "1", "v2".
This property should always be set when the Version trait
is imbued as part of a resolve response. If the entity is
not versioned, then the trait itself should not be imbued.
Stable:
description: >
Defines that the entity references returned from a
relationship query with this trait should be devoid of any
dynamic behaviour. This includes concepts such as
meta-versioning or context-specific variation that results
logically different data being supplied.
This is generally used to snapshot/bookmark specific
configurations to avoid temporal instability and/or ensure
processes are repeatable.
Note: This does not include variations such as regional
adaptation of the LocatableContent trait, where the underlying
data remains the same.
usage:
- relationship
managementPolicy:
description: Traits used in a Manager's managementPolicy response.
members:
Managed:
description: >
A trait indicating that the data matching the supplied trait set
is handled by the manager.
There are three possible policies determined by
applying/querying this trait:
* If the response is not imbued with this trait, then the
Manager has no interest in participating in the management of
entities that match the queried trait set, for either read or
write.
* If the response is imbued with this trait, but the "exclusive"
property is not set, or set to False, then the Manager would
like the opportunity to manage the data, but the user should
still be presented with standard Host UI for the type as an
option.
* If the "exclusive" property is set to true, then the Manager
takes exclusive control over data with the queried trait set,
and any standard host interfaces etc should be suppressed.
usage:
- managementPolicy
properties:
exclusive:
type: boolean
description: >
Determines if the manager exclusively handles data matching
the supplied trait set.
If True, then standard host contols should be disabled
in favour of manager delegated UI. For example, file system
browsers when determining where to load/save data.
If False, then standard host controls can be presented in
addition to any custom manager UI.
ResolvesFutureEntities:
description: >
A trait indicating a manager can potentially resolve the
supplied trait set for future entities.
If not imbued, the manager is not capable of determining data
in advance for new entities, and is only capable of resolving
traits for exising ones.
An example of this would be the ability to resolve a
LocatableContentTrait in advance, to determine where new data
should be written. When this trait imbued in the
managementPolicy response, a host may attempt to resolve the
locatableContent trait of a working entity reference supplied by
preflight in order to determine a suitable output path before
work is done. In its absence, a host must use alternate means to
determine a suitable output location.
usage:
- managementPolicy
relationship:
description: Traits specific to qualities of a relationship.
members:
Singular:
description: >
The relationship should return at most one reference for each
input. Unless otherwise qualified, relationships are
considered one-to-many.
usage:
- relationship
Unbounded:
description: >
The relationship may return large numbers of results for each
input, and so must be used with the paged API methods, such as
Manager.getWithRelationshipPaged.
usage:
- relationship
auth:
description: Traits related to authentication and authorization.
members:
BearerToken:
description: >
This trait holds an authentication token that the manager may
pass to a back-end service.
usage:
- locale
properties:
token:
type: string
description: >
Contents of the token.
specifications:
lifecycle:
description:
Specifications that are concerned with describing aspects of the
lifecycle of an entity, such as versioning.
members:
EntityVersionsRelationship:
description: >
A relationship between alternate versions of the same logical
entity. This may include unstable versions such as "latest".
traitSet:
- namespace: usage
name: Relationship
- namespace: relationship
name: Unbounded
- namespace: lifecycle
name: Version
usage:
- relationship
StableEntityVersionsRelationship:
description: >
Retrieves references to alternate stable versions of the same
logical entity. This will not include unstable versions such
as "latest".
traitSet:
- namespace: usage
name: Relationship
- namespace: relationship
name: Unbounded
- namespace: lifecycle
name: Version
- namespace: lifecycle
name: Stable
usage:
- relationship
StableReferenceRelationship:
description: >
Retrieves a stable reference to the supplied entity that is
guaranteed to always point to that specific entity and version.
This will apply and remove any dynamic behaviour such as
"latest version" or other context-sensitive behaviour. The
result may be used as a persistent bookmark (such as in an
"open recent" menu), or to snapshot the specific entities used
by a process for archival.
traitSet:
- namespace: usage
name: Relationship
- namespace: relationship
name: Singular
- namespace: lifecycle
name: Stable
usage:
- relationship