Skip to content

Commit

Permalink
config: Collapse extensibility to a single MUST
Browse files Browse the repository at this point in the history
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, opencontainers#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, opencontainers#811).  Some thought was put into this phrasing there
  [4,5] and earlier in opencontainers#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]: opencontainers#510 (comment)
[3]: opencontainers#510 (comment)
[4]: opencontainers#811 (comment)
[5]: opencontainers#811 (comment)
[6]: opencontainers#510 (comment)

Signed-off-by: W. Trevor King <wking@tremily.us>
  • Loading branch information
wking committed Aug 31, 2017
1 parent f5f1390 commit dba5778
Showing 1 changed file with 4 additions and 4 deletions.
8 changes: 4 additions & 4 deletions config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -454,12 +454,12 @@ Cleanup or debugging functions are examples of such a hook.

## <a name="configExtensibility" />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
Expand Down

0 comments on commit dba5778

Please sign in to comment.