OCSF: Open Cybersecurity Schema Framework Explained

A failed login should retain the same meaning as it moves from an identity provider to a security data lake and into an investigation. That requires agreement on more than a field called user. Analysts also need to know which account was targeted, what action occurred, whether it succeeded, and when it happened. OCSF gives producers and consumers a shared model for expressing those facts.

This article explains that model, how its taxonomy and data types fit together, and where normalization helps security operations. It also compares OCSF with Elastic Common Schema (ECS) and describes an implementation approach that tests both structural correctness and investigative usefulness.

What is OCSF (Open Cybersecurity Schema Framework)?

The Open Cybersecurity Schema Framework is an open-source framework for defining schemas, accompanied by a vendor-neutral schema for cybersecurity data. It provides common definitions for events, their attributes, and the entities involved. A producer can emit events in OCSF directly, or a data pipeline can translate an existing source format into it.

For a security engineer, the useful result is a predictable representation of an event. An authentication record has a defined place for the account being authenticated, the activity, and the outcome. A network record has a different structure suited to communication between endpoints. Consumers can interpret those structures without learning every producer's original vocabulary.

OCSF defines the data model independently of storage and transport. Its schema definitions use JSON, but adopting the schema does not require storing every event as a JSON document. Collection, transformation, storage, detection, and response remain responsibilities of the surrounding systems. This separation lets the same schema support different deployment architectures.

Amazon Security Lake illustrates the distinction. It normalizes supported AWS sources to OCSF and stores data in Apache Parquet in Amazon S3. Those collection and storage choices belong to Security Lake. Another implementation can use OCSF with a different pipeline or destination.

The practical question when evaluating OCSF support is therefore which event classes, attributes, and schema versions a producer emits and a consumer understands. A shared label alone says little about whether the information needed for a particular investigation survives the integration.

Why was OCSF created?

OCSF emerged from a recurring integration problem: security products describe related activity using different schemas. Each consumer then needs source-specific knowledge to interpret incoming records. Adding a source can mean updating parsers, field mappings, queries, dashboards, and detection content across several destinations.

AWS and Splunk announced OCSF in August 2022 with other security and technology companies. The project built on Symantec's ICD schema work. Its objective was to give the industry a common way to represent security events, reducing repeated normalization work. OCSF later joined the Linux Foundation in November 2024, continuing its existing open development model.

Consider an organization replacing its identity provider while keeping its detection platform. If detections depend directly on the old provider's event names and field layout, the replacement changes the detection interface. Mapping both providers into a shared authentication model gives the team a more stable interface to test against.

The work moves toward maintaining source-to-schema mappings and clear consumer expectations. That still requires engineering, especially when the new source reports different evidence. The architectural benefit is that understanding a source can become reusable work, instead of being rediscovered independently in every downstream integration.

What problems does OCSF solve?

Inconsistent event meaning. Field names alone are insufficient for normalization. A source's action might describe an attempted operation, while another source uses it for a security control's response. Mapping those values into the same destination column can create plausible but misleading queries. OCSF gives mappers defined event classes and attribute meanings against which to make that decision.

Repeated integration work. A shared destination schema lets multiple consumers reuse normalized data. A team can maintain source-specific transformations at an agreed pipeline boundary, then build searches against the resulting model. Whether that reduces work depends on the quality and coverage of those transformations; incomplete mappings simply move the uncertainty downstream.

Difficult cross-source analysis. Consistent representations make it easier to compare authentication outcomes, search network endpoints, or examine findings from different producers. They also make gaps visible. If a source cannot identify the account behind an activity, analysts can treat that absence explicitly instead of mistaking an unrelated field for equivalent evidence.

These normalization problems also shape the choice between OCSF and Elastic Common Schema (ECS). Both address normalization through an open specification. Elastic Common Schema defines common fields and Elasticsearch data types for event data, including logs and metrics. OCSF organizes its security schema around event classes and reusable objects, independently of a particular storage implementation. The useful comparison is how each model fits the systems that produce and consume your data.

