MicroProfile OpenAPI 3.1

[Emily-Jiang]

Description of the high level feature, including any external spec links:

Implement MicroProfile OpenAPI 3.1:
One of the important issues is about the Integration with Bean Validation.

---

Documents

When available, add links to required feature documents. Use "N/A" to mark particular documents which are not required by the feature.

• UFO: https://ibm.box.com/s/hmosaao2284obeiqzhctruq4aer3362o
• FTS: MP OpenAPI 3.1 Feature Test Summary #21001
• Beta Blog: BETA BLOG - MicroProfile OpenAPI 3.1 #21769
• GA Blog: GA BLOG - MicroProfile OpenAPI 3.1 #24583

---

Process Overview

• Prioritization
• Design
• Implementation
• Legal and Translation
• Beta
• GA
  • Focal Point Approvals
• Other Deliverables

General Instructions

The process steps occur roughly in the order as presented. Process steps occasionally overlap.

Each process step has a number of tasks which must be completed or must be marked as not applicable ("N/A").

Unless otherwise indicated, the tasks are the responsibility of the Feature Owner or a Delegate of the Feature Owner.

If you need assistance, reach out to the OpenLiberty/release-architect.

Important: Labels are used to trigger particular steps and must be added as indicated.

---

Prioritization (Complete Before Development Starts)

The (OpenLiberty/chief-architect) and area leads are responsible for prioritizing the features and determining which features are being actively worked on.

Prioritization

• Feature added to the "New" column of the Open Liberty project board
  • Epics can be added to the board in one of two ways:
    • From this issue, use the "Projects" section to select the appropriate project board.
    • From the appropriate project board click "Add card" and select your Feature Epic issue
• Priority assigned
  • Attend the Liberty Backlog Prioritization meeting

---

Design (Complete Before Development Starts)

Design preliminaries determine whether a formal design, which will be provided by an Upcoming Feature Overview (UFO) document, must be created and reviewed. A formal design is required if the feature requires any of the following: UI, Serviceability, SVT, Performance testing, or non-trivial documentation/ID.

Design Preliminaries

• UI requirements identified. (Owner and UI focal point)
• ID requirements identified. (Owner and ID focal point)
  • Refer to Documenting Open Liberty.
  • Feature Owner adds label ID Required, if non-trivial documentation needs to be created by the ID team.
  • ID adds label ID Required - Trivial, if no design will be performed and only trivial ID updates are needed.
• Serviceability Requirements Identified. (Owner and Serviceability focal point)
• SVT Requirements Identified. (Owner and SVT focal point)
• Performance testing requirements identified. (Owner and Performance focal point)

Design

• POC Design / UFO review requested.
  • Owner adds label Design Review Request
• POC Design / UFO review scheduled.
  • Follow the instructions in POC-Forum repo
• POC Design / UFO review completed.
• POC / UFO Review follow-ons completed.
• POC Design / UFO approval requested.
  • Owner adds label Design Approval Request
• Design / UFO approved. (OpenLiberty/chief-architect) or N/A
  • (OpenLiberty/chief-architect) adds label Design Approved
  • Add the public link to the UFO in Box to the Documents section.
  • The UFO must always accurately reflect the final implementation of the feature. Any changes must be first approved. Afterwards, update the UFO by creating a copy of the original approved slide(s) at the end of the deck and prepend "OLD" to the title(s). A single updated copy of the slide(s) should take the original's place, and have its title(s) prepended with "UPDATED".

FAT Documentation

• "Feature Test Summary" child task created
  • Use the Feature Test Summary Template
  • Add FTS issue link to the Documents section.

---

Implementation

A feature must be prioritized before any implementation work may begin to be delivered (inaccessible/no-ship). However, a design focused approach should still be applied to features, and developers should think about the feature design prior to writing and delivering any code.
Besides being prioritized, a feature must also be socialized (or No Design Approved) before any beta code may be delivered. All new Liberty content must be inaccessible in our GA releases until it is Feature Complete by either marking it kind=noship or beta fencing it.
Code may not GA until this feature has obtained the "Design Approved" or "No Design Approved" label, along with all other tasks outlined in the GA section.

