OCSF Schema: A Metaschema for Security Logging That Compiles, Not Just Documents
Hook
Every security team has written parsers for forty vendor log formats that all claim to log 'network connections' but can't agree on what fields that means. OCSF's answer: treat the schema itself as code.
Context
Security logging has a vocabulary problem masquerading as a format problem. When your SIEM ingests logs from firewalls, endpoints, cloud providers, and applications, you're not just parsing different formats (JSON vs. CEF vs. syslog)—you're reconciling fundamentally different ontologies. One vendor's 'src_ip' is another's 'source.address', and a third's 'network.client.ip'. The semantic chaos means security teams spend more time writing normalization rules than writing detections.
Historical attempts at standardization like Common Event Format (CEF) or Log Event Extended Format (LEEF) provided structure but not semantics. They're serialization formats with informal field guidelines documented in PDFs, not machine-readable schemas with validation rules. When CEF adds a field or changes semantics, there's no automated way to check if your parser still works—you find out in production when detections break. OCSF (Open Cybersecurity Schema Framework) takes a different approach: it's not a log format but a schema compiler. The ocsf-schema repository contains JSON files that define event classes, objects, and attributes as a declarative specification, validated by a metaschema, and compiled into whatever backend format you need. It's treating security event taxonomy like an API specification with versioning, compatibility checking, and formal extension points.
Technical Insight
The architectural insight is separation of concerns across three layers: the metaschema (schema-of-schemas), the core schema definitions, and extensions. The metaschema/ directory defines the rules that all OCSF schemas must follow—it's JSON Schema files that validate whether your event class definitions are structurally valid. This means you can CI-test schema changes automatically, catching breaking changes before they ship.
Event classes in events/ are organized by category (network, system, identity) and define the shape of specific security events. Here's a simplified example of how a network activity event is structured:
{
"caption": "Network Activity",
"name": "network_activity",
"uid": 4001,
"extends": "base_event",
"category": "network",
"attributes": {
"src_endpoint": {
"requirement": "required",
"description": "Source endpoint details"
},
"dst_endpoint": {
"requirement": "required",
"description": "Destination endpoint details"
},
"connection_info": {
"requirement": "optional"
}
}
}
Crucially, attributes like src_endpoint aren't defined inline—they're references to the central dictionary.json, which serves as the canonical registry. This prevents synonym proliferation: src_endpoint has one definition with specific semantics (an object containing IP, port, hostname), and every event class that uses it gets the same semantics. When you need the source IP across fifty event types, you query the same attribute path.
The extension mechanism solves the 'everyone needs custom fields' problem without forking. Extensions like extensions/linux/ or extensions/windows/ can augment core event classes with platform-specific attributes:
{
"name": "linux_extension",
"extends_classes": {
"process": {
"attributes": {
"linux_namespace": {
"type": "string_t",
"description": "Linux namespace identifier"
}
}
}
}
}
This extends the process class without modifying core definitions. A tool that understands the Linux extension gets the extra fields; one that doesn't still parses baseline OCSF correctly. It's composition, not inheritance—vendors ship their extensions as separate schemas that layer onto the core.
Profiles add another dimension by defining subsets of the schema for specific use cases. A cloud_profile.json might include only network and identity events, excluding endpoint-specific classes. Tools declare conformance to a profile rather than the entire spec, which is realistic: nobody implements all 100+ event classes. This formalization prevents the informal subsetting that fragments standards—'we support OCSF' now has a machine-checkable meaning.
The compilation story is where this becomes practical. The schema definitions themselves are consumed by ocsf-schema-compiler, which generates outputs like JSON Schema validators, Parquet table schemas, or language-specific type definitions. You're not parsing OCSF JSON at runtime; you're compiling the schema into whatever backend your pipeline uses. A data lake might compile to Parquet schemas for columnar storage, while an application might generate Go structs. The OCSF JSON is the intermediate representation, not the wire format.
The CI pipeline in .github/workflows/ validates every schema change against the metaschema and runs compatibility checks against the last stable release. This prevents accidental breaking changes—if you rename a required attribute or change its type, the CI fails. There's even an experimental step using Claude API to review changelog descriptions and flag unclear documentation, though that's more novelty than governance today.
Gotcha
The major limitation is that this repository provides no executable code—it's purely schema definitions. If you want to emit OCSF events from your application or parse them into your SIEM, you need to either find a library for your language or build your own compiler integration. The ecosystem is nascent: there's ocsf-schema-compiler for generating schemas and a Python library ocsf-lib for programmatic access, but coverage is spotty. You can't npm install an OCSF logger for Node.js or pip install an OCSF validator—you're writing that integration yourself or waiting for the ecosystem to mature.
Extension conflicts are undefined behavior. If two vendors ship extensions that both add a threat_score attribute to the same class with different types, OCSF has no resolution mechanism. The schema doesn't specify precedence rules or namespacing for conflicting extensions. In practice, this means 'OCSF-compliant' events from different vendors might be incompatible if they use overlapping extensions, fragmenting the ecosystem into dialects. The profile system also lacks composition primitives—you can't express 'profile A plus these three extra classes' or 'profile B minus authentication events' without forking the profile and maintaining your own. Real deployments need fine-grained schema customization, but OCSF gives you coarse-grained include/exclude.
Verdict
Use if: You're building security infrastructure (SIEM, data lake, log aggregator) and need a normalization layer above vendor formats; you're tired of maintaining fifty bespoke parsers and want a standard target; you're willing to invest in compiler integration and contribute to ecosystem tooling; you're betting on vendor adoption reaching critical mass in the next 2-3 years. The metaschema validation and extension model are genuine engineering improvements over CEF or Syslog, and if AWS/Microsoft/CrowdStrike emit OCSF natively, early adopters win. Skip if: You need a production-ready logging library today; you're an application developer wanting to emit structured security logs (use Elastic Common Schema instead, it has actual libraries); you're in a pure Elastic/Splunk environment where native formats already work; you're unwilling to bet on a standard before vendor adoption proves out. This is a specification for tool builders, not a drop-in solution for practitioners—expect a multi-year maturity curve.