Skip to content

Documentation updates #18

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.

Sign up for GitHub

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

Merged
rmouritzen-splunk merged 4 commits into from
Jul 8, 2026
Merged

Documentation updates #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
21d239e
Update development status to stable
rmouritzen-splunk Jul 1, 2026
91f73cf
Normalize schema structure before compilation
rmouritzen-splunk Jul 1, 2026
2686d4a
Document compiled schema format
rmouritzen-splunk Jul 1, 2026
4a0e289
Change link to docs/format.md to a full URL
rmouritzen-splunk Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ compiler = SchemaCompiler(Path("path/to/ocsf-schema"))
output = compiler.compile()
```

The returned `compile_version` 1 structure is documented in [Compiled schema format](https://github.com/ocsf/ocsf-schema-compiler/blob/main/docs/format.md).

See [`ocsf_schema_compiler.__main__`](https://github.com/ocsf/ocsf-schema-compiler/blob/main/src/ocsf_schema_compiler/__main__.py) for a working example.

## Developing ocsf-schema-compiler
Expand Down
141 changes: 6 additions & 135 deletions docs/diffs.md → docs/diffs-historical.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,142 +1,13 @@
# Differences between ocsf-server v3 compile and ocsf-schema-compiler
This document covers the differences with the ocsf-server v3 compiler and the ocsf-schema-compiler output. We will refer to the ocsf-server v3 compiler as the "legacy compiler" with its output as the "legacy format", and the ocsf-schema-compiler as the "new compiler" with its output as the "new format".
# Historical differences from the ocsf-server v3 compiler

This historical document records differences encountered while replacing the ocsf-server v3 compiler with the ocsf-schema-compiler. It is retained for migration details, compatibility decisions, and design rationale. The current `compile_version` 1 output is documented in [format.md](format.md).

This document refers to the ocsf-server v3 compiler as the "legacy compiler" and its output as the "legacy format". It refers to the ocsf-schema-compiler as the "new compiler" and its output as the "new format", reflecting the terminology used during the replacement project.

## Legacy exported schema vs new format
The ocsf-server's `/export/schema` format does not return all details, requiring use of various `/api` endpoints to retrieve the entire schema. The new format puts everything together.

The new format has the following:
```json5
{
"categories": {
"caption": "Categories",
"description": "...",
"name": "category",
"attributes": {
// Base schema categories
"<category_name>": {
"caption": "<short name>",
"description": "<description>",
"uid": 1
},
// Categories from extensions always use extension-scoped name
"<ext_name>/<category_name>": {
"caption": "<short name>",
"description": "<description>",
"extension": "<ext_name>",
"extension_id": 1, // extension uid
"uid": 199 // 100 * extension uid + category uid in extension
}
}
},
"dictionary": {
"caption": "Attribute Dictionary",
"description": "...",
"name": "dictionary",
"attributes": {
// Base schema dictionary attributes
"<attribute_name>": {
// attribute properties
},
// Dictionary attributes from extensions always use extension-scoped name
"<ext_name>/<attribute_name>": {
// attribute properties
"extension": "<ext_name>",
"extension_id": 1, // extension uid
}
},
"types": {
"caption": "Data Types",
"description": "...",
"attributes": {
// Base schema dictionary types
"<type_name>": {
// type properties
},
// Platform extensions dictionary types
// and dictionary types from non-platform extensions
// if compiled with --unscoped-dictionary-types enabled (True)
"<attribute_name>": {
// type properties
"extension": "<ext_name>",
"extension_id": 1, // extension uid
},
// Dictionary types from non-platform extensions
// if compiled with --unscoped-dictionary-types enabled (True)
"<ext_name>/<attribute_name>": {
// type properties
"extension": "<ext_name>",
"extension_id": 1, // extension uid
}
}
}
},
"classes": {
// class name is extension scoped when from an extension: "<ext_name>/<class_name>"
"<class_name>": {
"caption": "<short name>",
"category": "<category_name>",
"category_name": "<category_caption>",
"category_uid": 3,
"extension": "<extension_name>", // if class is from extension
"extension_id": 1, // if class is from extension
"description": "...",
"extends": "<base_class_name>", // if applicable
"name": "account_change", // name property is never extension-scoped
"profiles": [
"<profile_name>",
"<ext_name>/<profile_name>", // pextension-scoped when from extension
],
// class uid = 1000 * category uid + class uid
// For extension the category-scoped is used, effectively
// class uid = 1000 * ((100 * extension uid) + category uid) + class uid
// NOTE: The extension variation causes a potential class uid collision
// with classes in the same extension using a mix of base and extension
// categories with the same base category uid, while using the same class
// uid (which are meant to be scoped by category). See below.
"uid": 3001,
// other class properties
"attributes": {
// attribute names are never extension-scoped
"<attribute_name>": {
// attribute properties
}
}
}
},
"objects": {
// object name is extension scoped when from an extension: "<ext_name>/<object_name>"
"<object_name>": {
"caption": "<short name>",
"description": "...",
// other object properties
"attributes": {
// attribute names are never extension-scoped
"<attribute_name>": {
// attribute properties
}
}
}
},
"profiles": {
// profile name is extension scoped when from an extension: "<ext_name>/<profile_name>"
"<profile_name>": {
// profiles properties - does not include attributes
}
},
"extensions": {
"<ext_name>": {
"caption": "<short name>",
"description": "...",
"name": "<ext_name>",
"platform_extension?": false, // or true
"uid": 100,
"version": "<major>.<minor>.<patch>"
}
},
"version": "<major>.<minor>.<patch>",
"compile_version": 1, // currently always 1
}
```
This section focuses on how the current format differs from the legacy compiler output.

For reference, the legacy `/export/schema` API returns the following top-level structure:
```json5
Expand Down
Loading