@owsp/js

Runtime utilities for OpenWinSpec schemas: projection via x-partial, canonical stringification (4-decimal numbers), hashing, and validation helpers.

Quick usage

import {
  listSerializeFields,
  extractBySerializeGroup,
  hashBySerializeGroup,
} from "@owsp/js";

const alias = "Material Profile System"; // schema title

// Inspect which fields participate in a group
const fields = listSerializeFields(alias, "summary");

// Build a projection and hash it deterministically
const projection = extractBySerializeGroup(alias, data, "summary");
const hash = hashBySerializeGroup(alias, data, "summary");

See docs: ../../docs/guide-x-partial.md.

Schema property ordering (x-order)

The package exposes helpers to order object properties according to x-order annotations in schemas. This is useful for stable serialization/UI forms.

APIs:

• Auto-detect schema and order:

import { orderObject } from "@owsp/js";

const ordered = orderObject(data);

• Order by bundle type (when known):

import { orderObjectByType, BundleType } from "@owsp/js";

const ordered = orderObjectByType(BundleType.MaterialSystem, data);

• Order by schema $id (internal tools):

import { orderObjectBySchemaId } from "@owsp/js";

const ordered = orderObjectBySchemaId(
  "https://openwinspec.org/schemas/v1/material/profile/profile-system.json",
  data
);

Details: ../../docs/schema-ordering.md.

Behavior notes:

• If some known properties have x-order, they come first by x-order value, then known properties without x-order (sorted by key), then unknown properties (sorted by key).
• If at a given object level none of the known properties have x-order, the original key order is preserved at that level; nested values are still processed recursively and may be ordered if their schemas specify x-order.

Build & test

nx build js
nx test js

Projection & Sorting Details

• Deep projection: extractBySerializeGroup() walks nested objects/arrays, resolving $ref, oneOf, and allOf to collect fields annotated with x-partial.
• Array sorting: If a schema property has x-partial.sortArrayBy: [key1, ...], arrays are sorted deterministically by these keys. Numeric keys sort ascending numerically; otherwise comparison falls back to canonical JSON strings.
• Post-projection sort: Arrays are re-sorted after projecting inner items to ensure final ordering matches sorting rules.
• Targeted fallback for glazing: For glazing assemblies, inner arrays glazings[*].seals and glazings[*].glazing_beads project as {vendor, id} when no x-partial fields are present, with thickness included when available. This avoids changing schema structure.
• Scope: The glazing fallback is deliberate and not applied to other assemblies (e.g., sash_seal). Behavior for other assemblies depends on their x-partial annotations.