Implement Metaschema

[alanisaac]

Related Issue:

#735

Description of changes:

This PR is an implementation of "metaschemas", or JSON schemas that describe OCSF's schema. I started with the "object" and "event" schemas.

[alanisaac]

A couple notes from the discussion today:

• This would be the first time a language is introduced to the Schema repo other than JSON. Could potentially split up the JSON metaschemas and the Python tests?
• Possibility of incorporating validation into GitHub action checks?

[alanisaac]

To demonstrate another usage of metaschemas, I added IDE integration with Visual Studio Code, a popular code editor. Now, when you open an object or event with that IDE, it provides both autocomplete, validation, and tooltips with documentation. Examples:

Autocompleting:

For property names:

For enums:

Validation

Regex pattern matching that the name is valid:

Validating the data type of uid:

Validating that the constraint is a valid option:

Documentation

All properties get tooltips with the description of the field. I took descriptions from the examples:

[alanisaac]

A few observations from playing with additional constraints on metaschemas:

• I tried being more strict that enums must match a regex for numeric names. But there is a single exception in http_request.json here: https://github.com/ocsf/ocsf-schema/blob/main/objects/http_request.json#L16. They appear to be the only enum values in the schemas that are not numbers. Is there a reason why?
• I tried being more strict with properties of attributes. That indicated that there are a few more I could still add like sibling and type. But I did notice a few that might have been issues:
  • user.json has a name property on one attribute, but I see you already logged that as an issue! Cleanup user object  #754
  • analytic.json has a description: property on one attribute (with an extra colon). See https://github.com/ocsf/ocsf-schema/blob/main/objects/analytic.json#L19. EDIT: this is being fixed in minor fix for related_analytics JSON #761
  • metadata.json's version attribute is the only one with a default value on the attribute itself. See https://github.com/ocsf/ocsf-schema/blob/main/objects/metadata.json#L46. I do see others in the dictionary though. I tried looking for where it might be rendered on https://schema.ocsf.io/ and didn't see anything so I wasn't sure if it was in active use or not.

[alanisaac]

@rroupski --

• I think I've addressed all your review comments. Where should this go from here?
• And -- any comment on the remaining unaddressed bullets above? I'm especially curious if this one represents a bug in the schema or not:

I tried being more strict that enums must match a regex for numeric names. But there is a single exception in http_request.json here: https://github.com/ocsf/ocsf-schema/blob/main/objects/http_request.json#L16. They appear to be the only enum values in the schemas that are not numbers. Is there a reason why?

[rroupski]

I tried being more strict that enums must match a regex for numeric names. But there is a single exception in http_request.json here: https://github.com/ocsf/ocsf-schema/blob/main/objects/http_request.json#L16. They appear to be the only enum values in the schemas that are not numbers. Is there a reason why?

There are other “exceptions”, for example, the depth enum attribute in the cvss object.

The reason is that the enumerated values are defined in some other standard or document. The OCSF schema uses those external values in the enum to define the expected set of correct values for the attribute.

[rroupski]

• metadata.json's version attribute is the only one with a default value on the attribute itself. See https://github.com/ocsf/ocsf-schema/blob/main/objects/metadata.json#L46. I do see others in the dictionary though. I tried looking for where it might be rendered on https://schema.ocsf.io/ and didn't see anything so I wasn't sure if it was in active use or not.

The default value in the metadata.version is probably a mistake, so I'll fix it. However, some attributes defined in the dictionary.json use default values.

[rroupski]

@alanisaac I'll talk to @pagbabian-splunk to find a home for this tool.

It looks like there are 2 features defined in this PR:

1. Python OCSF schema validation tool
2. Visual Studio Code integration to provide autocomplete, validation, and tooltips with documentation.

Correct?

[alanisaac]

There are other “exceptions”, for example, the depth enum attribute in the cvss object.

The reason is that the enumerated values are defined in some other standard or document. The OCSF schema uses those external values in the enum to define the expected set of correct values for the attribute.

Ah I missed these. Thanks for the clarification!

It looks like there are 2 features defined in this PR:

1. Python OCSF schema validation tool
2. Visual Studio Code integration to provide autocomplete, validation, and tooltips with documentation.

That's correct. I know there was some discussion about 1. living in a different repository. Either way, I think there would be value in adding it to this repository's checks via GitHub Actions in order to enforce some of the validation that the schema can provide. Ensuring the tests pass also makes sure that the metaschema itself is always correct.

[alanisaac]

As discussed in meetings and Slack, I have updated this PR to only include the metaschemas themselves in a /metaschema folder. They are not exhaustive yet, if this pattern looks good, I will add the rest in a follow-on PR.

[dkolbly]

Moving the ball forward 🚀

[taddhar]

Some comments and questions here as per our call tonight.

In general I like the idea of a metaschema especially if it helps providing self documentation.

I have a question out of curiosity. We had the discussion on whether some attributes should be passed with a length or size limit. Would you be able to cover this aspect with this proposal?

[alanisaac]

I have a question out of curiosity. We had the discussion on whether some attributes should be passed with a length or size limit. Would you be able to cover this aspect with this proposal?

Something to clarify here is that there are two main concepts in OCSF: the schema definition files and the schemas. The files in this repository are the schema definition files, and the documents you can retrieve from the OCSF server, such as this one are the OCSF schemas.

So when we're talking about length or size limits for fields, it could mean:

1. We enforce length limits for attribute names. That is, the name of new attributes like activity_name, activity_id that you can see here cannot be longer than X characters.
2. We enforce that certain attributes cannot have values longer than a length limit. That is, the value assigned to activity_name, for example, cannot be longer than X characters.

I believe your question is referring to 2., but I wanted to call out both for clarity.

In order to enforce max lengths for attribute values, we'd want to add a feature to the schema definition files that can specify it. Metaschemas could absolutely allow and enforce that this hypothetical "max length" or "max size" field is used properly, but I think introducing this as a concept would likely best be served as a part of a separate issue. There's a similar issue asking about array size constraints here: #779

[floydtree]

Looks good to move ahead!

[mikeradka]

LGTM. Looking forward to getting the ball rolling on metaschema. Thanks Alan and Jeremy.

[alanisaac]

@dkolbly @floydtree @mikeradka -- I see this is approved, though I cannot merge it on my own. Any final checks to do here?

[mikeradka]

@dkolbly @floydtree @mikeradka -- I see this is approved, though I cannot merge it on my own. Any final checks to do here?

Thanks for reaching out, I just ran one last few bit of checks on the server side to be safe. I think we are good to go!