From dba5778ec950be373dea3123e219976e868af34d Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 31 Aug 2017 12:33:54 -0700 Subject: [PATCH] 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 27a05de3 (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 27a05de3 with a bump in b92cf90a (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]: https://github.com/opencontainers/image-spec/pull/164 [2]: https://github.com/opencontainers/runtime-spec/pull/510#r69845853 [3]: https://github.com/opencontainers/runtime-spec/pull/510#r69846114 [4]: https://github.com/opencontainers/runtime-spec/pull/811#discussion_r116294608 [5]: https://github.com/opencontainers/runtime-spec/pull/811#discussion_r116465503 [6]: https://github.com/opencontainers/runtime-spec/pull/510#r69846021 Signed-off-by: W. Trevor King --- config.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.md b/config.md index 1f57970cf..8f66fd231 100644 --- a/config.md +++ b/config.md @@ -441,7 +441,7 @@ Cleanup or debugging functions are examples of such a hook. Keys MUST NOT be an empty string. Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`. Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by subsequent specifications. - Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown annotation key. + Runtimes MUST handle unknown annotation keys like any other [unknown property](#extensibility). Values MUST be strings. Values MAY be an empty string. @@ -454,12 +454,12 @@ Cleanup or debugging functions are examples of such a hook. ## Extensibility -Runtimes that are reading or processing this configuration file MUST NOT generate an error if they encounter an unknown property. -Instead they MUST ignore unknown properties. +Runtimes MAY [log](runtime.md#warnings) unknown properties but MUST otherwise ignore them. +That includes not [generating errors](runtime.md#errors) if they encounter an unknown property. ## Valid values -Runtimes that are reading or processing this configuration file MUST generate an error when invalid or unsupported values are encountered. +Runtimes MUST generate an error when invalid or unsupported values are encountered. Unless support for a valid value is explicitly required, runtimes MAY choose which subset of the valid values it will support. ## Configuration Schema Example