Surface YamlNode.Start / YamlNode.End to OpenApi elements

[dferretti]

Hello! I've got a feature request here - can we read the YamlNode.Start and End properties and somehow attach them to the OpenApi elements that are created when reading from a YamlDocument?
I know you can sometimes read locations/pointers from errors that are thrown during parsing, but this would be useful for other scenarios where the YAML is syntactically valid but an application might want to notify the user of non-syntax info at a particular location.

I can take a stab at it if you think it would be worthwhile.

[dferretti]

I have read elsewhere in this repo that SharpYaml is an implementation detail and shouldn't be exposed in the public API if avoidable. The Mark struct that YamlNode.Start and End are is just 3 int properties. We could just create a new struct with similar properties to expose instead.

[darrelmiller]

Can you show an example of a document that would take advantage of this feature? It's not clear to me what is being proposed here.

[dferretti]

Sure - my use case is a C# Source Generator I am working on. I read in an openapi spec and generate models based on the schemas found in the spec, with System.ComponentModel.DataAnnotations attributes and all that. So I am traversing the OpenApiDocument looking at all of the OpenApiSchema instances. The spec itself might be totally valid from OpenApi's standpoint, but if for example my generator doesn't yet support the MinProperties on a a given OpenApiSchema schema, I'd like to be able to raise a warning saying

Constraint 'MinProperties' is not yet supported, found on line {schema.Start.Line}

or something along those lines.

[dferretti]

And I should add, I am hoping to include line numbers instead of just found at schema #/components/... because Source Generators can include Location information with line numbers, and VS will show these line numbers in the error list, and enable clicking the error to jump straight to the position in the file.

[darrelmiller]

Ahh, understood. Thanks for the clarification. We have had a similar request for this before. I am open to suggestions on how to enable this.

[dferretti]

One tricky part I am not sure what to do about: how to handle documents that are dynamically created / added to. My first thought would be to attach some line position info and a way to conditionally read it from the OpenApiSchema / OpenApiProperty / etc (maybe go as far as attaching this to the IOpenApiAny?). We could have our own LineInfo struct to mimic the SharpYaml.Mark struct, and then something like one of:

• a nullable Start / End line info struct
• mimic Newtonsoft's IJsonLineInfo and expose a HasLineInfo or similar
• expose a bool TryGetLineInfo(out LineInfo start, out LineInfo end)

Any of those could work and indicate to the caller that the info might not be present - I imagine we would only have this info on hand if the OpenApiDocument originated from one of the Readers that collected these line info data along the way.

But then what happens if I have read in a document, along with gathered line info, and then start calling AddOperation for example? At that point we don't have a way (as far as I can tell) to determine line info of new members, and existing members may have shuffled around. I can't think of a good way of invalidating the line info on the other pieces of the document. The Newtonsoft example I believe works well for them because it is used with the JsonReader explicitly, but here the OpenApiDocument can be used for reading or writing. Maybe it could just be a documentation thing? "Once a document has been modified all LineInfo values should be ignored".

[dferretti]

My use case is just for reading a static yaml document, so I don't plan on needing to figure out line numbers for dynamic documents - just thinking out loud.

[darrelmiller]

I took a look at this and I don't see an easy way to transfer the lineInfo information over to all the model objects. Currently when we parse the objects we don't have any assumption that they all derive from a base class. Therefore I think we would need to add the code to every deserializer.
I think there is some cleaning up I can do for the deserialization code that I will tackle when I implement the 3.1 parser. Maybe when doing that work a clean solution will reveal itself.

[darrelmiller]

We should investigate if this kind of error reporting is possible when moving to System.Text.Json #841

[darrelmiller]

Unfortunately System.Text.Json does not expose publicly the line numbers for us to access. There is an open issue here related to it dotnet/runtime#28482