Merge pull request #151 from linkml/type-designator-docs

Docs for type designators

Author: cmungall

linkml_model/model/docs/specification/02instances.md

@@ -321,11 +321,11 @@ To interpret a path *p*:
 1. **VariableName** is resolved to an instance *i*
 2. For each path component in the path, reset *i* to be the value of looking up that component:
     - if the path extension is `.<s>` then *r* must be an **InstanceOfClass*, and the value is equal to the value of the slot assignment for slot `s`
-    - if the path extension is `[<id>]` then *r* must be an **InstanceOfCollection**, and the value is equals to the member of that list that has a slot with the role of *identifier* whose value is `<id>`
+    - if the path extension is `[<key>]` then *r* must be an **InstanceOfCollection**, and the value is equals to the member of that list that has a slot with the role of *identifier* whose value is `<key>`
 
 For example, if *i* is equal to the Person instance in the Combined Example above:
 
 * `i` == `i`
 * `i.id` == `String^"SSN:123"`
 * `i.height.unit` == `String^"cm"`
-
+* `i.relationships[0].related_to` == `Person&"SSN:456"`

linkml_model/model/docs/specification/04derived-schemas.md

@@ -24,7 +24,7 @@ We use *m* to denote the input or asserted schema (model), and *m<sup>D</sup>* t
 We provide a non-normative example of a schema in canonical YAML. This will be referred to
 in the remainder of the document.
 
-The schema is organized in a local folder as follows
+The schema is organized in a local folder as follows:
 
 person.yaml:
 ```yaml
@@ -96,7 +96,7 @@ This section defines functions that can be used in schema derivation rules.
 
 ### Normalize as List Function
 
-The function **L**(*v*) normalizes `v`to a list:
+The function **L**(*v*) normalizes `v` to a list/collection:
 
 | *v*                                 | **L**(*v*)      |
 |-------------------------------------|-----------------|
@@ -108,8 +108,8 @@ i.e.
 
 ```
 L(v) = 
-  v if v == [...]
   [] if v == None
