Split Schema Implementation to Input and Output Schemas

[ccoffin]

The data submitted by CNAs has different fields than what is required for a valid CVE Record. CVE Services populates some fields (e.g., providerMetadata/orgId, see issue #312 ) during the submission process regardless of what the CNA provides in their submission.

A different (output) schema is needed when viewing/consuming CVE Records to ensure that all required data is present as intended. CVE consumers want to know that the data is there (see #334 and CVEProject/cvelistV5#66).

This could result in a CNA (input) schema and a CVE (output) schema.

[darakian]

To capture it from the QWG today. The desired behavior could be achieved by tagging a single schema appropriately such that input and output validation files/tool/whatevs can be mechanically derived from it.

graph TD;
    schema-->input_validation;
    schema-->output_validation;

Loading

[alilleybrinker]

First blush, I like this as it could in theory give CVE more flexibility in evolving the schema where it may be reasonable to make modifications to the output schema used by CVE consumers in ways that don't break CNAs or ADPs, or to modify the schema used for CNAs or ADPs in a way that doesn't break consumers. It also means CNAs and ADPs would only be responsible for providing the portion of the format which they actually know / care about.

[jayjacobs]

What about having a third schema for a "development" branch that applies on CVE submission? In other words, an upcoming schema that contains either deprecated sections or upcoming breaking changes. And it would probably need to be paired with someway to engage the CNA with any warnings or upcoming breaking changes that will affect their upcoming submissions.

e.g. "you submitted this with semver, did you know there is a new semver change", or "you submitted a datetime without a timezone, this will break in April"

[darakian]

What about having a third schema for a "development" branch that applies on CVE submission? ...

That could be very nice for tool developers. I'm unfamiliar with how the git branches and releases are managed and doing a quick look it seems like there isn't a development/staging/next/whatever branch in place today. Maybe that's the main branch though 🤔

Either way, as I read it I could see CVE services either having a endpoint that a record could be sent to to test against future changes or add validation against the next schema version on the current endpoint(s) and return the validation results as non-blocking errors.

[ElectricNroff]

I feel that having two CVE Record schemas is not the right solution. We should instead document that the CNA container schema (which is relevant for submission by CNAs) is not supposed to be the same as the CNA container portion of a CVE Record (in particular, providerMetadata should not be submitted). This can be emphasized through different learning pathways for data producers versus data consumers (e.g., different mindmap presentations, emphasizing the CNA container schema when onboarding CNAs, etc.).

An output schema is viable today, because every data element that is added by the CVE Services server (e.g., datePublished) exists in every CVE Record. However, in the future, there may be data elements that are missing in older records and cannot be reconstructed (a simple, but not very realistic, example is a data field expressing the number of milliseconds of CPU time spent on accepting container submissions). More generally, we can describe the server's output format with assertions such as "this data element is guaranteed to be in the CVE Record if it is found in the server's database, and is always there for new CVE Records." This is semantically different from saying that the cpuMilliseconds field is either required or optional within an "output schema."

[darakian]

I feel that having two CVE Record schemas is not the right solution.

So, as I recall the idea was less to have two independent schemas and rather to have one schema which could be "rendered" for lack of a better term into two machine consumable specs/validations/doohickeys to aid automation. The idea arose from the observation that what is required of a CVE publisher is not the same as what a reader of a record may expect. A simple example is the publication timestamp which the publisher does not define (cve services does). Not sure if that changes your perspective or not, but wanted to make sure that context was clear.

[ElectricNroff]

I understand all of the differences between data submission and data retrieval. I feel that establishing a container schema that the CVE Services server must use, when accepting data submission from a CNA, is outside the purview of the QWG. The requirement is that the CVE Services server store valid CVE Records (with the data that the CNA sent) and not accept containers that would lead to invalid records. Everything else is an implementation detail on the server side. For example, it might sometimes be helpful to use an equivalent schema that leads to more helpful error messages (from specific validation software) for invalid data. Other times, parts of a schema may be theoretically correct but not practically usable within specific validation software (e.g., because real-world arithmetic isn't infinitely precise, as in the CVEProject/cve-services#1204 issue). Again, an equivalent schema would need to be used unless it were more effective to replace the validation software.

Of course, ideally there would be a schema that happens to work perfectly across any current validation software and all future updates - so that nobody would ever need to bother with those equivalences.

[darakian]

I feel that establishing a container schema that the CVE Services server must use, when accepting data submission from a CNA, is outside the purview of the QWG.

What about establishing a container schema that the CVE Services server may use?

[jayjacobs]

I feel that having two CVE Record schemas is not the right solution.

We already have 2+ schemas, it's just not publicized. Right now, when a CNA or ADP submits their container, CVE Services uses an unpublicized schema to validate the submission. I believe this issue is more about making the differences explicit, public and documented.

Making it clear that CNAs will have their own schema should reduce extra work and confusion. The fields populated by CVE Services do not even need to appear in the CNA/ADP schemas (but should be required in the output schemas). This should remove questions and confusion that we have today, where, for exampel, vulnogram will submit a default (bogus) orgId in the providerMetadata column (I assume because it's listed as required in the one and only public schema).