ECS's categorization fields provide source-independent event classification. Detection portability depends on query languages, available evidence, and execution behavior as well as a shared schema. Teams with established ECS integrations should weigh that investment against the specific interoperability they expect OCSF to provide. Choose the schema boundary around concrete consumer requirements and include any necessary translation in the integration plan.

How does OCSF work?

An OCSF pipeline interprets a source event, assigns an appropriate event class, and populates that class's attributes. It then checks the output against the chosen schema and delivers it to consumers. A product emitting OCSF natively performs the modeling at the source; a mapper performs it for a product that emits another format.

Imagine a source record describing a failed attempt to sign in to a VPN service. The mapper first establishes that the event describes authentication. It then distinguishes the requested activity from its outcome. In the Authentication event class, selected fields would be:

The type identifier follows class_uid * 100 + activity_id. A successful logon has the same type identifier, with a different status. A query for failed logons therefore needs the outcome as well as the event type. Failure also does not, by itself, establish that the event is a high-severity security incident.

This table shows selected fields, not a complete event. The mapper must also populate required attributes, identify the subject of the authentication, and retain useful source context. Validation should use the chosen class and any applied profiles, including their nested object requirements.

The OCSF schema FAQ distinguishes source-specific fields retained in unmapped from raw text preserved in raw_data. These provide ways to keep evidence that has not been normalized. Fields needed routinely by shared analytics deserve a proper mapping or documented extension; placing them in unmapped leaves consumers dependent on source-specific interpretation.

The result is useful when consumers can trust both the shape and the interpretation of the data. A record can pass structural checks while still assigning an account or timestamp to the wrong role.

What are the core components of OCSF?

OCSF combines a taxonomy for classifying events with reusable definitions for their contents. These components answer different questions: what happened, which entities were involved, how values are represented, and what additional context applies.

Categories and event classes. Categories group related classes into domains such as System Activity, Network Activity, Findings, and Identity & Access Management. Classes describe more specific records, such as Process Activity, DNS Activity, Vulnerability Finding, and Authentication. The schema browser exposes this hierarchy. Choose a class based on the event's meaning, rather than assigning every record from a product to one class. A single security product can report several kinds of activity.

The distinction between activity and findings also matters. An activity record describes an observed operation. A finding represents an assessment or insight, potentially derived from other evidence. The schema's guidance on findings explains why an alert is not automatically a finding. Preserving that distinction helps consumers separate observations from the conclusions a tool drew about them.

Attributes, objects, and the dictionary. Attributes describe individual pieces of information. Objects group related attributes into reusable structures, such as a user, device, process, or network endpoint. The attribute dictionary supplies common definitions; a class gives those attributes their event-specific context. The framework overview explains how classes assemble these building blocks. Reusing an object makes its structure familiar, but its position still matters: an initiating actor and a target account have different roles.

Data types and enumerations. OCSF uses primitive types such as strings, integers, and booleans, plus specialized types with defined representations. Its data type definitions include ip_t for IP addresses and timestamp_t for milliseconds since the Unix epoch. Objects can be nested, and attributes can contain arrays. Enumerations provide defined values for fields such as activity and status. Mappers must translate source values into those meanings, rather than copying numbers that happen to fit the destination type.

A timestamp illustrates the difference between type checking and semantic checking. Epoch seconds and epoch milliseconds can both arrive as integers. A pipeline must understand the source unit before writing the normalized value; accepting an integer is insufficient to establish a correct timeline.

The distinction between enumeration values also carries meaning. Under OCSF's enumeration conventions, Unknown represents an unknown value, while Other accommodates a source value without a matching standard option. For Other, the corresponding string field carries the custom label. A mapper should preserve this distinction: missing outcome evidence is different from a known source outcome that the schema's standard choices do not describe.

