Cardinality of Applicability

[MarcelStepien]

I have a remark towards the documentation that should maybe be addressed immediately.

The following links is the documentation for cardinality of applicability and requirements:
https://github.com/buildingSMART/IDS/blob/ver/1.0.x/Documentation/UserManual/specifications.md

I have an issue regarding the "optional" option for cardinality of applicability. If I remember correctly, in the discussion of our last developer meetings earlier this year, we agreed that only the options "required" and "prohibited" are valid for applicability.

As I recall, the cardinality for applicability is assigned to the end result of the filtered subsets of elements (in contrast to the per facet evaluation in requirements).

Therefore, we argued, that optional for applicability would mean the same as simply ignoring the filter. By declaring the applicability optional all elements are always included in the filtered subset for checking the requirements, since the applicability may or may not apply. The same behavior can also be achieved by simply leaving the applicability empty, meaning no specific applicability is provided, therefore, all elements are accepted for validation.

The documentation still includes the "optional" option for applicability. I think this single entry should be removed, to avoid confusion.

[andyward]

I think that decision got reversed. @CBenghi may remember exactly where.

Not sure why you'd want to remove it - Optional applicability provides a useful capability. Here's how I explain it

Required cardinality: There must be matching applicable items, or the test fails (regardless of the requirements). E.g. There must be IfcBuildingStoreys and they should be named like ...
Prohibited cardinality: The must not be any matching applicable items. (In this case the requirements are irrelevant). E.g. There must not be any IfcBuildingElementProxies
Optional cardinality: There may be matching items, and there, the requirements should be met. E.g. If there is an IfcBoiler it should have these properties.

Optional is important, because in the last example, the spec would fail if there were not a Boiler in the model (or it was in another discipline model)

[MarcelStepien]

I think there is a misunderstanding of how applicability can be understood in the contexts of rule checking or property assignment.

As stated in the documentation:
"Applicability: Identifies the subset of the model that we are intending to specify. There are many different types of objects in IFC models, but each Specification only applies to a subset. [...]"

Reading this, I make the assumption that applicability is used like a filter (similar to MVD) that results in a subset of elements that will be checked based on the requirements.

Assuming I write a "required" applicability that defines a single "entity facet" with name "IFCWALL".

If my model contain zero walls, it is still valid. An IDS that "required" a IFCWALL and did not found any would simply be not applicable for execution.

If the goal of "optional" as an option is to distinguish between "must have" and "can have" constains by simply checking if a subset resulting from a applicability is empty or not, this is not really specified at any point in the documentation that way. The only reference I can derive that information from is the provided example in the tables for "required" and "optional". Those, however, do not reflect the broad definition for applicability in the rest of the documentation.

So, either way there seems to be a clash somehow. Maybe the edge case of "zero applicable elements found" has to be addressed more clearly.

[MarcelStepien]

I think that decision got reversed. @CBenghi may remember exactly where.

Not sure why you'd want to remove it - Optional applicability provides a useful capability. Here's how I explain it

Required cardinality: There must be matching applicable items, or the test fails (regardless of the requirements). E.g. There must be IfcBuildingStoreys and they should be named like ... Prohibited cardinality: The must not be any matching applicable items. (In this case the requirements are irrelevant). E.g. There must not be any IfcBuildingElementProxies Optional cardinality: There may be matching items, and there, the requirements should be met. E.g. If there is an IfcBoiler it should have these properties.

Optional is important, because in the last example, the spec would fail if there were not a Boiler in the model (or it was in another discipline model)

The issue I have with that example is that it forces the applicability to always pre-evaluate a specification as "success" or "failed" (thats something the requirements should evaluate). For example, evaluating the applicability as not applicable (for required) would always be interpreted as "failed". But this is not how applicability is understood. A whole specification can simply "not apply" but still be part of a set of specifications. In that case, I do not want to tell a user about a "failed" applicability check but rather about a specification that can be ignored entirely. The same applies for "optional". If I did not filter any elements, it is misleading that a optional specification would print "success".

That is a relevant case to consider for all types of digital modelling guidelines. Those often define additional requirements that only apply in certain cases of modelling. But its a whole different beast of information if I simply say:

