Add ability to parse Schema files according to OTEP 0152

[tigrannajaryan]

The parser and parsed representation (AST) are placed in a separate
Go module so that they are can be consumed independently without
the need to bring the rest of the SDK.

Ability to use the parsed representation for schema conversions
can be added later.

[tigrannajaryan]

@MrAlias @Aneurysm9 can you please have a look and tell me if this goes in the right direction?

[codecov]

Codecov Report

Merging #2267 (b25aa10) into main (478dc4f) will increase coverage by 0.0%.
The diff coverage is 93.3%.

@@          Coverage Diff          @@
##            main   #2267   +/-   ##
=====================================
  Coverage   72.6%   72.6%           
=====================================
  Files        170     171    +1     
  Lines      11873   11918   +45     
=====================================
+ Hits        8621    8660   +39     
- Misses      3019    3023    +4     
- Partials     233     235    +2     

Impacted Files	Coverage Δ
schema/v1.0/parser.go	93.3% <93.3%> (ø)
...s/otlp/otlptrace/internal/connection/connection.go	14.6% <0.0%> (-1.6%)	⬇️

[jmacd]

Looks good to me.

[MrAlias]

Overall, I think this looks good. Making this it's own module sounds like a good idea and I like the clear layout of code.

How do plan to handle version increments? I see the tests fail for v2.* and v1.1.*, but not v1.0.1. I'm guessing for the patch version we expect to be compatible, I can see a v2 living in it's own package, but I'm wondering what the plan is for v1.1.* and the like.

[tigrannajaryan]

How do plan to handle version increments? I see the tests fail for v2.* and v1.1.*, but not v1.0.1. I'm guessing for the patch version we expect to be compatible, I can see a v2 living in it's own package, but I'm wondering what the plan is for v1.1.* and the like.

Yes, v2 should live in its own package and patch numbers are ignored since they are compatible.

For minor number I think we can force the user to declare the maximum they expect. It is currently implied to be equal to 0, but we can make the Parse function accept maximum minor version number it expects, e.g.:

func Parse(schemaFile string, maxMinorVerNum int) (*ast.Schema, error) {
}

// in checkFileFormatField compare minor number with maxMinorVerNum.

Usage looks a bit ugly, not sure if we can make it nicer:

const maxMinorVer = 2;
ts, err := schema.Parse("myschema.yaml", maxMinorVer) // maximum version number we can handle is 1.2.x. 

Maybe we can change a bit with how we supply the max minor number to make the usage more natural. I can play with some possible approaches to see what I can come up with, but the idea is going to be the same: force the user to declare what maximum version they expect.

[tigrannajaryan]

I thought a bit more and I think we should just make all major and all minor versions separate packages. The initial version will be schema/v1.0, the next minor version will go in schema/v1.1, etc. This is similar to how we handle semconv packages and forces the user to explicitly choose the version they expect.

Using schema/v1.2 means that you are ok to see files in format 1.0, 1.1, 1.2, but not anything newer than 1.2.x (so range [1.0-1.3) is what you expect).

New versions of file format are going to be rare (maybe 1-2 minor versions per year, ever less major versions) so we are not going to have a proliferation of packages.
Let me refactor to show what it would look like.

[tigrannajaryan]

@MrAlias Refactored. PTAL.

[tigrannajaryan]

If we are happy with this direction, I will tidy up the draft for full review.

[tigrannajaryan]

Squashed and ready for review.

[Aneurysm9]

Please add the new module to versions.yaml. This should probably go in a new module set, perhaps experimental-schema, starting at v0.0.1.

[tigrannajaryan]

Please add the new module to versions.yaml. This should probably go in a new module set, perhaps experimental-schema, starting at v0.0.1.

Done.

[MrAlias]

Looks good overall 👍, nothing blocking.

[tigrannajaryan]

@Aneurysm9 do you want to have another look or we can merge?

[tigrannajaryan]

@open-telemetry/go-approvers is there anything else to do on this?

[MrAlias]

@open-telemetry/go-approvers is there anything else to do on this?

Looks good. Going to merge.