Requirements and metadata. Class and object definitions mark attributes as required, recommended, or optional and can impose additional constraints. Required fields establish minimum structural expectations; recommended fields often carry context needed for practical analysis. Metadata identifies the reporting product and the OCSF schema version, with fields for additional provenance. This lets consumers interpret an event against a known schema instead of assuming every record follows the newest release.

An event instance identifier serves a separate purpose from a class or type identifier. For example, metadata.uid can identify a particular event assigned an ID by the logging system. Many distinct logon events share the same type_uid; that value cannot serve as a deduplication key.

Profiles and extensions. Profiles add a related set of attributes to applicable classes or objects. For example, the Host profile can add device and actor context to network activity. Extensions provide a way to define additional schema elements without changing the core. The extensions registry helps avoid collisions in extension names and UIDs. Use these mechanisms deliberately: shared structure remains useful only when consumers understand the additions they depend on.

Benefits of OCSF

OCSF's value becomes concrete when a team can use the same normalized evidence in several workflows. The benefits depend on preserving the attributes those workflows require.

Detection engineering. A failed-authentication analytic can operate on a common activity and outcome representation across mapped sources. Source onboarding then includes testing whether the existing analytic sees the expected events. This gives engineers a stable place to express detection intent, while retaining source-specific conditions where the evidence differs. It also makes a parser change testable against the detections it could affect.

Threat hunting and incident investigation. An analyst can search for an account, inspect its authentication activity, and compare relevant network or endpoint evidence without relearning each source's field vocabulary. OCSF also defines observables, which surface selected values and their locations in an event through a common structure. When producers populate them, they can simplify searches for an IP address or file hash across classes. A matching observable is evidence to investigate, not proof that two events share a cause.

Security data lake reuse. A normalized dataset can support multiple analytical consumers, provided each understands its schema and storage interface. This is useful when a team wants investigation access beyond the data selected for immediate detection. The distinction between a security data lake and a SIEM is relevant here: the lake can hold reusable evidence while the SIEM supplies detection content and operational workflows.

Reporting and evidence review. Consistent event categories, outcomes, and provenance make repeated questions easier to define. A team investigating changes to privileged access can document which normalized events support its report and which sources are absent. OCSF supplies a common representation for that evidence; retention, completeness, access control, and the interpretation of a particular audit requirement remain separate responsibilities.

Across these use cases, the gain is reduced dependence on source-specific interpretation during analysis. The strongest implementation measure is whether a real detection, hunt, or report becomes easier to maintain while preserving its evidence.

Challenges of OCSF

Mapping requires domain judgment. A parser can extract a field correctly and still map it incorrectly. An account named in a message may be the actor, the target, or an owner referenced for context. Likewise, an address may belong to the client, a proxy, or the destination. Test mappings with representative events and their source documentation. A validator cannot reconstruct meaning that the mapper misunderstood.

Shared fields do not resolve identities. Two events containing alex do not establish that they refer to the same account. Usernames may be scoped to a tenant or directory, and IP addresses may be shared or reassigned. For cross-source analysis, define identity keys with the necessary scope and preserve evidence about how records were linked. Uncertain matches should remain distinguishable from authoritative identifiers.

Extensions can weaken interoperability. Additional fields preserve valuable context, but they create consumer dependencies. If the facts needed by a detection exist only in a private extension or an opaque payload, another tool needs additional knowledge to use them. Review frequently queried additions for reuse, document their semantics, and avoid changing the meaning of a core field to accommodate one source.

Schema evolution and physical storage need coordination. Producers, validators, and consumers may support different OCSF releases. Even an additive change can require adjustments to a destination table or a strict consumer. OCSF follows semantic versioning, but versioning alone does not coordinate your deployment. Maintain an explicit compatibility plan and test changes against existing analytics.

Storage design remains an implementation decision. OCSF's storage strategies guide discusses organizing tables by source, category, or class, among other approaches. A class-oriented layout can simplify focused searches while increasing the number of tables involved in broader investigations. Nested structures and arrays also need appropriate support in the chosen query engine.

