From 3baa82de9f22f254f46dbb3112340ff328245e07 Mon Sep 17 00:00:00 2001 From: csnyulas Date: Wed, 21 Jun 2023 05:15:52 +0300 Subject: [PATCH] Re-tagged rules and sections, and fixed several typo in UML conventions. --- docs/modules/ROOT/pages/uml/conv-attributes.adoc | 4 ++-- docs/modules/ROOT/pages/uml/conv-classes.adoc | 4 ++-- docs/modules/ROOT/pages/uml/conv-connectors.adoc | 8 ++++---- docs/modules/ROOT/pages/uml/conv-datatypes.adoc | 8 ++++---- docs/modules/ROOT/pages/uml/conv-general.adoc | 11 +++++++++-- docs/modules/ROOT/pages/uml/conv-packages.adoc | 4 ++++ 6 files changed, 25 insertions(+), 14 deletions(-) diff --git a/docs/modules/ROOT/pages/uml/conv-attributes.adoc b/docs/modules/ROOT/pages/uml/conv-attributes.adoc index f99ce4ca..138eaabe 100644 --- a/docs/modules/ROOT/pages/uml/conv-attributes.adoc +++ b/docs/modules/ROOT/pages/uml/conv-attributes.adoc @@ -60,11 +60,11 @@ uml:Attribute shall be defined with generally accepted primitive datatypes. *Description:* -Each uml:Attribute must have a name and an attribute type. uml:Attribute is mostly transformed into owl:DataProperty and in some controlled cases into owl:ObjectProperty. High preference shall be given to using OWL 2 compliant XSD [xref:references.adoc#ref:xsd[xsd]] and RDF [xref:references.adoc#ref:rdf[rdf]] standard datatypes. [xref:uml/conv-datatypes.adoc#rule:primitive-datatypes[see Section on Primitive Data types]] +Each uml:Attribute must have a name and an attribute type. uml:Attribute is mostly transformed into owl:DataProperty and in some controlled cases into owl:ObjectProperty. High preference shall be given to using OWL 2 compliant XSD [xref:references.adoc#ref:xsd[xsd]] and RDF [xref:references.adoc#ref:rdf[rdf]] standard datatypes. [xref:uml/conv-datatypes.adoc#rule:datatypes-primitive[See convention on Primitive Data types]] In cases when a property needs to be defined as ranging on an unknown controlled list or authority table constitute a special case. They can be expressed as uml:Attribute with the datatype `skos:Concept`. These attributes are transformed into owl:ObjectProperty in a manner similarly to uml:Association. -An attribute may contain an alias, used as an alternative label. It can be specified via uml:Tags. [xref:uml/conv-general.adoc#rule:gen-tags[See section on uml:Tags]] +An attribute may contain an alias, used as an alternative label. It can be specified via uml:Tags. [xref:uml/conv-general.adoc#rule:gen-tags[See convention on uml:Tags]] [[rule:attributes-reuse]] |=== diff --git a/docs/modules/ROOT/pages/uml/conv-classes.adoc b/docs/modules/ROOT/pages/uml/conv-classes.adoc index ba52a1a7..29f183f0 100644 --- a/docs/modules/ROOT/pages/uml/conv-classes.adoc +++ b/docs/modules/ROOT/pages/uml/conv-classes.adoc @@ -37,7 +37,7 @@ Class names shall be formulated in singular. A class name represents a collection of objects. For example, a class "Language" actually represents all languages. Therefore, it could be more natural for some model designers to call the class "Languages" rather than "Language". In practice, however, the singular is used more often for class names, while the plural for sets and collections [xref:references.adoc#ref:noy2001[noy2001]]. Therefore, it is required that the class names must always use the singular lexical form. -[[rule:class-name-capital] +[[rule:class-name-capitalisation] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Capitalise class names @@ -121,7 +121,7 @@ Each uml:Class must have a short URI name. uml:Class is transformed into an owl:Class. Each uml:Class must have a name. -[[rule:class-descr]] +[[rule:class-description]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Class description diff --git a/docs/modules/ROOT/pages/uml/conv-connectors.adoc b/docs/modules/ROOT/pages/uml/conv-connectors.adoc index 8d3f72f5..6f138d3d 100644 --- a/docs/modules/ROOT/pages/uml/conv-connectors.adoc +++ b/docs/modules/ROOT/pages/uml/conv-connectors.adoc @@ -59,7 +59,7 @@ The name of the inverse relation should not be semantically inverted verb, such When the relation is of different nature, more like an attribute, then prefixing and suffixing techniques can be employed. For example, in the Organization Ontology [xref:references.adoc#ref:org-ontology[org-ontology]], the concepts of an "Organization" and a "Site" are defined along with two relationships that are the inverse of each other: "Organisation hasSite Site" and "Site siteOf Organisation" [xref:references.adoc#ref:d3.1-2015[d3.1-2015]]. -[[rule:connetors-inverse-def]] +[[rule:connetors-inverse-definition]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Definition of inverse relations @@ -248,7 +248,7 @@ uml:Generalization connector elements shall have no name or a target role specif The uml:Generalization connectors must have no name or source/target roles specified in the UML model. -[[rule:proxy-classes]] +[[rule:connetors-proxy-classes]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Proxy classes @@ -265,7 +265,7 @@ For classes defined in external models proxy uml:Class elements should be define In case a model class should inherit a class from an external model then proxies must be created for those classes. For example, if `Buyer` specialises an `org:Organization`, then a proxy for `org:Organization` must be created in the `org` package. -[[rule:disjoint-subclasses]] +[[rule:connetors-disjoint-subclasses]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Disjoint subclasses @@ -283,7 +283,7 @@ In this specification, the subclasses are assumed disjoint by default, unless ot -[[rule:equivalent-classes]] +[[rule:connetors-equivalent-classes]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Equivalent classes diff --git a/docs/modules/ROOT/pages/uml/conv-datatypes.adoc b/docs/modules/ROOT/pages/uml/conv-datatypes.adoc index 77884a48..b00f3a73 100644 --- a/docs/modules/ROOT/pages/uml/conv-datatypes.adoc +++ b/docs/modules/ROOT/pages/uml/conv-datatypes.adoc @@ -2,7 +2,7 @@ === Conventional recommendations on datatypes -[[rule:composite-datatypes]] +[[rule:datatypes-composite]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Primitive vs. composite datatypes @@ -22,7 +22,7 @@ This convention draws the distinction between primitive (or atomic) types (consi [[sec:uml-datatype]] === Technical conventions on uml:DataType elements -[[rule:primitive-datatypes]] +[[rule:datatypes-primitive]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* XSD and RDF datatypes @@ -66,7 +66,7 @@ The table above provides a simplified correspondence between UML and XSD datatyp * https://www.w3.org/TR/rdf11-concepts/#section-Datatypes[RDF 1.1 Datatypes section] * https://www.w3.org/TR/owl2-syntax/#Datatype_Maps[OWL 2 Datatype Maps] -[[rule:owl2-datatypes]] +[[rule:datatypes-owl2]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* OWL 2 datatypes @@ -82,7 +82,7 @@ Whenever possible, OWL 2 compliant XSD and RDF datatypes shall be used. We strongly recommended the use of OWL 2 compliant XSD and RDF standard datatypes, if possible. They might be useful also for indicating a specific datatype, which is impossible with the UML ones. For example, making a distinction between a general string (`xsd:string`) and a literal with a language tag (`rdf:langString`), or XML encoded ones such as `rdf:HTML` and `rdf:XMLLiteral`. -[[rule:proxy-datatypes]] +[[rule:datatypes-proxy]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Proxy datatypes diff --git a/docs/modules/ROOT/pages/uml/conv-general.adoc b/docs/modules/ROOT/pages/uml/conv-general.adoc index 14750293..7877aafe 100644 --- a/docs/modules/ROOT/pages/uml/conv-general.adoc +++ b/docs/modules/ROOT/pages/uml/conv-general.adoc @@ -13,6 +13,7 @@ UML is a language without formal semantics. Moreover, it is quite flexible and p In theory any name can be assigned to a concept, relationship or property. In practice, there are two types of constraints on the kind of names that should be used: _technical_ and _conventional_. This section deals with conventional recommendations, while the technical aspects are covered in later sections, such as [xref:sec:namespaces[]], [xref:sec:charset[]], and [xref:sec:stereotypes-tags[]] . +[[rule:gen-names-labels-and-ids]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Support for generation of human- and machine-readable denominations @@ -29,6 +30,7 @@ Element names should support generation of human- and machine-readable denominat The naming conventions apply to the _element names_ in the conceptual model. These names are intended for further use as human-readable denominations, called _labels_; and machine-readable denominations, called _identifiers_. The identifiers serve as a basis for generating URIs [xref:references.adoc#ref:rfc3986[rfc3986]] to ensure unambiguous reference to a formal construct; while the labels are meant to ease the comprehension by human-readers. For this reason we will consider that mostly the conventional recommendations provided here apply to them and none of the technical constraints. +[[rule:gen-names-language]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Recommendation on language @@ -46,6 +48,7 @@ It is recommended that the names and descriptions for classes and properties are In addition, a mechanism for providing a multilingual labelling system should be adopted. +[[rule:gen-names-namespaces]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Namespace definition @@ -62,6 +65,7 @@ The names should also belong to and be organised by _namespaces_. They can be pr *See also:* SEMIC Style Guide Rules [https://semiceu.github.io/style-guide/1.0.0/gc-general-conventions.html#sec:gc-r4[GC-R4]], [https://semiceu.github.io/style-guide/1.0.0/gc-semantic-conventions.html#sec:sc-r3[SC-R3]] and [https://semiceu.github.io/style-guide/1.0.0/gc-conceptual-model-conventions.html#sec:cmc-r6[CMC-R6]] +[[rule:gen-clear-language]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Use clear language @@ -148,7 +152,7 @@ This means that there cannot exist a class and an attribute with the same name ( Names that reduce to the same identifier are considered the same. For example "Legal Entity" and "LegalEntity" are different labels, but they reduce to the same identifier "LegalEntity". In such cases the names are considered equal and the UML elements replicated. -Although name uniqueness is a recommendation, sometimes it is useful to replicate a UML element. In such cases, when the names are reused, the assumption is that the two UML elements represent manifestations of the same meaning. This is especially important for relations, and is explained in Convention [xref:#rule:gen-relation-reuse[]]. +Although name uniqueness is a recommendation, sometimes it is useful to replicate a UML element. In such cases, when the names are reused, the assumption is that the two UML elements represent manifestations of the same meaning. This is especially important for relations, and is explained in convention [xref:#rule:gen-relation-reuse[]]. //[[sec:relation-reusability]] @@ -214,6 +218,7 @@ Optionally common and descriptive prefixes and suffixes for related properties o Large emphasis is set on the naming conventions. Nonetheless, most often, a good name is insufficient for an accurate or easy comprehension by human-readers. To mitigate this, and to increase the conceptual richness, practitioners may wish to provide human-readable definitions, notes, examples and comments grasping the underlying assumptions, usage examples, additional explanations and other types of information. +[[rule:gen-description]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Description of elements @@ -342,7 +347,7 @@ In order to enable the reuse of names defined in other models and reuse of uniqu // Namespaces are commonly structured as hierarchies to allow reuse of names in different contexts [xref:references.adoc#ref:xml-namespaces[xml-namespaces]]. This mechanism can be implemented in UML through partitioning the model using packages, which are described in the [xref:uml/conv-packages.adoc#sec:uml-package[uml:Package]] Section. -[[rule:gen-known-namespaces]] +[[rule:gen-namespaces-declared]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Known namespaces @@ -374,6 +379,7 @@ A namespace organises a collection of names obeying three constraints: each name In the formal ontology, the URIs must conform to RDF [xref:references.adoc#ref:rdf11[rdf11]] and XML[xref:references.adoc#ref:xml1-spec[xml1-spec]] format specifications. Both languages effectively require that terms begin with an upper or lower case letter from the ASCII character set, or an underscore (_). This tight restriction means that, for example, terms may not begin with a number, hyphen or accented character [xref:references.adoc#ref:d3.1-2015[d3.1-2015]]. Although underscores are permitted, they are discouraged as they may be, in some cases, misread as spaces. A formal definition of these restrictions is given in the XML specification document [xref:references.adoc#ref:xml1-spec[xml1-spec]]. +[[rule:gen-names-characters]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Valid characters in element and connector names @@ -391,6 +397,7 @@ Local names of elements should start with a letter or underscore. It is required that the names use words beginning with an upper or lower case letter (A–Z, a–z) or an underscore (_) for all terms in the model. Digits (0–9) are allowed in the subsequent character positions. Also, as mentioned above, spaces are permitted in the local segment of the name. +[[rule:gen-names-charsets]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* URI character sets diff --git a/docs/modules/ROOT/pages/uml/conv-packages.adoc b/docs/modules/ROOT/pages/uml/conv-packages.adoc index 798ee021..b0ba0892 100644 --- a/docs/modules/ROOT/pages/uml/conv-packages.adoc +++ b/docs/modules/ROOT/pages/uml/conv-packages.adoc @@ -1,6 +1,7 @@ [[sec:uml-package]] == Conventions on uml:Package elements +[[rule:package-partitioning]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Partitioning of the model @@ -18,6 +19,7 @@ Packages should be used to define a logical partition of the model. They serve a *See also:* SEMIC Style Guide Rule [https://semiceu.github.io/style-guide/1.0.0/gc-conceptual-model-conventions.html#sec:cmc-r15[CMC-R15]] +[[rule:package-hierarchy]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Hierarchy of packages @@ -33,6 +35,7 @@ Packages may form hierarchies. Packages may form hierarchies. In this case the hierarchical relation is interpreted as _meronymy_, denoting a constituent parts of the package. Formally they are translated into owl:import statements.The module corresponding to the parent package imports modules corresponding to the child packages. +[[rule:package-empty]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Empty packages @@ -48,6 +51,7 @@ There shall be no empty packages. No empty packages shall be present in the model. A package is empty if it contains no child elements. +[[rule:package-names]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Package naming