Feature Development Begins

• Add the In Progress label

Legal and Translation

In order to avoid last minute blockers and significant disruptions to the feature, the legal items need to be done as early in the feature process as possible, either in design or as early into the development as possible. Similarly, translation is to be done concurrently with development. Both MUST be completed before Beta or GA is requested.

Legal (Complete before Feature Complete Date)

• Changed or new open source libraries are cleared and approved, or N/A. (Legal Release Services/Cass Tucker/Release PM).
• Licenses and Certificates of Originality (COOs) are updated, or N/A

Translation (Complete 1 week before Feature Complete Date)

• PII updates are merged, or N/A. Note timing with translation shipments.

Innovation (Complete 1 week before Feature Complete Date)

• Consider whether any aspects of the feature may be patentable. If any identified, disclosures have been submitted.

---

Beta

In order to facilitate early feedback from users, all new features and functionality should first be released as part of a beta release.

Beta Code

• Beta fence the functionality
  • kind=beta, ibm:beta, ProductInfo.getBetaEdition()
• Beta development complete and feature ready for inclusion in a beta release
  • Add label target:beta and the appropriate target:YY00X-beta (where YY00X is the targeted beta version).
• Feature delivered into beta
  • (OpenLiberty/release-manager) adds label release:YY00X-beta (where YY00X is the first beta version that included the functionality).

Beta Blog (Complete 1.5 weeks before beta eGA)

• Beta blog issue created and populated using the Open Liberty BETA blog post template.
  • Add a link to the beta blog issue in the Documents section.
  • Note: This is for inclusion into the overall beta release blog post. If, in addition, you'd also like to create a dedicated blog post about your feature, then follow the "Standalone Feature Blog Post" instructions under the Other Deliverables section.

---

GA

A feature is ready to GA after it is Feature Complete and has obtained all necessary Focal Point Approvals.

Feature Complete

• Feature implementation and tests completed.
  • All PRs are merged.
  • All epic and child issues are closed.
  • All stop ship issues are completed.
• Legal: all necessary approvals granted.
• Translation: All messages translated or sent for translation for upcoming release
• GA development complete and feature ready for inclusion in a GA release
  • Add label target:ga and the appropriate target:YY00X (where YY00X is the targeted GA version).
  • Inclusion in a release requires the completion of all Focal Point Approvals.

Focal Point Approvals (Complete by Feature Complete Date)

These occur only after GA of this feature is requested (by adding a target:ga label). GA of this feature may not occur until all approvals are obtained.

All Features

• APIs/Externals Externals have been reviewed or N/A. (OpenLiberty/externals-approvers)
  • Approver adds label focalApproved:externals
• Demo Demo is scheduled for an upcoming EOI or N/A. (OpenLiberty/demo-approvers)
  • Add comment @OpenLiberty/demo-approvers Demo scheduled for EOI [Iteration Number] to this issue.
  • Approver adds label focalApproved:demo.
• FAT All Tests complete and running successfully in SOE or N/A. (OpenLiberty/fat-approvers)
  • Approver adds label focalApproved:fat.
• Globalization Translation and TVT are complete or N/A. (OpenLiberty/globalization-approvers)
  • Approver adds label focalApproved:globalization.

Design Approved Features

• Accessibility Accessibility testing completed or N/A. (OpenLiberty/accessibility-approvers)
  • Approver adds label focalApproved:accessibility.
• ID Documentation is complete or N/A. (OpenLiberty/id-approvers)
  • Approver adds label focalApproved:id.

  • NOTE: If only trivial documentation changes are required, you may reach out to the ID Feature Focal to request a ID Required - Trivial label. Unlike features with regular ID requirement, those with ID Required - Trivial label do not have a hard requirement for a Design/UFO.

