About Automatic Linking and Embedding
RAPID-ML™ promotes convention over configuration by including useful and intuitive default behaviors. Modelers only need to specify relationships and behaviors that differ from the defaults.
One of the important areas of behavior in a Resource API is linking and embedding -- the realization of a Reference Property as a hyperlink to another resource, or as an embedded object within the referring resource. RAPID-ML determines linked vs. embedded realization according to the rules defined here.
About Default Resources
When a resource or a request or response message is bound to a Data Structure, the Data Structure is realized within this bound context. The resource or message may include a Property Set, Reference Links and/or Reference Embeds in order to explicitly specify the realization. But there are rules that determine a default realization for any Reference Property whose realization is not explicitly specified as a Reference Link or Reference Embed.
Where possible, RAPID-ML's default realization rules will interpret reference properties as hyperlinks. In order to do this, there needs to be an appropriate target resource for the hyperlink. We refer to this as a default resource.
More specifically, a default resource is applicable to reference properties:
|•||with a given multiplicity - single-valued or multi-valued.|
So there is not one single "default resource." Within the context of a Resource API, different accessible resources (locally defined or imported) can serve as default resources. Each default resource is the default hyperlink target for either single-valued or multi-valued references to a certain data type.
Rules for Determining Default Resources
Within a Resource API, the default resource for references to a given Data Structure, with a given given multiplicity, is determined as follows:
|•||If there is no resource in the addressable scope that is bound to the referenced Data Structure and that has the required multiplicity -- an Object Resource for a single-valued reference or a Collection Resource for a multi-valued reference -- then there is no default resource.|
|•||If there is exactly one resource in scope that is bound to the referenced Data Structure and that has the required multiplicity, that resource is designated implicitly as the default resource.|
|•||If there is more than one resource in scope that is bound to the referenced Data Structure and that has the required multiplicity:|
|o||If exactly one of those resources is explicitly designated as the default resource by use of the default qualifier keyword, that resource is the default resource.|
|o||If none of those resources is explicitly designated as the Default Resource, or if more than one of those resources is so designated, then there is no default resource.|
Default Link Descriptors
In RAPID-ML, Reference Links can be plain hyperlinks, or "decorated" with one or more properties of the target Data Structure. The most direct way to decorate a hyperlink is by adding target properties to the Reference Link.
Sometimes it is useful for a resource to define a reusable decorated link specification, so that referrers do not have to specify the target properties explicitly in each instance. This reusable specification is called a Link Descriptor Definition. A resource can define any number of link descriptors, and a Reference Link targeting that resource can apply any of these by name.
Furthermore, one of these link descriptors can be designated implicitly or explicitly as the default, such that any resource link targeting that resource will automatically apply the default Link Descriptor Definition unless otherwise specified.
The rules for default link descriptors are as follows:
|•||If a resource defines exactly one Link Descriptor Definition, that Link Descriptor Definition is implicitly designated as the default.|
|•||If a resource defines more than one Link Descriptor Definition:|
|o||If one of the defined link descriptors is explicitly designated as the default by use of the default keyword, that Link Descriptor Definition is the default.|
|o||If none of the defined link descriptors is excplicitly designated as the default, there is no default Link Descriptor Definition.|
|o||If more than one Link Descriptor Definition on a single resource is defined with the default keyword, this is an error condition.|
|•||Automatic Reference Links will use the target resource's default Link Descriptor Definition, if there is one.|
|•||Explicit Reference Links will use the target resource's default Link Descriptor Definition, unless the Reference Link explicitly specifies a different named Link Descriptor Definition, or specifies a delimited list of target properties.|
Default Realization of Reference Properties
Building on the above specified rules for default resources and default link descriptors, reference properties are realized as follows:
|•||If there is an explicit Reference Link or Reference Embed for the Reference Property, this defines the realization.|
|o||If there is an explicit Reference Link that does not specify a Link Descriptor Definition or target properties, and the target resource has a default Link Descriptor Definition, that Link Descriptor Definition is applied to the Reference Link.|
|•||If there is no explicit Reference Link or Reference Embed:|
|o||If there is a default resource in scope for the reference, the reference is realized as a hyperlink. If the default resource has a default Link Descriptor Definition, the Link Descriptor Definition applies to the automatic hyperlink.|
|o||If there is no default resource in scope, the reference is realized as an embedded object. |