OPXF 0.1.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 8 and .NET 9.

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

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) 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 in the data file is advisory. When set to "incremental", referential existence rules (CONF-28, CONF-29, CONF-38) are relaxed — missing targets are the exporter's responsibility. When absent or unrecognised, "snapshot" semantics apply (strict enforcement).

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

Attribute types

The AttributeType class exposes string constants for all OPXF canonical types:

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