+  v if v == [...]
   [v] otherwise
 ```
 
@@ -121,9 +121,36 @@ In the metamodel, the identifier **SlotDefinitionName** is always `name`, so thi
 
 > **K**(*v*) = *v*.**name**
 
+### URI and CURIE functions
+
+- a CURIE is a string that conforms to the [W3 CURIE specification](https://www.w3.org/TR/curie/)
+- a URI is a string that conforms to [rfc3987](https://www.ietf.org/rfc/rfc3987.txt)
+- The function **URI**(*s*, *v*) takes a string as input and normalizes it to a URI
+    - if the input is already a URI, then return it
+    - if the input is a CURIE, then expand it using the prefix map in *s*; this is known as *expansion*
+- The function **CURIE**(*s*, *v*) takes a string as input and normalizes it to a CURIE
+    - if the input is already a CURIE, then return it
+    - if the input is a URI, then shorten it using the prefix map in *s*; this is known as *contraction*
+
+When a CURIE is expanded, it is first decomposed according to the grammar defined in [W3 CURIE specification](https://www.w3.org/TR/curie/):
+
+> curie       :=   [ [ prefix ] ':' ] reference
+> 
+> prefix      :=   [NCName](http://www.w3.org/TR/1999/REC-xml-names-19990114/#NT-NCName)
+>
+> reference   :=   irelative-ref (as defined in [IRI](https://www.w3.org/TR/curie/#ref_IRI))
+
+The following concatenation is applied
+
+> **URI**(`<prefix>`: `<reference>`) = `m.prefixes`[`prefix`]`.prefix_reference` + `<reference>`
+
+For the reverse operation, any URI that starts with a prefix reference can be used to generate a valid CURIE.
+The one with the shortest reference is chosen as the canonical.
+
 ### Resolve Functions
 
 The function **Resolve** takes as input a **InstanceOfReference** and returns an **InstanceOfClass**
+that is the referenced object.
 
 | *i*                    | **Resolve**(*i*) |
 |------------------------|------------------|
@@ -192,24 +219,23 @@ The imports closure function **I** returns the reflexive **ReferenceClosure** of
 
 > **I**(*s*) = **C***(*s*, **s.imports**)
 
-### Function: Element CURIEs
+### Function: Element CURIEs and URIs
 
-The lookup table to retrieve the CURIE for an element is:
+For each element in the schema, we can derive a model URI and an element URI. These *may* be identical.
 
-| Type              | Main Rule     | Default                                  |
-|-------------------|---------------|------------------------------------------|
-| `ClassDefinition` | `e.class_uri` | `<m.default_prefix>:<SafeCamel(e.name)>` |
-| `SlotDefinition`  | `e.slot_uri`  | `<m.default_prefix>:<SafeSnake(e.name)>` |
-| `TypeDefinition`  | `e.uri`       | `<m.default_prefix>:<SafeCamel(e.name)>` |
-| `EnumDefinition`  | `e.enum_uri`  | `<m.default_prefix>:<SafeCamel(e.name)>` |
-| `PermissibleValue` | `e.meaning`   | `CURIE(Enum) + "." + Safe(e.text)`         |
+The following table is used:
 
-### Function: Expand CURIEs
+| Type                | Element URI   | Model URI                                |
+|---------------------|---------------|------------------------------------------|
+| `ClassDefinition`   | `e.class_uri` | `<m.default_prefix>:<SafeCamel(e.name)>` |
+| `SlotDefinition`    | `e.slot_uri`  | `<m.default_prefix>:<SafeSnake(e.name)>` |
+| `TypeDefinition`    | `e.uri`       | `<m.default_prefix>:<SafeCamel(e.name)>` |
+| `EnumDefinition`    | `e.enum_uri`  | `<m.default_prefix>:<SafeCamel(e.name)>` |
+| `PermissibleValue`  | `e.meaning`   | `ModelURI(Enum) + "." + Safe(e.text)`    |
 
-To expand a CURIE to a URL, the string is split on `:`. There must be two tokens.
-The first token is used to lookup `m.prefixes`, and the URL is constructed from:
+If the element URI slot is not set, then the model URI is used as the element URI.
 
-> `uri(PREFIX: LOCAL) = m.prefixes[PREFIX].prefix_reference + LOCAL`
+URIs can be contracted to CURIEs using the `prefixes` map in the model, see next function.
 
 ### Function: Applicable Slots
 
@@ -395,7 +421,28 @@ for c in m.classes:
 
 ### Rule: Derived Class and Slot URIs
 
-For each class or slot, if a class_uri or slot_uri is not specified, then this is derived by concatenating `m.default_prefix` with the CURIE separator `:` followed by the SafeUpperCamelCase encoding of the name of that class or slot definition
+For each class or slot, if a class_uri or slot_uri is not specified, then this is derived using the rules specified
+for Element URIs above.
+
+For example, given:
+
+```yaml
+prefixes:
+  foo: http://example.org/foo/
+  bar: http://example.org/bar/
+default_prefix: foo
+classes:
+  A:
+    class_uri: bar:A
+    ...
+  B:
+    ...
+```
+
+the following values would be set:
+
+ * `A.class_uri` = `http://example.org/bar/A`
+ * `B.class_uri` = `http://example.org/foo/B`
 
 ### Rule: Derived Permissible Values
 

linkml_model/model/docs/specification/05validation.md

@@ -48,10 +48,10 @@ The following holds for any validation procedure:
 | `NodeKind`            | ERROR     | range metatype         | `NodeKindConstraintComponent`     |
 | `MinimumValue`        | ERROR     |                        | `MinInclusiveConstraintComponent` |
 | `MaximumValue`        | ERROR     |                        | `MaxInclusiveConstraintComponent` |
-| `Pattern`             | ERROR     |                        | `PatternConstraintComponent` |
-| `EqualsExpression`    | INFERENCE |                        | `EqualsConstraintComponent` |
-| `StringSerialization` | INFERENCE |                        | `EqualsConstraintComponent` |
-| `TypeDesignator`      | INFERENCE |                        |  |
+| `Pattern`             | ERROR     |                        | `PatternConstraintComponent`      |
+| `EqualsExpression`    | INFERENCE |                        | `EqualsConstraintComponent`       |
+| `StringSerialization` | INFERENCE |                        | `EqualsConstraintComponent`       |
+| `TypeDesignator`      | INFERENCE |                        |                                   |
 
 For the `INFERENCE` type, the validation procedure MAY fill in missing values in the instance.
 There is only an error if the inferred value is not consistent with the asserted value.