• Performance Performance testing is complete or N/A. (OpenLiberty/performance-approvers)
  • Approver adds label focalApproved:performance.
• Serviceability Serviceability has been addressed or N/A. (OpenLiberty/serviceability-approvers)
  • Approver adds label focalApproved:sve.
• STE Skills Transfer Education chart deck is complete or N/A. (OpenLiberty/ste-approvers)
  • Approver adds label focalApproved:ste.
• SVT System Verification Test is complete or N/A. (OpenLiberty/svt-approvers)
  • Approver adds label focalApproved:svt.

Remove Beta Fencing (Complete by Feature Complete Date)

• Beta guards are removed, or N/A
  • Only after all necessary Focal Point Approvals have been granted.

GA Blog (Complete by Feature Complete Date)

• GA Blog issue created and populated using the Open Liberty GA release blog post template.
  • Add a link to the GA Blog issue in the Documents section.
  • Note: This is for inclusion into the overall release blog post. If, in addition, you'd also like to create a dedicated blog post about your feature, then follow the "Standalone Feature Blog Post" instructions under the Other Deliverables section.

Post GA

• Replace target:YY00X label with the appropriate release:YY00X. (OpenLiberty/release-manager)

---

Other Deliverables

• Standalone Feature Blog Post A blog post specifically about your feature or N/A. (OpenLiberty/release-architect)
  • This should be strongly considered for larger or more prominent features.
  • Follow instructions in the blogs repo.
• OL Guides OL Guides assessment is complete or N/A. (OpenLiberty/guide-assessment)
• Dev Experience Developer Experience & Tools work is complete or N/A. (OpenLiberty/dev-experience-assessment)

---

[Azquelt]

Changes for MP OpenAPI 3.1 (from 3.1 Milestone)

• Allow extensions to be added via annotations in more places
• Support additionalProperties in @Schema
• Better support for defining security requirements and security requirement sets with annotations
• Allow @APIResponse on classes
• Recommend a standard location for a UI endpoint if provided
• Enhance generated schema using information from Bean Validation annotations (still in progress)
• Other clarifications and TCK fixes and enhancements

[Azquelt]

@chirp1 I don't think we need any docs changes for this feature. All the changes listed above are minor improvements that I don't think make sense to add to our current documentation.

The only things I can see that would need doing are:

