Skip to content

Commit dba5778

Browse files
committed
config: Collapse extensibility to a single MUST
Generating an error seems like one potential violation of the requirement to ignore unknown properties. Compliance testing for the ignore requirement can cite the MUST I've written here for any noticeable runtime activity around the unknown property without needing a error-specific MUST. We've had the two MUSTs since 27a05de (Add text about extensions, 2016-06-26, #510), citing [1]. I'd asked for consolidated phrasing then [2,3], but hadn't followed up after the commit landed. I've left a line mentioning the error activity as non-normative clarification, but am also happy to drop that line completely. Also: * Update the unknown annotation entry to reference the generic extensibility section, because there's nothing annotation-specific in how we want runtimes to handle unknown keys. * Remove "reading or processing" language. This initially landed in 27a05de with a bump in b92cf90 (consistency and style fix, 2017-05-12, #811). Some thought was put into this phrasing there [4,5] and earlier in #510 [6], but we never got around to dropping this qualifier. However, the purpose of this qualifier is unclear to me. What is the point of compliance requirements for runtimes which don't read or process a configuration? [1]: opencontainers/image-spec#164 [2]: #510 (comment) [3]: #510 (comment) [4]: #811 (comment) [5]: #811 (comment) [6]: #510 (comment) Signed-off-by: W. Trevor King <[email protected]>
1 parent f5f1390 commit dba5778

File tree

1 file changed

+4
-4
lines changed

1 file changed

+4
-4
lines changed

config.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -441,7 +441,7 @@ Cleanup or debugging functions are examples of such a hook.
441441
Keys MUST NOT be an empty string.
442442
Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
443443
Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by subsequent specifications.
444-
Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown annotation key.
444+
Runtimes MUST handle unknown annotation keys like any other [unknown property](#extensibility).
445445

446446
Values MUST be strings.
447447
Values MAY be an empty string.
@@ -454,12 +454,12 @@ Cleanup or debugging functions are examples of such a hook.
454454

455455
## <a name="configExtensibility" />Extensibility
456456

457-
Runtimes that are reading or processing this configuration file MUST NOT generate an error if they encounter an unknown property.
458-
Instead they MUST ignore unknown properties.
457+
Runtimes MAY [log](runtime.md#warnings) unknown properties but MUST otherwise ignore them.
458+
That includes not [generating errors](runtime.md#errors) if they encounter an unknown property.
459459

460460
## Valid values
461461

462-
Runtimes that are reading or processing this configuration file MUST generate an error when invalid or unsupported values are encountered.
462+
Runtimes MUST generate an error when invalid or unsupported values are encountered.
463463
Unless support for a valid value is explicitly required, runtimes MAY choose which subset of the valid values it will support.
464464

465465
## Configuration Schema Example

0 commit comments

Comments
 (0)