Support in-memory only metadata dictionary in OpenAPI object model

[captainsafia]

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 OpenApiAny implementers

[captainsafia]

@baywet @MaggieKimani1 @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:

• OpenApiDocument
• OpenApIPath
• OpenApiOperation
• OpenApiSchema

[baywet]

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]

I wonder if interface default implementations could help us get the best of both here?

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 ble suffix (Extensible, Serializable, Referenceable). I couldn't think of a good one for this but I'm open to ideas.

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?

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 OpenApiOperation instance that acts as a join ID with the ActionDescriptor concept in ASP.NET Core so we can link the OpenApiOperation instance with the framework type associated with it.

[baywet]

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]

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]

@darrelmiller We're unfortunately cornered with all the good names given that Properties, Annotations, and Extensions all have special meanings in this space. PropertyBag is good. Some other ideas:

• ContextData
• Metadata