• The config examples on the MP OpenAPI 3.0 feature page should be carried across to the 3.1 page. I'm not sure whether this happens automatically or you would like an issue raised for that.
• The guide should be updated to the latest version
• Documenting the new config property (which would be done under Collate all MP Config properties to understand how/if to document them as reference docs#505)

[Azquelt]

Similarly, I don't expect to need any changes to SVT.

[jhanders34]

Feedback from the UFO socialization:

Slide 17

• Update slide to talk about class and method both having APIResponse and how it works. Clarify method override of the annotation for the same response code. Need to make sure that it is documented in the spec.

Slide 22

• update to say MP OpenAPI annotations instead of just MP OpenAPI.

Slide 27

• Bean validation is not required for MP. Need to validate that TCK can disable Bean Validation tests
• Open doc item documenting which properties are dynamic and which ones are static. Add this property to a table and gradually add more of the MP config properties. (Emily owns this item)

Slide 28

• Is there MP Language server impact?

Slide 32

• Update to say Red Hat for Xlate? Maybe in parentheses

Slide 43

• Add an example to the slide

[scottkurz]

I don't see the UFO link or the recording link?

[Azquelt]

@scottkurz I've added the UFO link, I was sent a recording link but I can't access it. Is that usually added? It wasn't in the template.

[Azquelt]

UFO updates done.

[NottyCode]

@Azquelt I like the way you laid out the as-is/to-be for the use cases. It make it very easy to follow and understand what was being done as a result of each change.

One thing that would help me in future, especially if there is a delay between requesting approval and the socialization, is when commenting that the UFO feedback has been integrated to indicate how each entry in the socialization feedback comment has been addressed.

Some comments on the design before I approve:

Slide 11

• I don't think this makes sense without watching the socialization. I'm not sure how to improve it, but I don't find the way the annotations are expressed is intuitive, your explanation on the call was good, but I'd have liked the slide to reflect that. It wasn't clear to me that the second example was "both of these" and the first was "any of these".
• Was there any discussion about being able to generate this from the JWT spec, or the Jakarta Security annotations? I'm guessing not, but this would have seemed a little obvious as a next step given the bean validation content.

Slide 14

• There is no example of what setting it to True of False should be. I haven't looked at the API in MP OpenAPI but it would suggest the type for additionalProperties would be Object since that seems to be the only way to get True, False or Class into the field, so what happens if someone puts something that isn't True, False or Class in? This would possibly suggest something for slide 28 and 43 beyond what is captured.

Slide 27 comments:

• During the socialization there was a discussion about the MP Config property for bean validation and checkpoint, this was not recorded and no action was taken, but I think the UFO should capture what was said on the call. The socialization call switched to talking about static vs dynamic configuration and the need to document it, but didn't capture the comment about checkpoint. The UFO should talk about this regarding checkpoint.
• From socialization there is a comment about slide 27 regarding the TCK, but there is nothing to indicate that action was taken. Please confirm what the result of that investigation are.
• What is the issue that was raised as a result of the static vs dynamic config discussion?

Slide 28 comment

• I do not think the resolution to slide 28 is sufficient for the feedback on the call. LSP4MP to support latest MicroProfile APIs #14706 does not include details of what changes might be required to the LSP for the API updates and that is what this slide is supposed to do.

Slide 42 comment

• I don't see what the content of this slide has to do with security, in addition the fact that there are changes regarding security in the UFO means I'd expect to see something here. On its own it probably isn't enough for me to not approve the design, but for next time I think there should be more when you have security relevant annotations in the design.

Slide 43 comment

• The point of serviceability slide is to identify common problems that may occur and what we can do to make the customer able to self diagnose. While the common problem is clear, the response is "well they should know" if that is the case then it wouldn't be a serviceability issue so we wouldn't need to call it out.

[Azquelt]

@NottyCode thanks for your feedback. I will be sure to log the changes that were done as a result of the UFO feedback next time.

Slide 11:

• I agree that the information on the side doesn't explain the examples well. I've added two more slides here with background information. (This changes the later slide numbers)
• There wasn't any discussion about using information from MP JWT to generate OpenAPI documentation.
  • My instinct is that we won't be able to get enough information just from scanning the annotations in the code (which is the current approach). I need to have a proper look to see if there's anything else we should do here and would look to raise it as a spec enhancement for the next release of MP OpenAPI if I think there is something we should do there.

Slide 14/16:

• The API provides special classes True.class and False.class to represent the special true and false values so the type of additionalProperties is just Class<?>. I've updated the slide to include this information

Slide 27/29:

• Collate all MP Config properties to understand how/if to document them as reference docs#505 actually already existed and the result of this was the MicroProfile Config properties docs page which lists all of the supported MP Config properties and when they're read by the runtime.
  • The new property was included on this page
• The Spec and TCK was updated to make the Bean Validation parts optional in Limit Bean Validation processing requirement eclipse/microprofile-open-api#541
• The conclusion from the replay was that there wasn't a concern for checkpoint because the property relates to the application, not the runtime environment and it's static and read only at startup. I've added this to the notes for the slide.

Slide 28/30:

• This was at the suggestion of YK as it sounds like they have quite a few MP APIs to add. I've updated the slide to add the information I think will be relevant to LSP4MP and I'll run that past him.

Slide 42/44:

• I agree this slide is overly brief. When analysing a potential security issue, I would be most concerned with where we expose external endpoints and serve requests to users and there are no changes to this part of the feature in this release.
• I hadn't included the @SecurityResourcesSet because it only documents security requirements, it doesn't change anything about the enforcement of any authentication and authorization requirements. I've now added this information to the slide.

Slide 43/45:

• This is a fair comment. I guess I looked at this as a potential problem which could occur but decided no action was needed due to the way the OpenAPI schema corresponds directly to the class, and the class has annotations which directly correspond to the incorrect elements of the schema.
  • I've left these slides in for now since it's a problem we considered even though we decided we didn't need to do anything about it. I'm also happy to remove them.

[Azquelt]

I am still waiting on approvals from:

• @OpenLiberty/globalization-approvers
• @OpenLiberty/performance-approvers
• @OpenLiberty/serviceability-approvers
• @OpenLiberty/ste-approvers (STE has been added to the WAS L3 site)

Can I have these approvals please? If there's any additional information you require please let me know, thank you.

[samwatibm]

Can you clarify when you froze your English PII? 23.0.0.2 translations just came back today and aren't merged yet. If PII was changed after 23.0.0.1 NL freeze of Jan 6, then we need to wait.

[Azquelt]

@samwatibm There have been no message changes for this feature. The only recent change to our nlsprops files was the update to the copyright header when we moved to EPL-2.0.

[donbourne]

Serviceability Approval Comment - Please answer the following questions for serviceability approval:

1. UFO -- does the UFO identify the most likely problems customers will see and identify how the feature will enable them to diagnose and solve those problems without resorting to raising a PMR? Have these issues been addressed in the implementation?

2. Test and Demo -- As part of the serviceability process we're asking feature teams to test and analyze common problem paths for serviceability and demo those problem paths to someone not involved in the development of the feature (eg. L2, test team, or another development team).
   a) What problem paths were tested and demonstrated?
   b) Who did you demo to?
   c) Do the people you demo'd to agree that the serviceability of the demonstrated problem scenarios is sufficient to avoid PMRs for any problems customers are likely to encounter, or that L2 should be able to quickly address those problems without need to engage L3?

