Skip to content

Commit

Permalink
spec: Define the property-specification syntax
Browse files Browse the repository at this point in the history
And add platform annotations.

By formally defining our syntax, we do a better job of making that
syntax enforcable.  We can also make platform-scoping very obvious,
and no longer need to rely on "For Linux-based systems the process
supports..." guards.

The only intentional semantic change is that we now allow,
platform-named properties that don't match platform.os.  For example:

  {
    "platform": {
      "os": "linux",
      ...
    },
    "windows": {
      ...
    }
  }

and even:

  {
    "platform": {
      "os": "linux",
      ...
    },
    "windows": "foo",
  }

are both legal now.  This rolls back the "MUST NOT be set otherwise"
requirement which had landed in 718f9f3 (minor narrative cleanup
regarding config compatibility, 2017-01-30, opencontainers#673) to make those
properties consistent with our general:

  Implementations that are reading/processing this configuration file
  MUST NOT generate an error if they encounter an unknown property.

and:

  The state MAY include additional properties.

extensibility policies.  The alternative would be cross-platform
specification of those properties which then forbid the properties on
non-matching platforms, but then the cross-platform definition would
not match the platform-specific Go type.  For example:

  Linux *Linux `json:"linux,omitempty" platform:"linux"`

Blocking the non-matching-platform properties didn't seem to be worth
the potential confusion of the Go platform tag not matching the
Markdown platforms tag.

The ABNF highlighting comes from [1,2].

[1]: https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting
[2]: https://github.com/github/linguist/blob/v5.0.8/lib/linguist/languages.yml#L50-L56

Signed-off-by: W. Trevor King <wking@tremily.us>
  • Loading branch information
wking committed Apr 25, 2017
1 parent 4754b55 commit 05da00b
Show file tree
Hide file tree
Showing 5 changed files with 143 additions and 117 deletions.
Loading

0 comments on commit 05da00b

Please sign in to comment.