@@ -133,13 +133,51 @@ The following checks only match when `i` is an **AtomicInstance**
 
 The following checks only match when `i` is an **InstanceOfClass**
 
-| **T**  | Element                            | Check             | Fail Condition                                      |
-|--------|------------------------------------|-------------------|-----------------------------------------------------|
-| `in`   | `<Class>(<Assignments>)`           | `Abstract`        | `Class.abstract`                                    |
-| `in`   | `<Class>(<Assignments>)`           | `Mixin`           | `Class.mixin`                                       |
-| `in`   | `<Class>(<Assignments>)`           | `ClassRange`      | `slot.range ∉ A*(<Class>)`                          |
-| `in`   | `<Class>(..., <subslot>=<V>, ...)` | `ApplicableSlot`  | `subslot ∉ <Class>.attributes`                      |
-| `in`   | `<Class>(..., <ts>=<V>, ...)`      | `DesignatedType`  | `<V> ∉ A*(<Class>)`  `ts = TypeDesignator(<Class>)` |
+| **T**  | Element                            | Check             | Fail Condition                                                                  |
+|--------|------------------------------------|-------------------|---------------------------------------------------------------------------------|
+| `in`   | `<Class>(<Assignments>)`           | `Abstract`        | `Class.abstract`                                                                |
+| `in`   | `<Class>(<Assignments>)`           | `Mixin`           | `Class.mixin`                                                                   |
+| `in`   | `<Class>(<Assignments>)`           | `ClassRange`      | `slot.range ∉ A*(<Class>)`                                                      |
+| `in`   | `<Class>(..., <subslot>=<V>, ...)` | `ApplicableSlot`  | `subslot ∉ <Class>.attributes`                                                  |
+| `in`   | `<Class>(..., <ts>=<V>, ...)`      | `DesignatedType`  | `∃ v ∈ L(<V>): v ∉ Norm(A*(<Class>), ts.range)` and `ts.designates_type = True` |
+
+For the DesignatedType check, the `Norm` function takes as input as a list of classes,
+and expands these according to the range of the slot `ts` that designates the type.
+
+
+| Range        | Match                                                |
+|--------------|------------------------------------------------------|
+| `string`     | { `c.name` }                                         |
+| `curie`      | { **CURIE**(`c.class_uri`) }                         |
+| `uri`        | { **URI**(`c.class_uri`) }                           |
+| `uriorcurie` | { **CURIE**(`c.class_uri`), **URI**(`c.class_uri`) } |
+
+For example, given an instance
+
+> `Organization(name="acme", type=String^"Business")`
+
+And a schema that includes:
+
+```python
+ClassDefinition(
+  name="Business",
+  is_a=ClassDefinition&Organization,
+)
+ClassDefinition(
+  name="Organization",
+  attributes=[
+    SlotDefinition(name="type", range=TypeDefinition&string),
+    ...
+```
+
+This will pass the `DesignatedType` check, because:
+
+* `A*(ClassDefinition&Business) = { ..., ClassDefinition&Organization, ... }`
+* `Norm(A*(ClassDefinition&Business), TypeDefinition&string) = { ..., String^"Business", ... }`
+* `String^"Business" ∉ { ..., String^"Business", ... }`
+
+DesignatedType checks can also executed in inference mode, where an inference engine
+may choose to assign the most specific value allowed to the slot.
 
 ### Enum checks
 
@@ -187,8 +225,6 @@ For each rule `r` in *C*.rules:
 
 ### Classification Rule evaluation
 
-### type designator checks
-
 ## Validation of TypeDefinitions
 
 For each slot `s` in **Assignments**, if `i.<s>` is not `None`, and `s.range` is in `m*.types`,

linkml_model/model/schema/meta.yaml

@@ -7,7 +7,7 @@ description: |-
   For more information on LinkML:
 
   * [linkml.io](https://linkml.io) main website
-  * [specification](https://linkml.io/linkml-model/docs/specification/)
+  * [specification](https://w3id.org/linkml/docs/specification/)
 
   LinkML is self-describing. Every LinkML schema consists of elements
   that instantiate classes in this metamodel.