Generated .NET Metadata Code Is Not Accurate With Enums

[HoyaBoya]

About

It's a bit odd how the official RESO 1.7 metadata XML gets translated into working code for potential clients. For example, if I use the OData-CLI from Microsoft to generate code against the 1.7 XML example contained in the repo here, I get seemingly invalid enums.

The OData EDMX suggests that an Enum -> Member should have an Integer value.

https://devblogs.microsoft.com/odata/tutorial-sample-use-enumeration-types-in-odata/

The workaround provided in the sample 1.7 XML is to provide an annotation that the value should be a string. For example, for MediaType of Pdf, the value is pdf as it should be here: https://ddwiki.reso.org/display/DDW17/MediaType+Lookups.

That said, the generated client doesn't care about the annotations and simply generates that the underlying value is 7.

Is this correct? Is it even possible to generate a working stub against the RESO metadata? Or will there always be some sort of tinkering by a RESO client?

Expected Behavior

To have Pdf mapped to pdf.

Actual Behavior

Pdf is mapped to 7 for it's order in the enum.

https://gist.github.com/HoyaBoya/eef1fe2d6ccde3d55e68533b0807984c

[darnjo]

Thanks for your post.

It's a bit odd how the official RESO 1.7 metadata XML gets translated into working code for potential clients. For example, if I use the OData-CLI from Microsoft to generate code against the 1.7 XML example contained in the repo here, I get seemingly invalid enums.

One thing to mention is that the metadata samples RESO publishes are meant to be references rather than something you could generate a client with that works for all providers in the industry. One reason for this is that providers are allowed to extend the Data Dictionary specification with their own values, so any client stub generation needs to be against whatever server you're working with. There are also suggested max length, scale, and precision attributes that clients are allowed to differ on.

There are also different representations of enumerations. For single-valued enumerations, they can either be OData EnumTypes or strings. For multiple enumerations they can use OData IsFlags, collections of OData enumerations, or collections of strings.

The OData EDMX suggests that an Enum -> Member should have an Integer value.

In the OData documentation for enumerations, it says the following:

"If the IsFlags attribute has a value of false, either all members MUST specify an integer value for the Value attribute, or all members MUST NOT specify a value for the Value attribute. If no values are specified, the members are assigned consecutive integer values in the order of their appearance, starting with zero for the first member. Client libraries MUST preserve elements in document order."

Integer values are required when IsFlags is true, however the reference metadata doesn't use IsFlags for multiple enumerations and instead uses collections of OData enumerations.

The workaround provided in the sample 1.7 XML is to provide an annotation that the value should be a string. For example, for MediaType of Pdf, the value is pdf as it should be here: https://ddwiki.reso.org/display/DDW17/MediaType+Lookups.

The value provided in the annotation uses a deprecated standard RESO used to use to convey human-friendly strings that violate OData's SimpleIdentifier requirements. RESO has since migrated to using string enumerations in these cases. The annotations were left in place for those who might still be using the old conventions, since they're not disallowed.

That said, the generated client doesn't care about the annotations and simply generates that the underlying value is 7.

Is this correct? Is it even possible to generate a working stub against the RESO metadata? Or will there always be some sort of tinkering by a RESO client?

I haven't tried to use this utility to generate a client myself, but it seems like it's not fully implementing the OData spec given the specification for enumerations above?

RESO uses the Apache Olingo library to validate the XML metadata documents for servers during Certification, so all certified providers should have metadata that you can generate a client with, but there are features in the Web API Core standard that are outside of OData.

For example, the Lookup Resource, which allows providers to use human-friendly string enumerations rather than OData ones due to their inherent limitations. In many cases, providers also have enumeration metadata that is very large and changes often, so changing the advertisement of allowed values to use a separate resource rather than monolithic metadata documents allows clients to pull them incrementally and update diffs by timestamp when they change.

Hope this helps.