(Background)
The NIEM-UML specification states for <<References>>, from Clause 8.2:
...If a Property is the client of a References Realization, then it represents a NIEM property defined by reference to the NIEM property declaration represented by the supplier of the Realization. It is implemented in XSD schema as an attribute use or element particle that references the attribute or element declaration that implements the supplier of the Realization. ...
From Clause 7.5.2 Property Holders and Property References/Representation
Common
The client UML property of a «References» realization represents the use, in the context of the complex type represented by the owning class of the property, of the NIEM property declared by the supplier UML property of the realization
.
PSM
A property reference is implemented as an attribute use or element particle referencing the corresponding declaration. If the UML property representing the property declaration is contained in a different «Namespace» package than the UML property representing the property reference, then the implementation of the property reference will refer to a declaration in a different schema.
From Clause 7.5.2.3 Mapping Summary (part of Clause 7.5.2 referenced above)
PIM to PSM Mapping
A realization between two properties in a PIM with the stereotype «References» applied shall map to a corresponding realization in the PSM with the «References» stereotype applied, between corresponding properties mapped from the PIM.
PSM to XML Schema Mapping
A property in a PSM that is owned by a class with the «PropertyHolder» shall be mapped as an attribute or element declaration
A property in a PSM that is the client of a «References» or «XSDDeclaration» realization whose supplier has a different target namespace shall be mapped as an attribute use or element particle
The attribute use or element particle shall have its ref attribute set to the attribute or element declaration mapped from the supplier of the realization.
A summary of the above excerpts for a <<References>> is:
· The client is mapped to an attribute use or element particle, within a type, within a schema having some targetNamespace, and the schema is located at a file location within the MPD as specified by the MPD catalog.
· The supplier is mapped to a top level attribute or element declaration, within a schema having some targetNamespace, and the schema is located at a file location within the MPD as specified by the MPD catalog.
Conflict:
From the "Guide" portion of the NIEM-UML spec, for a PIM:
Any use in the subset package of an element (e.g., classifier or property) from the reference package is considered to instead refer to a similarly named element included in the subset package. In particular, the use of a property declaration from the reference package as the supplier of a «References» realization from an element of the subset package results in the reference actually being to a corresponding property declaration in the subset package.
This overloading of the <<References>> was originally deemed feasible based on the following assumptions:
Distinction between the two meanings of <<References>> could be determined by distinguishing whether or not the supplier was in a reference model and the client was not in a subset model.
The primary use of the PIM meaning of <<References>> would be with respect to transforming to a subset model which was wired up according to this description. Other uses of the model, such as defining business constraints as OCL, or instantiating instances of an exchange, were not part of the consideration for this meaning of <<References>>.
There was only one reference model and only one corresponding subset model visible within the scope of an IEPD.
These assumptions are now known to be too simplistic:
· Some form of controlled modification (e.g., subsetting) of namespace content occurs between different types of models at many levels:
o Domain and Core Updates. Change and/or extend reference models, derived product is a reference model.
o EIEM. “Subset” reference models, derived product is typically a subset model but may sometimes be tagged as a reference model. EIEM will also introduce extension models and control visibility of NIEM reference models.
o IEPD. May “subset” reference models with derived product being a subset model. May “subset” EIEM provided subset models, with derived product a subset model. May “subset” EIEM provided extension models, with derived product an extension model.
o Constraints. May be based on reference, subset, extension, exchange; derived product is termed a constraint model.
· Multiple models with same target namespace will be visible to the modeler. Many times an IEPD model will contain multiple exchange models, each based on different derivations of the same NIEM reference model. For example, there may be a “request” exchange model and a “response” exchange model. Each exchange model may be based on a different subset of an EIEM subset of a NIEM reference model. Thus, in this scenario, the modeler will have visibility to his request nc subset, his response nc subset, an EIEM nc subset, the original NIEM reference model, and some nc constraint models. Additionally, the modeler may use the EIEM subset models directly rather than going through his own subsetting process.
When a modeler references a Property, he is not just referencing a target namespace, but a specific model, which has its unique location. Since subsetting may be across almost any kind of model, it becomes unclear how to interpret a <<References>> to a subset model: is it intended to be in the role of a “base” model for derivation purposes, is it intended to be in the role of a “base” model for a “base” model of a derivation, is it intended to be a reusable component of an EIEM defined model (which may have a derived model elsewhere in the IEPD), is it intended to be the derived model? When it is intended to be the “base” model, which “derived” model amongst several, with the same namespace, in an MPD would it be? Failure to unambiguously resolve these derivations may lead to lack of coherence in provisioned MPDs, with multiple conflicting schema locations for the same namespace within a given exchange schema set, which in turn will result in schema validation failures.
Additionally, in cases of business constraints represented as OCL:
The use of references to reference model types/properties as implicit references to subset types/properties would prevent proper validation of OCL. The reference model is bigger than the subset model, and it would not be possible to determine if references to types/properties within the OCL were valid in the context of a particular exchange, with its constrained view of subset models.
And for instance models:
The instantiation of references to a reference model would necessarily require instantiation of reference model components to maintain a well-formed UML model. It would not be possible to access or represent extensions such as subtypes or substitution groups from the reference model instantiation.
Execution of the OCL validation for instance models would be subject to the composite set of issues with OCL and instantiation representations.
The implicit version of Property <<References>> was originally intended to provide some level of abstraction over the concrete form of Property <<References>>. Concrete <<References>> are required to unambiguously define coherent exchange schema sets, business constraints, instance models, and constraint validation of instance models. Nevertheless, a distinguishable markup for the more abstract representation of property derivation (and type references) could serve a complementary role. In the context of an Enterprise developing IEPDs, the set of shareable components known as an EIEM is often volatile. The names and other characteristics of the components change, which impact the derived IEPDs. A mechanism to establish a relationship between an IEPD and its corresponding EIEM components would enable a smoother transition across EIEM versions. For example, the use of markup establishing refs from property uses to declarations could partially automate changes in the concrete representation of names, types, and other characteristics of base components at the IEPD level. However, the suggested resolution for this issue does not include new markup.
Suggested resolution
The suggested resolution is to add a <<Subsets>> stereotype as a specialization of <<References>>. This stereotype should always be used between a subset and a reference model. <<References>> between packages interpreted as a <<subsets>> should be retained for backwards compatibility.