3. SVT -- SVT team is often the first team to try new features and often encounters problems setting up and using them. Note that we're not expecting SVT to do full serviceability testing -- just to sign-off on the serviceability of the problem paths they encountered.
   a) Who conducted SVT tests for this feature?
   b) Do they agree that the serviceability of the problems they encountered is sufficient to avoid PMRs, or that L2 should be able to quickly address those problems without need to engage L3?

4. Which L2 / L3 queues will handle PMRs for this feature? Ensure they are present in the contact reference file and in the queue contact summary, and that the respective L2/L3 teams know they are supporting it. Ask Don Bourne if you need links or more info.

5. Does this feature add any new metrics or emit any new JSON events? If yes, have you updated the JMX metrics reference list / Metrics reference list / JSON log events reference list in the Open Liberty docs?

[Azquelt]

@donbourne

1. Yes (slides 45-46). As discussed above, this is behaviour defined in the spec . While I'm not totally happy with it, I think we've addressed it as best we can and I think that users will be able to resolve it without raising a support request.
2. Yes, I demonstrated to @benjamin-confino (L3) and showed adding bean validation annotations and showed the behaviour with and without @Valid. Agreed that the scenario was unlikely to require L3.
3. @hanczaryk you added the svt approval, can you speak to any serviceability issues you encountered?
4. L3 will be handled by WL3CDI
5. No new metrics or JSON events

[hanczaryk]

In regards to serviceability question 3.
a) Brian Hanczaryk conducted SVT tests for this feature.
b) I agree that the serviceability of the problems encountered were sufficient to avoid PMRs and L2 should be able to quickly address any problems without needing to engage L3.

[donbourne]

From serviceability perspective, I'm mostly concerned about the bean validation + open api annotations combining to determine the resultant docs for an endpoint method. I could see that causing some confusion for a while, but I think that's inherent to the changes to the OpenAPI spec (and there isn't much that can helpfully be done in the impl to make that better).

[Azquelt]

@OpenLiberty/demo-approvers Demo scheduled for EOI 23.4

[tevans78]

All done, closing the epic.