Conceptual Guide — Overview¶

The OGC SWE Common Data Model 3.0 is organized into ten packages, each building on the ones before it. This guide explains each package from the perspective of a developer integrating these schemas into an application.

Package map¶

graph TD
    P1["Pkg 1
Basic Types"]
    P2["Pkg 2
Abstract Components"]
    P3["Pkg 3
Scalar Components"]
    P4["Pkg 4
Range Components"]
    P5["Pkg 5
Polymorphic Unions"]
    P6["Pkg 6
Records & Vectors"]
    P7["Pkg 7
Choice Components"]
    P8["Pkg 8
Arrays & Streams"]
    P9["Pkg 9
Geometry"]
    P10["Pkg 10
Encodings"]

    P1 --> P2
    P2 --> P3
    P2 --> P4
    P3 --> P5
    P4 --> P5
    P5 --> P6
    P5 --> P7
    P5 --> P8
    P1 --> P9
    P2 --> P9
    P1 --> P10
    P9 --> P5
    P10 --> P8

How the packages compose¶

Packages 1–2 lay the foundation: value types (UnitReference, NumberOrSpecial, nil values, constraints) and the abstract base types that every component inherits from.

Packages 3–4 define the leaf-level data components — scalar values like Quantity, Time, and Category, plus their range counterparts (QuantityRange, TimeRange, etc.).

Package 5 introduces the polymorphic unions (AnyComponent, AnyScalarComponent, etc.) that let composite types hold any component without knowing its concrete type at compile time.

Packages 6–8 build composite structures on top of those unions: DataRecord (named fields), Vector (coordinates), DataChoice (discriminated alternatives), DataArray / Matrix (homogeneous collections), and DataStream (observation streams).

Package 9 (new in 3.0) adds geometry support via GeoJSON-compatible types.

Package 10 defines how values are serialized on the wire — text (CSV), JSON, XML, or binary encoding descriptors.

File layout across formats¶

Each format splits the packages across the same set of files:

File	Packages	Contents
`basic_types.*`	1 & 2	Value types, abstract bases
`scalar_components.*`	3 & 4	Scalar and range components
`sweCommon3.*`	5–8	Unions, records, arrays, streams
`geometry.*`	9	Geometry types
`encodings.*`	10	Encoding descriptors

Packages 5–8 must live in the same file because AnyComponent, DataRecord, DataArray, and the other composite types form a mutually referential cycle that none of the three IDLs can split across files.

Next steps¶

Dive into each package: