Repository navigation
Support in-memory only metadata dictionary in OpenAPI object model #1719
Description
Is your feature request related to a problem? Please describe.
Currently, all properties within the OpenAPI object model are serialized to the output as part of the OpenAPI writer implementation. This makes it difficult to manage temporary state associated with the in-memory OpenAPI model. For example, ASP.NET Core needs to correlate a given OpenApiOperation with a unique identifier for each endpoint recognized by the framework.
Describe the solution you'd like
The OpenAPI object model should support some sort of property bag that allows users to manage metadata associated with an object model in-memory without having to worry about information in this property bag being serialized.
public class OpenApiHasPropertyBag
{
IDictionary<string, object> MetadataCollection { get; }
}
Describe alternatives you've considered
Currently, ASP.NET Core works around this limitation by storing the metadata in the Extensions property on OpenApiSchema and OpenApiOperation then scrubbing this metadata out from the in-memory model before it is serialized. This presents a couple of issues:
- The additional cost of having to scrub out metadata that doesn't need to be serialized
- The additional cost of mapping property bag values to
OpenApiAnyimplementers
Activity
captainsafia commentedon Jul 10, 2024
Vincent Biret (@baywet) Maggie Kimani (@MaggieKimani1) Darrel (@darrelmiller) Any thoughts on the API shape proposed here? I know the library makes extensive use of interfaces for things like this but it strikes me that using a base class would reduce the implementation overhead.
With regard to what classes will extend
OpenApiHasPropertyBag, I'm thinking that we should start with:baywet commentedon Jul 10, 2024
From what I remember from this code base, having a base class would go against the general design.
The extensive use of interfaces for every facet has been the design here.
I wonder if interface default implementations could help us get the best of both here?
From a scenario perspective I'm not sure I understand what you'd expect OAS.net to do with that property bag besides storing it in memory?
captainsafia commentedon Jul 10, 2024
Good idea! An interface with a default property implementation can help fill the gap here. My other conondrum was more bike-sheddy. A lot of the interfaces already defined have end in some sort of
blesuffix (Extensible, Serializable, Referenceable). I couldn't think of a good one for this but I'm open to ideas.Yep, just store it in-memory. It's only there to provide a space for consumers of the object model to do book-keeping on instances within the object model. To elaborate on the ASP.NET Core scenario I described above, we'd use the property pag to store a unique identifier on a given
OpenApiOperationinstance that acts as a join ID with theActionDescriptorconcept in ASP.NET Core so we can link the OpenApiOperation instance with the framework type associated with it.baywet commentedon Jul 11, 2024
Thanks for the additional context!
For the name : IPropertyBagStorable? ugly, but explicit
What would you expect to happen with copy constructors? reference copy or deep copy?
darrelmiller commentedon Feb 19, 2025
Interface IPropertyBag and the property should be called "PropertyBag". Yes it is ugly but we don't have a better suggestion for capturing the fact that these properties are ephemeral.
captainsafia commentedon Feb 19, 2025
Darrel (@darrelmiller) We're unfortunately cornered with all the good names given that
Properties,Annotations,andExtensionsall have special meanings in this space.PropertyBagis good. Some other ideas: