[BUG] - description and desciption bundle documentation should call out hidden disjoint behavior

Description

In sections 3.3.1.1 and 3.5.1.2 of the OML language reference, the current text and example inform and lead the user to believe they should be using the namespace of the vocabulary. What is hidden is the fact that it may be highly preferrable to use the vocabulary bundle's namespace.

If the vocabulary bundle's namespace is used, the reason will use the bundle and then run the disjoint algorithm. This means the bundle.owl file that is created will have disjoint information.

If the namespace of the vocabulary is used instead of the bundle's namespace, disjoint information is not created and hence will not be available. This could alter reasoning significantly.

Steps to Reproduce

In either the description file or the vocabulary bundle file, if the namespace of the target vocabular is used, then Oml2OwlTask will not know to close the world and subsequently there will be no bundle.owl file that is created and thus no disjoint information for the vocabulary exists.

description bundle <http://okean.solutions/test-models/bundle#> as tm-db {
  uses <http://okean.solutions/monsid/monsid-types#>
  includes <http://okean.solutions/test-models/tc2#>
}

The result is that when the uses statement directly references a vocabulary file (in this case monsid-types.owl via catalog namespace mapping), there is no resulting disjoint information when the Oml2OwlTask runs.

When the bundle's namespace used instead, a bundle.owl is created and the disjoint information exists within the file (see the following example).

description bundle <http://okean.solutions/test-models/bundle#> as tm-db {
  uses <http://okean.solutions/monsid/bundle#>
  includes <http://okean.solutions/test-models/tc2#>
}

Expected Behavior

In sections 3.3.1.1 and 3.5.1.2 (Description Imports Usage and Description Bundle Imports Usage, respectively), should clearly call out that referencing a bundle namespace will allow the creation of disjoint information. Otherwise, no disjoint information will be created.

Suggested wording:

uses NAMESPACE (as ID)?

Where NAMESPACE represents either the vocabulary namespace or the vocabulary bundle's namespace. Note that referencing a vocabulary namespace vs. bundle's namespace has consequences on disjoints. It may be preferable to use the vocabulary bundle's namespace if available. See section NN.NN for details.

where section NN.NN goes into detail about disjoints.

Note: section NN.NN would be a new addition to the OML spec that discusses how disjoints are created/calculated.

opencaesar / oml