You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: proposals/common-definitions/README.md
+32-39Lines changed: 32 additions & 39 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -107,20 +107,23 @@ Related Issues:
107
107
108
108
## Basic mechanism
109
109
110
-
Forms and schemas are impacted by this.
111
-
112
110
### Defaultable form elements
113
111
114
112
Forms and schemas are defaultable and have a container `formDefinitions` and `schemaDefinitions` at the root of the Thing that is a map of Forms and Schemas, respectively.
115
113
Using `formDefaults` or `schemaDefaults` as an array in the root level chooses which of the previously-defined definitions are default for the Thing.
116
114
117
-
TODO: Every element can have a term `inherit` that points to a single element in their corresponding definitions. If inherit is populated all the fields in the pointed element are used as default for the current element.
118
-
119
115
### Inlining
120
116
121
117
Using `formDefaults` or `schemaDefaults` with an object in the root level removes the need for `formDefinitions` or `schemaDefinitions` and you can define the default for the Thing within the object, thus not needing to define before using.
122
118
This mechanism is called inlining a definition.
123
119
120
+
### Overriding
121
+
122
+
The defaults defined in the root level (definition or inlining), can be overwritten in two ways:
123
+
124
+
1. A form can redefine the specific keyword in the defaults object, i.e. `contentType` or use an absolute URI in the value `href`. This way, the default defined in the Thing-level is overridden.
125
+
2. A form can use the `form` keyword and point to a form definition from `formDefinitions`. That way, that specific form would use the keys and values defined at that definition instead of the default one.
126
+
124
127
## Keywords and Types
125
128
126
129
### Thing Level
@@ -129,63 +132,52 @@ This mechanism is called inlining a definition.
129
132
130
133
These set a default for the whole Thing. The mechanism is the same for all the terms, i.e. if the term has an array of strings value, each string is a reference and if it has an object value, it is an in-place definition.
131
134
132
-
| Vocabulary Term | Description | Assignment | Type | Remarks |
| formDefaults |A reference to or an in-place definition of a Form, if missing the affordance/operation-specific defaults apply. | optional | Array with items pointing to the `formDefinitions` map or Object with type`Form`. | If Array, the items have an `OR` relationship key, meaning multiple form defaults can be used. |
135
-
| schemaDefaults |A reference to or an in-place definition of a Data Schema | optional | Array with items pointing to the `schemaDefinitions` map or Object with type `DataSchema`. ||
135
+
| Vocabulary Term | Description | Assignment | Type | Remarks|
| formDefaults |Reference(s) to or an in-place definition of a Form. If there are missing terms, the affordance/operation-specific defaults apply. | optional | Array with String Items pointing to the `formDefinitions` map or Object of type`Form`. | The items have an `OR` relationship key, meaning multiple forms with defaults can be used in an affordance. |
138
+
| schemaDefaults |Reference(s) to or an in-place definition of a Data Schema | optional | Array with String Items pointing to the `schemaDefinitions` map or Object with type `DataSchema`. ||
136
139
137
-
#### Definitions/Defaults container
140
+
#### Definitions container
138
141
139
-
| Vocabulary Term | Description | Assignment | Type | Remarks |
| formDefinitions | A set of form information that can be referenced in a form to group common form information such as `contentType`, `base`, `security`, or binding-specific terms. | optional | Map of Object with of type `Form`| The first-level keys are free to choose by the TD producer. |
142
-
| schemaDefinitions | A set of Data Schemas to group common payload structures | optional | Map of Object with of type `DataSchema`| The first-level keys are free to choose by the TD producer. Same as TD 1.1 |
142
+
| Vocabulary Term | Description | Assignment | Type | Remarks |
| formDefinitions | A set of form information that can be referenced in a form or in `formDefaults`to group common form information such as `contentType`, `base`, `security`, or binding-specific terms. | optional | Map of Object with of type `Form`| The first-level keys are free to choose by the TD producer. |
145
+
| schemaDefinitions | A set of Data Schemas to group common payload structures | optional | Map of Object with of type `DataSchema`| The first-level keys are free to choose by the TD producer. Same as TD 1.1 |
143
146
144
147
Note: Even if a single form of an affordance is not complete, a defaultable element should exist.
145
148
146
-
### Elements
147
-
148
-
#### Overall Rules
149
-
150
-
- TODO: All of them contain `inherit`, which has type `String`
151
-
- Form can refer to a schema via `Form::additionalResponse` (no change)
152
-
- Schema cannot refer to anything beside itself, i.e. inheriting or `oneOf` etc.
149
+
### Elementss
153
150
154
151
#### Security
155
152
156
-
Same as now
157
-
158
-
#### Connection
159
-
160
-
| Vocabulary Term | Description | Assignment | Type | Remarks |
| base | The base URI that is used for building an absolute URI together with relative URIs in forms | optional | String of URI | None |
163
-
| security | String pointing to the `securityDefinitions` map or Object with type `Security`| optional | Array with items pointing to the `securityDefinitions` map or Object with type `Security`| When the security definition moves to the bindings, these terms can be moved a layer up to `connection`|
153
+
Does not exist in the Thing-level anymore. It exists within `Form` and is the same as a `SecurityDefinition` from TD 1.1
164
154
165
155
#### Form
166
156
167
-
| Vocabulary Term | Description | Assignment | Type | Remarks |
| op | Indicates the semantic intention of performing the operation(s) described by the form. | with default | String or Array of Strings (no change) ||
170
-
| contentType | Assign a content type based on a media type (e.g., `text/plain`) and potential parameters (e.g., `charset=utf-8`) for the media type | with default | String (no change) ||
171
-
| base | The base URI that is used for building an absolute URI together with relative URIs in forms | optional | String of URI | None |
172
-
| security | String pointing to the `securityDefinitions` map or Object with type `Security`| optional | Array with items pointing to the `securityDefinitions` map or Object with type `Security`| When the security definition moves to the bindings, these terms can be moved a layer up to `connection`|
157
+
| Vocabulary Term | Description | Assignment | Type | Remarks |
| op | Indicates the semantic intention of performing the operation(s) described by the form. | with default | String or Array of Strings | (no change) |
160
+
| contentType | Assign a content type based on a media type (e.g., `text/plain`) and potential parameters (e.g., `charset=utf-8`) for the media type | with default | String | (no change) |
161
+
| base | The base URI that is used for building an absolute URI together with relative URIs in forms | optional | String of URI | Cannot be used in the Form-level, only usable in a Form Definition |
162
+
| security | Security applied on the operations of the `Form`| mandatory | Object with type `Security`||
163
+
| form | A form definition from the `formDefinitions` to be used for a specific form in the Form-level | optional | String | Cannot be used in a form definition, only usable in the Form-level |
164
+
165
+
Note: The terms `base` and `form` can be only used in specific levels. Please see the Remarks column.
173
166
174
167
#### Schema
175
168
176
169
Same as now
177
170
178
171
## Guidelines
179
172
180
-
Best practices for designing TDs. When to use this or not.
173
+
Best practices for designing TDs. When to use this common definitions mechanism or not.
181
174
182
175
1. If you have one mechanism just inline it, i.e. do not use `-Definitions` objects.
183
176
2. In case of multiple defaults, as default definitions are applied to all forms, any local form overwriting it can result in multiple forms with the same information. See https://github.com/w3c/wot-thing-description/pull/2163#issuecomment-3562576204
184
177
3. A TD is not required to use the common definitions. If you do not have common patterns in your TD, where most of the forms don't have duplicate terms, do not try to use this feature. It will make it more complicated for the Consumers to process.
178
+
4. You do not need to use `"form"` in the Form-level if that form already uses the defaults. That is provided as a way to override defaults.
185
179
186
180
- No resolution: Having no security field at all (none in the forms, none in the top level) -> reverting to defaults
187
-
- No resolution: Security defaults:
188
-
- McCool auto -> Assuming nosec is wrong assumption
189
181
190
182
## Validation Rules
191
183
@@ -196,9 +188,10 @@ Best practices for designing TDs. When to use this or not.
196
188
3.`"formDefaults"`
197
189
4.`"formDefinitions"`
198
190
3. In an expanded TD, the following terms MUST NOT be used in the form level:
199
-
1.`"schema"`: TODO:
191
+
1.`"schema"`: TODO: How to remove?
200
192
2.`"formDefaults"`
201
-
4. When a field — such as or `"formDefaults"` — references a definition, that definition MUST exist in the root level in the respective category; e.g., all values of `"formDefaults"` (when not an object) must be in the `"formDefaults"` in the root level.
193
+
3.`"form"`
194
+
4. When a field — such as or `"formDefaults"` — references a definition, that definition MUST exist in the root level in the respective category; e.g., all values of `"formDefaults"` (when not an object) must be in the `"formDefinitions"` in the root level.
0 commit comments