Merge branch 'main' into 309-task-enhance-best-practice-with-rule-for-how-to-write-a-good-description

Author: aniluede

documentation/modules/ROOT/examples/aspect-sample.ttl

@@ -314,6 +314,15 @@
     samm:characteristic samm-c:Text .
 # end::see-oid-declaration[]
 
+# tag::see-irdi-declaration[]
+:drillDiameter a samm:Property ;
+    # Reference to IRDI 0173-1#02-AAC895#009
+    samm:see <urn:irdi:0173-1#02-AAC895%23009> ;
+    samm:characteristic :Diameter .
+# end::see-irdi-declaration[]
+
+:Diameter a samm:Characteristic .
+
 # tag::see-dontuse[]
 :organizationPerson a samm:Property ;
     samm:description "See ISO/IEC 11179-6:2015(E), section 3.35"@en ;

documentation/modules/ROOT/pages/modeling-guidelines.adoc

@@ -105,7 +105,7 @@ descriptions to it.
 
 [source,turtle,subs="attributes+,+quotes"]
 ----
-@prefix : urn:samm:{example-ns}.myapplication:1.0.0# .
+@prefix : <urn:samm:{example-ns}.myapplication:1.0.0#> .
 @prefix samm: <{samm}> .
 
 # The colon denotes the namespace as defined in the first @prefix declaration above.
@@ -641,7 +641,7 @@ include::example$extending-entity-declaration-inheritance.ttl[tags=extending-ent
 ----
 
 [[declaring-abstract-entities]]
-==== Declaring Abstract Entities
+=== Declaring Abstract Entities
 
 In contrast to Entities, Abstract Entities cannot directly be instantiated. A Characteristic class may have a type `samm:entity` or `samm:AbstractEntity`. But a Characteristic instance cannot have a type `samm:AbstractEntity`. If there is an instance created from a Characteristic that uses an Abstract Entity as its type, this Characteristic instance's dataType must be a sub-Entity of the Abstract Entity.
 The main use case for Abstract Entities is to share Properties across multiple Entities. This can be achieved through inheritance: Abstract Entities can extend other Entities and Abstract Entities and can themselves be extended in a manner not dissimilar to how abstract classes are used in many programming languages.
@@ -655,7 +655,7 @@ include::example$aspect-sample.ttl[tags=abstract-entity-declaration]
 ----
 
 [[abstract-entities-with-abstract-properties]]
-==== Abstract Entities with Abstract Properties
+=== Abstract Entities with Abstract Properties
 
 When an Abstract Entity needs to be defined with a certain Property, but the modeler using the
 Abstract Entity (i.e., extending it) should be able to decide the Property's Characteristic, the
@@ -763,6 +763,19 @@ xref:samm-specification:appendix:bibliography.adoc#rfc3061[[rfc3061\]], so for e
 include::example$aspect-sample.ttl[tags=see-oid-declaration]
 ----
 
+Another example for a type of unique identifier that is not a URI is the International Registration
+Data Identifier
+(https://eclass.eu/support/technical-specification/structure-and-elements/irdi[IRDI]) as used for
+example by the https://eclass.eu/[ECLASS] classification system. Referencing IRDIs is also done
+using a synthetic URN structure by prefixing them with `urn:irdi:`. However, since a valid IRDI
+always contains two `\#` signs, this alone does not make it a valid URI, which is why the second sign
+needs to be URL-encoded (`#` replaced with `%23`):
+
+[source,turtle,subs="attributes+"]
+----
+include::example$aspect-sample.ttl[tags=see-irdi-declaration]
+----
+
 If an external element should be referenced that has no unique identifier, `samm:see` should not be
 used. In this case, refer to the external element in the current model element's `samm:description`,
 for example:
@@ -785,21 +798,19 @@ a detailed description, and an external reference to the value.
 include::example$aspect-sample.ttl[tags=value-declaration]
 ----
 
-Also, as an ExampleValue in Property:
+A value can also be used as `samm:exampleValue` for a Property, either by referencing the value or
+by declaration of an anonymous value:
 
- - Additional Value:
 [source,turtle,subs="attributes+"]
 ----
 include::example$aspect-sample.ttl[tags=value-in-example-value-additional]
 ----
 
- - Anonymous ExampleValue:
 [source,turtle,subs="attributes+"]
 ----
 include::example$aspect-sample.ttl[tags=value-in-example-value-anonymous]
 ----
 
-
 [[optional-properties]]
 === Optional Properties
 

documentation/modules/ROOT/pages/namespaces.adoc

@@ -91,6 +91,8 @@ xref:samm-specification:appendix:bibliography.adoc#sparql[[sparql\]]):
 * The prefix "samm-c" _must_ be used for the URN `{samm-c}`
 * The prefix "samm-e" _must_ be used for the URN `{samm-e}`
 * The prefix "unit" _must_ be used for the URN `{unit}`
+* The prefix "xsd" _must_ be used for the URL `http://www.w3.org/2001/XMLSchema#`
+* The prefix "rdfs" _must_ be used for the URL `http://www.w3.org/2000/01/rdf-schema#`
 * The empty prefix (":" in RDF/Turtle) _must_ be used for the URN prefix of the current model scope, i.e.
   everything up to and including the `#` of the model elements that are being defined
 * For other elements, use prefixes that _must not_ contain the string `samm`.
@@ -103,4 +105,4 @@ xref:samm-specification:appendix:bibliography.adoc#sparql[[sparql\]]):
 @prefix : <urn:samm:{example-ns}.myapplication:1.0.0#> .
 
 include::example$prefixes-sample.ttl[tags=content]
-----
+----