# OCSF: Open Cybersecurity Schema Framework Explained

> Learn what OCSF is, how the Open Cybersecurity Schema Framework works, its taxonomy, event classes, data types, benefits, use cases, and OCSF vs ECS.

- Canonical URL: https://www.puppygraph.com/blog/ocsf
- Published: 2026-09-25
- Author: Hao Wu

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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

## What is OCSF (Open Cybersecurity Schema Framework)?

The [Open Cybersecurity Schema Framework](https://ocsf.io/) 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](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html) 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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

## 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](https://aws.amazon.com/blogs/security/aws-co-announces-release-of-the-open-cybersecurity-schema-framework-ocsf-project/) with other security and technology companies. The project built on [Symantec's ICD schema work](https://www.splunk.com/en_us/newsroom/press-releases/2022/cybersecurity-and-technology-industry-leaders-launch-open-source-project-to-help-organizations-detect-and-stop-cyberattacks-faster-and-more-effectively.html). 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](https://www.linuxfoundation.org/press/open-cybersecurity-schema-framework-ocsf-joins-the-linux-foundation-to-optimize-critical-security-data), 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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

## 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](https://www.elastic.co/docs/reference/ecs) 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.

| Dimension | OCSF | ECS |
| --- | --- | --- |
| Organizing Model | Event classes with defined attributes and reusable objects | Common fields organized into field sets |
| Event Classification | Category, class, activity, and derived type identifiers | `event.kind`, `event.category`, `event.type`, and `event.outcome` |
| Storage Relationship | Schema is independent of a storage engine | Field definitions specify Elasticsearch data types |
| Additional Context | Profiles and extensions augment the schema | Custom fields, with [naming guidance to avoid conflicts](https://www.elastic.co/docs/reference/ecs/ecs-custom-fields-in-ecs) |
| Main Adoption Question | Can producers and consumers agree on classes, mappings, and versions? | Can integrations and analytics use the expected ECS fields and meanings? |

ECS's [categorization fields](https://www.elastic.co/docs/reference/ecs/ecs-category-field-values-reference) 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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

## 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](https://schema.ocsf.io/1.3.0/classes/authentication), selected fields would be:

| Field | Value | Meaning in This Example |
| --- | --- | --- |
| `category_uid` | `3` | Identity & Access Management |
| `class_uid` | `3002` | Authentication |
| `activity_id` | `1` | Logon |
| `type_uid` | `300201` | Authentication: Logon |
| `status_id` | `2` | Failure |

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](https://github.com/ocsf/ocsf-docs/blob/main/faqs/schema-faq.md) 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.

![](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-b28983deeb95436403010d7ed3f680ed8d0261bb93da2374eb448c5819129474.webp)

Figure: OCSF supplies the shared definitions; the surrounding systems perform normalization and analysis. Keeping activity separate from outcome lets a failed logon retain both meanings.

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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

## 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](https://schema.ocsf.io/) 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](https://github.com/ocsf/ocsf-docs/blob/main/faqs/schema-faq.md#when-should-i-use-a-finding-event-class) 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](https://github.com/ocsf/ocsf-docs/blob/main/overview/understanding-ocsf.md) 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](https://github.com/ocsf/ocsf-schema/blob/1.3.0/dictionary.json) 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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

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](https://github.com/ocsf/ocsf-docs/blob/main/overview/understanding-ocsf.md#enum-attributes), `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](https://schema.ocsf.io/1.3.0/objects/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](https://github.com/ocsf/ocsf-docs/blob/main/articles/profiles-are-powerful.md) 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](https://github.com/ocsf/ocsf-schema/blob/main/extensions.md) 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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

## 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](https://github.com/ocsf/ocsf-docs/blob/main/articles/defining-and-using-observables.md), 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](https://www.puppygraph.com/blog/security-data-lake-vs-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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

## 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](https://www.rfc-editor.org/rfc/rfc7618.html) or [reassigned](https://www.rfc-editor.org/rfc/rfc2131.html#section-2.2). 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](https://github.com/ocsf/ocsf-docs/blob/main/faqs/schema-faq.md#how-is-backwards-compatibility-managed), 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](https://github.com/ocsf/ocsf-docs/blob/main/articles/OCSF-Storage-Strategies.md) 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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

## 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](https://github.com/ocsf/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](https://github.com/ocsf/ocsf-server) 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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

**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](https://docs.aws.amazon.com/security-lake/latest/userguide/custom-sources.html) 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.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

### **Investigate OCSF security data with PuppyGraph**

The [PuppyGraph OCSF demo](https://github.com/puppygraph/puppygraph-getting-started/tree/main/use-case-demos/ocsf-schema-demo) connects security events and asset inventories in PostgreSQL through a graph model. It uses simplified, OCSF-inspired relational tables to demonstrate relationship analysis, with no separate graph database to populate.

#### **1\. Start the demo**

Clone the repository, open the `use-case-demos/ocsf-schema-demo` directory, and run:

```shell
docker compose up -d
```

Docker Compose starts PostgreSQL and PuppyGraph. The database initialization script creates the source tables and loads the supplied CSV files, including users, devices, network flows, and resource access events.

#### **2\. Build the graph with PuppyGraph AI**

Open PuppyGraph at `localhost:8081` and sign in with username `puppygraph` and password `puppygraph123`. On **Catalogs**, click **\+ Add Catalog**, select **PostgreSQL**, and enter:

| Field | Value |
| --- | --- |
| Catalog Name | `ocsf_sql` |
| JDBC Connection String | `jdbc:postgresql://ocsf_db:5432/ocsf_demo` |
| Username | `admin` |
| Password | `password` |

Configure PuppyGraph AI with a supported model endpoint and API key. Open **Chat** from the left navigation and leave **Auto-confirm** off.

For this walkthrough, we ask PuppyGraph AI to build a subset of the demo’s graph schema, focusing on users, devices, resources, and their relationships. To use the complete graph model, upload the `schema.json` file included in the [demo repository](https://github.com/puppygraph/puppygraph-getting-started/tree/main/use-case-demos/ocsf-schema-demo).

Enter the following prompt:

```
Build a security investigation graph from the public schema in
the ocsf_sql catalog.

Create User, Device, and Resource nodes from users, devices,
and resources, using user_id, device_id, and resource_id as IDs.

Create these directed edges:
- Authenticated: User → Device, from authentication_events
  using user_id and device_id.
- NetworkFlow: Device → Device, from network_flows
  using src_device_id and dst_device_id.
- AccessedResource: Device → Resource, from resource_access_events
  using device_id and resource_id.

Preserve each event row as a separate edge. Keep timestamps as
temporal properties named timestamp, and expose resource
criticality as Resource.criticality.

Inspect sample rows, test the joins, and propose the mappings
for my review.
```

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

Review the proposed identifiers, edge directions, and property mappings, then approve the changes. Ask the assistant to verify that each applied node and edge label returns data.

![](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-87ca03c411cbf5197133136c0d0f8ac0abc15ab8ab027f95517c2da56c20cd88.webp)

Figure: PuppyGraph AI turns connected security tables into a graph schema through reviewed node and edge mappings.

The resulting graph connects users to devices, devices to other devices, and devices to resources. PuppyGraph queries the underlying PostgreSQL tables directly.

#### **3\. Trace potential lateral movement**

Open **Query**, select **Cypher**, and run:

```
MATCH path =
  (source:Device)-[flow:NetworkFlow]->
  (destination:Device)-[access:AccessedResource]->
  (resource:Resource)
WHERE resource.criticality IN ['critical', 'high']
  AND source <> destination
  AND flow.timestamp < access.timestamp
RETURN path
LIMIT 20
```

The query finds network communication between devices followed by the receiving device accessing a high-value resource. The timestamp condition preserves that sequence, helping analysts identify paths for further investigation.

![](https://o6xswp5m6ilbks2z.public.blob.vercel-storage.com/blog-bdfdb9da4282e4bf542f26d0a953c1ec923d5d0e21babf09e22403d45cbdcaac.webp)

Figure: Network flows and subsequent resource access appear together as paths for investigating potential lateral movement.

These paths identify related activity that warrants review; they do not alone establish compromise. The repository also includes queries for suspicious tool execution and successful privilege escalation, using the same graph model.

[Get Started with PuppyGraph for FREE](https://www.puppygraph.com/download-confirmation)

## 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](https://www.puppygraph.com/download-confirmation) and [book a demo](https://www.puppygraph.com/book-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.