README.md

API Expression Working Group

Enable API authors to better serve API consumers, by improving and documenting all aspects of Kubernetes API development. See full Mission Statement.

Stakeholder SIGs

• SIG API Machinery
• SIG Architecture

Meetings

Joining the mailing list for the group will typically add invites for the following meetings to your calendar.

• Regular WG Meeting: Tuesdays at 9:30 PT (Pacific Time) (biweekly). Convert to your timezone.
  • Meeting notes and Agenda.
  • Meeting recordings.

Organizers

• Antoine Pelisse (@apelisse), Google
• Kevin Wiesmueller (@kwiesmueller), Google

Contact

• Slack: #wg-api-expression
• Mailing list
• Open Community Issues/PRs
• Steering Committee Liaison: Jordan Liggitt (@liggitt)

Full Mission Statement

Joint project between SIG API Machinery and SIG Architecture.

Supersedes WG Apply, since it is more general and covers post-GA SSA tasks.

Deliverables:

• Documented, coherent “desired state” for API schema features
  • I.e., what sorts of things may a Kubernetes API schema express? (unions, immutable fields, pluralized fields (?), static field validations, defaults, etc)
  • How should these things be expressed? Both in source form (“types.go”) and in published form (OpenAPI)? What should the canonical API schema expression form be, if not types.go? (if the group recommends a change, the group has to be willing to implement it!)
  • For API specification, do we want to stick with “types.go”, move to a IDL/DSL, or something else?
• Documented, coherent “desired state” for how API authors evolve APIs
  • Covering version-to-version and within-version changes
  • Should cover all kinds of schema changes, not just e.g. adding a field
  • Categorize changes as 100% safe, unsafe-but-needed-anyway (see “ratcheting” below), and unsafe-not-permitted
  • Give guidance both to API authors who a) don’t need to keep old users working and b) need to not break old users.
• Tools for programmatically evaluating the safeness / conformance of an API change that can be run as presubmits. (Should operate on the output of the api definition pipeline, so that they’re language agnostic.)
• Tools & techniques for gradually & safely rolling out marginally unsafe changes to make existing API objects good citizens (called “ratcheting”, usually in the context of validation functions, but API schema changes require the same thought).
• If we need a DSL for API specification, write the tools & code needed.
• Finish SSA and implement missing API constructs (unions etc).
• Updated developer documentation / API guide (i.e., document the current state and not just the desired state)

All artifacts above address both CRs and built-in resources

API Machinery will be the owner of the code produced.

[Original Document].