Module reference

Reference shape and factories.

Defines ReferenceShape and the reference factory used to link a resource to another standalone resource identified by an absolute IRI. References pair an IRI value with a ResourceShape that describes the target resource, supporting circular and self-referential definitions through lazy resolution.

Defining Reference Properties

Wrap a target resource shape with reference and apply a cardinality factory:

import { required, multiple } from '@metreeca/blue/value';
import { reference } from '@metreeca/blue/reference';
import { resource, id } from '@metreeca/blue/resource';

const Vendor = resource({
  id: id()
});

const Product = resource({
  id: id(),
  vendor: required(reference(Vendor)),
  suppliers: multiple(reference(Vendor))
});
Copy

Standalone vs Embedded Resources

A reference() wrapper links to a standalone resource, an independently identified and managed entity. A direct shape inclusion (without the wrapper) defines an embedded resource, a nested object with no independent identity, created and managed together with its parent. See resource for the embedded form.

Retrieval Forms

In a retrieval template, a reference-valued property accepts either form:

1. IRI reference — a bare IRI reference placeholder retrieves only the identifier of the linked resource, without inspecting any of its entries. As a placeholder it is never resolved on decoding, so it admits any IRI reference: the empty string, a root-relative or relative reference, or an absolute IRI. Reference values proper (the operands of a selection) are resolved against the base IRI and absolute by validation time.
2. Nested resource template — a nested template retrieves the requested subset of the linked resource, validated against its target shape and subject to the template validator's depth budget (if any).

Setting the template validator's depth option to 0 disables form 2 while still accepting form 1. See validate for the full form comparison and resource!ResourceShape for the companion embedded form.

Foreign and Captive References

The optional foreign and captive flags refine the link semantics:

• foreign marks the reference as a read-only view over data owned by the target resource; foreign entries are accepted in retrieval templates but rejected in resource state
• captive marks the referenced resource as existentially dependent on the source resource: it has its own identity and lifecycle but is cascade-removed when the source is deleted

The two flags are independent and may be combined.