1. an applicability is optional and resulting elements are empty is evaluated as "successful" (meaning applicable) or
2. an applicability is required and resulting elements are empty is evaluated as "failed" (meaning not applicable).

I understand the differences, I believe its simply not clear enough in the documentation.

Tl;dr: Applicability should strictly decide about "applicable" and "not applicable" of a set elements. In case of "applicable" I would evaluate the requirements and determine "success" or "failure". That is, more or less, how the documentation reads, but not how the examples are written.

@andyward About your example: The option of a property can be still be expressed through the facets of the requirements, which still would have "optional" to express this use-case. But it should maybe not be expressed on the level of applicability, as I hopefully explained why.

[andyward]

Some of the backstory on this and the decisions are in #203 (comment) - it was quite a late change in IDS 0.97-1.0. It sounds like we need to fix up some of the docs.

[MarcelStepien]

In that case, I propose adding the following remark to the documentation to make it clear:

"The applicability filters a subset of elements from the model and produces the input that is checked by the requirements. In special cases the applicability may already evaluate the specification instead of an evaluation through the requirements:

1. an applicability is optional and filtered elements are empty evaluates the specification as "successful" (meaning applicable)
2. an applicability is required and filtered elements are empty evaluates the specification as "failed" (meaning not applicable).

A none empty filtered subset has to be evaluated by the requirements, always."

[MarcelStepien]

However, there is one more issue regarding the applicability in combination of prohibited:

If the applicability works as described in the example, we are heavily limiting the capabilities of IDS. The Example in the documentation states that prohibited ignores the requirements and only checks the applicability. So, again, the applicability is performing the evaluation instead of the requirements.

Its more logical for IDS that prohibited simply inverts the subset and the let the requirements handle the evaluation. The separation between applicability and requirements is super unclear, or rather their functionally is blending into each other.

To more specific:
The options "required", "optional" or "prohibited" are not applied to the filter of the applicability, but are used to pre-determine an evaluation result for the whole specification.

This is irritating and makes explaining IDS more complicated.

[andyward]

To be honest I'm not sure how much that clarifies (given these are docs for end users not tech implementors).

A none empty filtered subset has to evaluated by the requirements, always

Not entirely clear what this actually means - or if it's correct.

Isn't the applicability cardinality intent already clear from the table under 'Cardinality of the applicability entity'?

[MarcelStepien]

Isn't the applicability cardinality intent already clear from the table under 'Cardinality of the applicability entity'?

Its ONLY the table that makes it more clear. And my argument is that the rest of the documentation do not reflect the example that is described there. Because in the example part of the evaluation is done only by the applicability. Something I argue should not be the case.

Applicability = filter
Requirement = evaluation

In my opinion.

[andyward]

We crossed over. This is probably better as a discussion given 1.0 is shipped and it's by design?

I agree that it's strange that required and prohibited are not symmetrical. i.e. as an author I kind of expected NOT(Required applicability) == Prohibited applicability

[MarcelStepien]

We crossed over. This is probably better as a discussion given 1.0 is shipped and it's by design?

I agree that it's strange that required and prohibited are not symmetrical. i.e. as an author I kind of expected NOT(Required applicability) == Prohibited applicability

But nothing in the schema has to be changed. Its just confusing and can be solved by clarifying how applicability and requirements should behave. Its either one of two option that can fix this issue immediately:

1. Provide a different example that fits the rest of the documentation and behavior of the evaluation.
2. Clarify how applicability and requirements influence the outcome of results as a concept and were the points of intersections are.

[andyward]

May just put a PR in with the proposed edits?

[atomczak]

The documentation looks fine to me as it is. Yes, the requirements are ignored when the subset selected by applicability is prohibited because the existence of prohibited elements already triggers an error. I don't see any benefits of changing that, and it would cause chaos to the ongoing implementation/education.

@MarcelStepien, assuming @andyward's (and mine) interpretation (option 2 from your list), please propose what improvements you would like to see in the docs to make it more consistent and clear by submitting a PR. Please try to keep the language simple for the non-technical readers.