Opxf 0.3.0

opxf-dotnet

Strongly-typed .NET library for the Open Product Exchange Format (OPXF) — POCOs, System.Text.Json converters, and cross-file conformance validation.

Overview

OPXF is a PIM-agnostic transit format for moving product data from enterprise PIM systems (Akeneo, Inriver, Struct, Pimcore, Bluestone) into downstream consumers (e-commerce platforms, PDF engines, and other channels). This library provides the .NET foundation for working with OPXF payloads.

An OPXF exchange consists of two files:

Installation

dotnet add package OPXF

Targets .NET Standard 2.0, .NET 8, and .NET 9 — so it can be consumed from .NET Framework 4.6.1+, .NET Core 2.0+, and modern .NET alike. On .NET Standard 2.0 it pulls in the System.Text.Json package; .NET 8/9 use the in-box version.

Note (next major rework): .NET Standard 2.0 support currently relies on a small set of internal polyfills in src/OPXF/Compatibility/NetStandardPolyfills.cs — compiler-required types (IsExternalInit, RequiredMemberAttribute, CompilerFeatureRequiredAttribute) for the init/required syntax, plus convenience wrappers (ToHashSet, KeyValuePair.Deconstruct). For the next version, rework the project to drop these wrappers and adjust the code so it compiles natively against .NET Standard 2.0 and the other targets without polyfills (e.g. replace xs.ToHashSet() with new HashSet<>(xs) and deconstructing foreach loops with explicit KeyValuePair access; reconsider the init/required POCO shape if the compiler-attribute polyfills are also to be removed).

Usage

Deserialize

using OPXF;

var model = OpxfSerializer.DeserializeModel(File.ReadAllText("model.json"));
var data  = OpxfSerializer.DeserializeData(File.ReadAllText("data.json"));

Validate

using OPXF.Validation;

var validator = new OPXFValidator();
var result = validator.Validate(model, data);

if (!result.IsValid)
{
    foreach (var error in result.Errors)
        Console.WriteLine(error); // [CONF-02] /data/products/0/productTypeId: unknown productTypeId 'apparel'
}

Serialize

string json = OpxfSerializer.SerializeData(data);

Stream-based I/O

For large payloads, use the stream overloads to avoid loading the full JSON into a string:

await using var modelStream = File.OpenRead("model.json");
await using var dataStream  = File.OpenRead("data.json");

var model = await OpxfSerializer.DeserializeModelAsync(modelStream);
var data  = await OpxfSerializer.DeserializeDataAsync(dataStream);

await using var outStream = File.Create("data.out.json");
await OpxfSerializer.SerializeDataAsync(data, outStream);

Work with attribute values

using OPXF.Data;
using OPXF.Model;

foreach (var product in data.Data.Products)
{
    foreach (var (attrId, entry) in product.Attributes ?? [])
    {
        // Value shape depends on the model's localizable flag:
        //   localizable: false → string | double | bool | string[] | JsonElement
        //   localizable: true  → IReadOnlyDictionary<string, object> keyed by BCP 47 locale
        if (entry.Value is IReadOnlyDictionary<string, object> localeMap)
        {
            var enValue = localeMap["en-GB"];
        }
        else
        {
            var value = entry.Value;
        }
    }
}

Namespaces

Working with values

Attribute values are stored as object (their shape depends on the model), but you rarely need to cast by hand. AttributeValueEntry exposes typed accessors:

var attrs = product.Attributes!;

double weight = attrs["weight"].AsNumber();          // throws if not a number
bool   isNew  = attrs["is_new"].AsBool();
string fit    = attrs["fit"].AsString();             // select id, link id, text, …
var    tags   = attrs["tags"].AsStringList();        // text-list / select-list / *-link-list
JsonElement raw = attrs["spec_sheet"].AsJson();      // json attributes

if (attrs["sku"].TryAsString(out var sku)) { /* … */ }   // non-throwing variants

// Localizable attributes carry a locale-keyed value:
var name = attrs["name"];
if (name.IsLocalized)
    string? enName = (string?)name.ForLocale("en-GB", fallbackLocale: "en-US");

Locale-keyed labels (Label, Description, etc.) have resolution helpers:

string? colour = attr.Label.Resolve("de-DE", fallbackLocale: model.DefaultLocale);
string  shown  = attr.Label.ResolveOr("de-DE", defaultValue: attr.Id);

And model ids resolve without manual First(...) scans:

var pt  = model.Model.ProductTypeById(product.ProductTypeId);   // one-off lookup
var def = model.Model.ProductAttributeById("colour");

var index = model.Model.Index();                                // O(1) for repeated lookups
foreach (var p in data.Data.Products)
    var t = index.ProductType(p.ProductTypeId);

Conformance validation

OPXFValidator.Validate() enforces the cross-file rules from docs/conformance.md — constraints that JSON Schema alone cannot express. Each ValidationError carries:

• RuleId — the conformance rule code, e.g. CONF-02
• Message — human-readable description of the violation
• Path — RFC 6901 JSON Pointer to the offending element, e.g. /data/products/0/productTypeId

OPXFValidator.ValidateModel() validates model internal integrity (CONF-31 through CONF-43, plus the model-side market rules CONF-55..57) without a data file.

Validators collect all violations in a single pass — a payload returns all errors at once, not just the first.

Transfer mode

opxf.transferMode is required and modeled as the TransferMode enum (Snapshot / Incremental) — a missing or unknown value is a deserialization error, not a silent default. When Incremental, referential existence rules (CONF-28, CONF-29, CONF-38) are relaxed — missing targets are the exporter's responsibility. Snapshot enforces them fully.

Conformance rules implemented

Section 1 — Model/Data binding

Section 2 — Products

Section 3 — Variants

Section 4 — Objects

Section 5 — Assets

Section 6 — Attribute value types

Section 7 — Categories

Section 8 — Model internal integrity

Section 9 — Entity id format

Section 10 — Cross-file references

Section 11 — Lifecycle and tombstones

Section 12 — Markets and market scoping

Lifecycle

Every product, variant, object, and asset carries a mandatory Lifecycle (OPXF 0.2):

Lifecycle.Draft     // "draft"    — not yet published
Lifecycle.Active    // "active"   — live and current
Lifecycle.Archived  // "archived" — retired but retained for reference
Lifecycle.Deleted   // "deleted"  — tombstone: remove downstream (still carried so links resolve)

Assets additionally carry a required UrlUpdatedAt (DateTimeOffset) whenever a Url is present, for cache-busting and change detection.

Attribute types

AttributeType is an enum of all OPXF canonical types. Each member serializes to its kebab-case wire string via the built-in converter:

AttributeType.Text            // "text"
AttributeType.TextList        // "text-list"
AttributeType.Textarea        // "textarea"
AttributeType.Number          // "number"
AttributeType.Boolean         // "boolean"
AttributeType.Datetime        // "datetime"
AttributeType.Select          // "select"
AttributeType.SelectList      // "select-list"
AttributeType.AssetLink       // "asset-link"
AttributeType.AssetLinkList   // "asset-link-list"
AttributeType.ObjectLink      // "object-link"
AttributeType.ObjectLinkList  // "object-link-list"
AttributeType.ProductLink     // "product-link"
AttributeType.ProductLinkList // "product-link-list"
AttributeType.Json            // "json"

Related repositories

License

MIT