These challenges make ownership essential. Someone must maintain mappings, someone must define what consumers require, and someone must investigate quality regressions. Adopting a schema gives those teams a common reference for their work.

How to implement OCSF

Start with a limited set of sources and a question whose answer you can verify. Expanding a tested implementation is easier than discovering that a large normalized dataset omitted the fields its first detection needs.

1. Define the analytical requirement. Choose a bounded workflow, such as investigating repeated failed sign-ins followed by a successful sign-in for the same account. Identify the necessary event outcomes, identity scope, timestamps, and source coverage. Collect representative input events, including failures, missing values, and unusual authentication paths. Write down what the expected output should mean before selecting transformation tools.

2. Specify the mapping contract. Select the OCSF version, event classes, and applicable profiles supported by the destination. For each source field, record the destination attribute, transformation, missing-value behavior, and reason for the mapping. Preserve the distinction between event time and processing time. Document how identities are scoped and how useful source information is retained when no core attribute fits. The project's translation examples can inform this work, but verify their assumptions against your actual source.

3. Validate structure and meaning. Use the OCSF schema server's validation capabilities against the selected schema, including nested objects and applied profiles. Keep mapping fixtures in version control and rerun them when parsers or schemas change. Add semantic checks beyond schema validation: a failed sign-in remains a failure, the target account stays in the intended role, and the normalized timestamp matches the input instant. Route rejected records to a monitored location where engineers can inspect and replay them.

Then run the intended analytic over known test events. Check both expected matches and events that should remain unrelated, such as the same username in different tenants. This tests the full path from source evidence to analytical result.

4. Design delivery and storage together. Confirm the destination's requirements for schema versions, file formats, partitioning, and access. For example, Security Lake custom sources must supply OCSF-normalized data in Parquet and meet its ingestion requirements. That differs from Security Lake's automatic normalization of supported AWS sources. Plan raw-event retention and replay alongside normalized storage so a corrected mapping can be applied to earlier evidence where needed.

5. Operate the mappings as maintained software. Track validation failures, missing analytical fields, unmatched identities, and changes in event volumes by source and class. A rising share of unknown outcomes deserves investigation even if every record remains structurally valid. Assign owners to source mappings and consumer requirements. Before an upgrade, compare old and new outputs using representative events and check the detections, reports, and investigations that rely on them.

Once normalization is reliable, some investigations need a model of relationships across events and inventories. For example, an analyst may want to follow an account through authenticated sessions to accessed resources, retaining the timestamps and source events that support each connection. That requires explicit identity and relationship definitions on top of the normalized records.

With OCSF-normalized data represented in supported warehouse or lakehouse tables, PuppyGraph lets you define a graph schema over those tables and query it with openCypher and Gremlin. Its graph model maps source data to nodes, edges, and properties, giving analysts an entity-and-relationship vocabulary for those investigations. The default direct-query path keeps data in the underlying store and requires no persistent duplicate graph dataset.

The integration is through the supported storage layer and the graph schema you define. Source normalization, identity resolution, and any necessary preparation of table columns still belong in the data implementation. This separates two useful responsibilities: OCSF standardizes event representations, and the graph model expresses the relationships an investigation needs to traverse.

Conclusion

OCSF provides a shared structure and vocabulary for security data. Its taxonomy, event classes, reusable objects, and extension mechanisms let teams normalize diverse sources without tying that model to one storage engine. The practical benefits depend on mapping quality, evidence preservation, and consumer compatibility.

Start with an investigation you can test. Verify that normalized records retain the identities, actions, outcomes, and times needed to answer it, then expand source coverage and analytical uses.

Try the forever-free PuppyGraph Developer Edition and book a demo with the team to see how openCypher and Gremlin queries connect identities and events across warehouse and lakehouse tables, with no graph-specific ETL, for investigations over OCSF-normalized security data.