urpx.core — energy.grid-coordination/clj-urpx 0.12.0

URPX rate plan loading and price resolution.

Parses URPX JSON-LD rate plan documents into Clojure data structures and resolves prices for any given timestamp and timezone.

expand-document-entities clj

(expand-document-entities entity)

Public because it is the one piece a CLI or a third-party consumer needs and cannot otherwise reach: load-graph returns top-level entities only, so anything that walks a document itself would never descend a wrapper and would validate the wrapper metadata alone.

If entity is one of wrapper-types, return its embedded payload entities: urpx:hasRatePlan and urpx:hasRatePlanModifier (both wrappers), urpx:hasTariffPublication (v0.2.x URPXDocument only), and urpx:packages (the general containment pointer added in v0.3.0). Otherwise return [entity] unchanged.

Used by load-rate-plan and load-rate-plan-modifier to descend transparently through the wrapper so consumers can target inner entities by @type without caring whether the document is wrapped, bare single-entity, or @graph-bundled.

keys->jsonld clj

(keys->jsonld v)

Walk a Clojure data structure converting namespaced-keyword map keys back to their JSON-LD string forms via keyword->jsonld-key. Inverse of the private transform-keys walker that the parse path uses to keywordize incoming JSON-LD.

Output is plain JSON-friendly Clojure data (string keys, leaves unchanged), ready for clojure.data.json/write-str.

keyword->jsonld-key clj

(keyword->jsonld-key k)

Inverse of prefixed-key->keyword: a Clojure keyword → its JSON-LD string-key form.

• :jsonld/X (reserved JSON-LD keys) → "@X" (covers @type, @id, @context, @graph).
• Namespaced keywords → "ns:local" (CURIE form, e.g. :urpx/name → "urpx:name").
• Bare keywords → "name".

Used by the write-side path (urpx.emit, URPX-biu) to project a typed entity back into the JSON-shaped data that clojure.data.json/write-str serializes.

load-graph clj

(load-graph src)

Load a URPX JSON-LD document from src — anything clojure.java.io/reader can coerce (File, URL, Reader, InputStream, or path string). See parse-graph for the unwrapping semantics.

Accepting URLs lets callers pass the result of (io/resource ...) directly, including the jar:file:...!/... URL form that classpath lookups produce when the library is deployed inside an uberjar.

load-rate-plan clj

(load-rate-plan src)

Load a URPX rate plan from src — anything clojure.java.io/reader can coerce (File, URL, Reader, InputStream, or path string; URL forms include the jar:file:...!/... produced by (io/resource ...) against an uberjar classpath). The document may carry the plan in one of three shapes — all three resolve to the unique inner urpx:RatePlan:

• Single-entity doc: top-level @type: urpx:RatePlan.
• @graph bundle: the plan appears as one of several siblings (alongside RatePlanModifier(s), ProgramEnrollment, …).
• Wrapper: top-level @type: urpx:URPXDocument (v0.2.0 Decision #103) or urpx:URPXPackage (its v0.3.0 rename), with urpx:hasRatePlan or urpx:packages pointing at the plan.

Zero or more than one urpx:RatePlan in a single document is an error — use load-graph to inspect such documents directly.

load-rate-plan-modifier clj

(load-rate-plan-modifier src)

Load a URPX rate plan modifier from src (see load-rate-plan for the accepted shapes — File, URL, Reader, InputStream, path string, including jar:file:... URLs from (io/resource ...)). Parallel to load-rate-plan — the modifier may appear as a standalone single-entity doc, as one entity in a @graph bundle, or under a urpx:URPXDocument / urpx:URPXPackage wrapper's urpx:hasRatePlanModifier or urpx:packages pointer.

The unique urpx:RatePlanModifier is returned; zero or more than one is an error — use load-graph to inspect ambiguous documents directly.

load-rate-plan-modifier-version clj

(load-rate-plan-modifier-version src)

Load a top-level urpx:RatePlanModifierVersion snapshot from src. Parallel to load-rate-plan-version; the back pointer is urpx:forRatePlanModifier.

load-rate-plan-version clj

(load-rate-plan-version src)

Load a top-level urpx:RatePlanVersion snapshot from src.

v0.5.1 un-nests the version: a document may carry the snapshot as a sibling of the identity urpx:RatePlan rather than nested under urpx:hasRatePlanVersion, with the link stated upward as urpx:forRatePlan. All three v0.5.1 examples shipped with urpx-org/urpx do exactly this, and none asserts the down-pointer.

load-rate-plan discards such a snapshot, since it filters for urpx:RatePlan; this is its counterpart. Use urpx.index/versions-by-plan when a document carries several snapshots and you need them keyed by the plan they belong to.

Zero or more than one urpx:RatePlanVersion is an error.

parse-graph clj

(parse-graph src)

Parse a URPX JSON-LD document and return a vector of every top-level entity.

• Documents with a top-level @graph yield the graph contents (a vector of entity maps), e.g. a base RatePlan + its sibling RatePlanModifier bundled together.
• Single-entity documents yield a one-element vector containing the entity itself.

Always returns a vector so callers can use the same code path for both shapes; dispatch on each entity's :jsonld/type to decide what to do with it (e.g. via urpx.coerce/coerce-doc).

parse-rate-plan clj

(parse-rate-plan src)

Parse a URPX JSON-LD rate plan document from src (anything io/reader can handle: File, URL, Reader, InputStream, or path string).

Returns a Clojure map with keys converted to namespaced keywords: prefixed CURIEs (e.g. 'urpx:name') become :urpx/name; JSON-LD reserved keys ('@id', '@type', '@context') become :jsonld/id, :jsonld/type, :jsonld/context. String values (including CURIE references) are left unchanged.

This is a raw parser — it does not unwrap a top-level @graph container. Use parse-graph / load-graph for documents that bundle multiple entities.