Documentation of YAML Format and Schema

[aj-stein-nist]

Hello. Long-time listener, first-time caller. I was reviewing the metrics published in this repository and had some questions about the schema or maybe more generally data format and expected values and value types (string, integer, a string with a special keyword).

Is there any place this is documented? I pulled down a clone of the repo and I had struggled to find something quickly. Some examples by way of questions from my review:

• Many metrics have defined a samplingPeriod: P30D. I reviewed the HTML generation system and it seems that it should be an ISO8601 duration and Ruby libraries are used to convert that into human-readable temporal durations, but it is ISO8601 and it must be that if I were to edit the metrics?
• sloRangeMin: 80% requires a percentage (as a string) and cannot be expressed as a decimal value sloRangeMin: 0.80? Are both supported?
• relatedControlIds: ["Missing"] (sorry for converting it inline here for simpler list writing in the issue) means it is an array but it cannot be assigned empty as in relatedControlIds: [] like other YAML-based formats? Is there any requirements on the control IDs referenced or is that up to interpretation to keep things flexible?

Thanks in advance for your publication of this data and, if you have the time to do so, for reviewing my issue full of questions.

[rajkrishnamurthy]

To @aj-stein-nist's point above; @pritikin: Can we make the relatedControlIds: [] optional. The string "Missing" is misleading.

[aj-stein-nist]

@rajkrishnamurthy, FYI, there are a few YAML syntax errors and other data irregularities at current main/master commit. Should I open another issue around that for you?

[rajkrishnamurthy]

Hi @aj-stein-nist: Please do. I'm seeing the same thing. Fixing them up and will send it to @pritikin and @mosi-k-platt for review.

[apannetrat]

The more formal specification of the YAML format is here:
https://github.com/cloudsecurityalliance/continuous-audit-metrics/wiki/Metrics-catalog-YAML-format

It's not entirely complete, but it's a good starting point.

[aj-stein-nist]

The more formal specification of the YAML format is here: https://github.com/cloudsecurityalliance/continuous-audit-metrics/wiki/Metrics-catalog-YAML-format

It's not entirely complete, but it's a good starting point.

Would a proper JSON Schema matching or clarifying these requirements be helpful? For schema validation for CI/CD, it could be. We make use of that in our work, beyond just checking "hey is this YAML syntactically correct?"

If you want to chat about this next week, let me know.