-
Notifications
You must be signed in to change notification settings - Fork 176
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Move yaml schema definition to semantic conventions #916
Comments
The ways to achieve it could be: Option 1. Separate vCurrent and vNext schemas
Cons: hard to keep track of difference between vNext schema and what tooling actually supports. Option 2. Keep vCurrent in semconv and vNext in tooling (only weaver)
Cons: schema changes/proposals are less discoverable in the weaver. Option 2.5. Same as p2, but start with a discussion in the semconv
Cons: slightly more difficult process. Might need a formal way to accept schema changes |
Is there an option where:
|
@jsuereth I believe all of the options do this (with a different file, not tag, but the same). I.e. if we got 10 contributions to schema in semconv on top of tag A, but implemented 2 of them in weaver, it'd be a problem when we're going to release tag A + 1 |
What I'm saying is that we can't bump the "allowed version" for YAML internally until weaver has adopted/implemented "vnext" So there would always be a lag between when we release and when you can start moving YAML to the new version |
so we'll have to do soft-backpressure and reject new schema features once we want to bump. What I'm saying that we can apply this soft-backpressure right away and not even merge schema changes until weaver implements them. [Update] I guess we can start without extra process and see how it goes |
In my opinion the main point of the schema file to describe the actual schema of the YAML files that go along with it. I don't see the point of having a
Versioning schema files could mitigate this. Although JSON schema doesn't support versioning out-of-the-box, it would be added like this: {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "YAML schema for semantic convention generator, use for example with VS Code.",
"additionalProperties": false,
"type" : "object",
"required" : ["version"],
"properties" : {
"version" : { "type":"string", "const":"1-1-0" },
...
}
} Given smaller (backward compatible) schema changes, a single version of Weaver could possibly support multiple different versions of the schema. Given bigger changes to the schema that might not be feasible, but given the versioning Weaver could at least immediately know whether the schema version it supports matches the schema version in the semconv repository. A given version of the semantic convention repository would then contain the schema that corresponds to the YAML files in this version. A given version of Weaver would know about the schema version(s) this version of Weaver supports. As related parts are spread out across two repositories this will always cause some coordination effort, overhead, and resulting lag. However, I think there would be a benefit of making dependencies as explicit and clear as possible. |
Yeah - I like this. |
The proposal to have a check of the JSON schema version against the versions supported by Weaver seems good to me. In terms of process, a possible approach could be to generate the JSON schema from the Rust structures representing the semantic conventions, in order to limit discrepancies and ensure that changes are directly integrated into Weaver. Schemars is a Rust library that allows this generation. I have never tested it, but in my opinion, it would be worth trying. |
I'm very much in favor of this move, and I think that validation of the model vs its spec can and should be independent of build-tools or weaver. There are purpose-built tools for this, ajv and a github action using it. How does this change how we can modify the semconv without the tools updating? I think there are two paths to this:
There is a tangential question of whether the weaver data shape should be used to generate the spec. I think this shouldn't be an automatic thing. While the tooling is welcome and can help, especially in the initial pass, if we tie weaver like this, we will have problems where we need a change to weaver to update the semconv, which we need to start using in weaver. If these are truly independent, we can make changes to Weaver and use this to generate, but it's not a prerequisite. |
Description
Schema definition for semconv yaml currently lives in the build tools repo along with the documentation that describes yaml format.
They should be part of semantic conventions and can be shared between different tooling (weaver/build-tools) and easily discoverable by semconv authors.
Additions/removals/changes should be tracked in the semconv repo as they affect all conventions and should be discussed/reviewed by wider community.
Additional context
We'll need to find a good process to update semconv yaml schema: new schema features would still need to be implemented in tooling repos before they can be brought in to semconv.
The text was updated successfully, but these errors were encountered: