Merge pull request #54 from co-cddo/issue-51_obligations

Improve presentation of a properties

Makefile

@@ -161,7 +161,8 @@ doc-setup:
 	mkdir -p $(EXAMPLEDIR)
 	cp src/data/*/valid/* $(EXAMPLEDIR)
 
-gendoc: gen-examples
+#gendoc: doc-setup
+gendoc: test
 	cp src/docs/*.md $(DOCDIR)
 	cp LICENSE.md $(DOCDIR)
 	$(RUN) gen-doc -d $(DOCDIR) \
@@ -179,7 +180,7 @@ mkd-%: gendoc
 # Needed as macOS does not support multiple entities with the same name but different cases
 docker-serve:
 	docker build -t model-docs .   
-	docker run -p 8080:8080 model-docs
+	docker run --name ukgov-metadata-docs -p 8080:8080 model-docs
 ###########################################################
 # CLEANUP
 ###########################################################

src/docs/templates/class.md.jinja2

@@ -40,19 +40,25 @@ URI: {{ gen.uri_link(element) }}
 {% endif %}
 
 ## Properties
-
-| Name | Cardinality and Range | Description | Inheritance |
+{% macro slots_table(heading, slots) -%}
+{% if slots | length > 0 %}
+### {{ heading }} Properties
+| Name | Range | Description | Cardinality |
 | ---  | --- | --- | --- |
-{% if gen.get_direct_slots(element)|length > 0 %}
-{%- for slot in gen.get_direct_slots(element) -%}
-| {{ gen.link(slot) }} | {{ gen.cardinality(slot) }} <br/> {{ gen.link(slot.range) }} | {{ slot.description|enshorten }} | direct |
-{% endfor -%}
-{% endif -%}
-{% if gen.get_indirect_slots(element)|length > 0 %}
-{%- for slot in gen.get_indirect_slots(element) -%}
-| {{ gen.link(slot) }} | {{ gen.cardinality(slot) }} <br/> {{ gen.link(slot.range) }} | {{ slot.description|enshorten }} | {{ gen.links(gen.get_slot_inherited_from(element.name, slot.name))|join(', ') }} |
-{% endfor -%}
+{% for slot in slots -%}
+| {{gen.link(slot)}} | {{ gen.link(slot.range) }}{% if slot.minimum_value is not none %}<br/>Minimum Value: {{ slot.minimum_value|int }}{% endif %}{% if slot.maximum_value is not none %}<br/>Maximum Value: {{ slot.maximum_value|int }}{% endif %}{% if slot.pattern %}<br/>Regex pattern: {{ '`' }}{{  slot.pattern }}{{ '`' }}{% endif %} | {{ slot.description|enshorten }} | {% if slot.multivalued %}Many{% else %}One{% endif %} |
+{% endfor %}
 {% endif %}
+{%- endmacro %}
+
+{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("required", "none") | rejectattr("required", "false") | sort(attribute='name') -%}
+{{ slots_table("Mandatory", slots) }}
+
+{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("recommended", "none") | rejectattr("recommended", "false") | sort(attribute='name') -%}
+{{ slots_table("Recommended", slots) }}
+
+{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("required") | rejectattr("recommended") | sort(attribute='name') -%}
+{{ slots_table("Optional", slots) }}
 
 {% if schemaview.is_mixin(element.name) %}
 ## Mixin Usage

src/docs/templates/slot.md.jinja2

@@ -15,31 +15,13 @@
 {% endfor %}
 {% endif %}
 
-URI: {{ gen.uri_link(element) }}
+## Obligation and Cardinality
 
-Range: {{gen.link(element.range)}}
+The obligation or cardinality can be overridden when used by classes. Check the [Applicable Classes](#applicable-classes) section below for details.
 
-{% if element.multivalued %}
-Multivalued: {{ element.multivalued }}
-{% endif -%}
-
-{% if element.required %}
-Required: {{ element.required }}
-{% elif element.recommended %}
-Recommended: {{ element.recommended }}
-{% endif -%}
-
-{% if element.minimum_value is not none %}
-Minimum Value: {{ element.minimum_value|int }}
-{% endif -%}
-
-{% if element.maximum_value is not none %}
-Maximum Value: {{ element.maximum_value|int }}
-{% endif -%}
-
-{% if element.pattern %}
-Regex pattern: {{ '`' }}{{  element.pattern }}{{ '`' }}
-{% endif -%}
+| URL                         | Range                       | Obligation  | Cardinality |
+|-----------------------------|-----------------------------|-------------|-------------|
+| {{ gen.uri_link(element) }} | {{gen.link(element.range)}} {% if element.minimum_value is not none %}<br/>Minimum Value: {{ element.minimum_value|int }}{% endif %}{% if element.maximum_value is not none %}<br/>Maximum Value: {{ element.maximum_value|int }}{% endif %}{% if element.pattern %}<br/>Regex pattern: {{ '`' }}{{  element.pattern }}{{ '`' }}{% endif %} | {% if element.required %}Mandatory{% elif element.recommended %}Recommended{% else %}Optional{% endif %} | {% if element.multivalued %}Many{% else %}One{% endif %} |
 
 {% if schemaview.is_mixin(element.name) %}
 Mixin: {{ element.mixin }}

src/model/uk_cross_government_metadata_exchange_model.yaml

@@ -75,13 +75,6 @@ classes:
       - type
       - theme
       - version
-    slot_usage:
-      accessRights:
-        required: true
-      description:
-        required: true
-      modified:
-        required: true
 
   DataService:
     is_a: DataResource
@@ -122,7 +115,12 @@ classes:
       - title
       - type
     slot_usage:
+      accessRights: 
+        required: false
+      description:
+        required: false
       modified:
+        required: false
         recommended: true
 
   Organisation:
@@ -148,6 +146,7 @@ slots:
   accessRights:
     slot_uri: dct:accessRights
     description: A rights statement that concerns how the distribution is accessed.
+    required: true
     range: AccessRightsValues
   address:
     slot_uri: vcard:hasAddress
@@ -294,6 +293,7 @@ slots:
     description: |
       A concise narrative of the content of an information resource.
       A free-text account of the distribution.
+    required: true
     range: string
     comments: |
       purpose:
@@ -453,6 +453,7 @@ Note that there could be a security risk in sharing the endpoint URL for interna
   modified:
     slot_uri: dct:modified
     description: The date, or date and time, on which the content of an information resource is changed.
+    required: true
     range: date
     comments: |
       purpose:
@@ -566,11 +567,19 @@ Note that there could be a security risk in sharing the endpoint URL for interna
   summary:
     slot_uri: rdfs:comment
     description: |
-      "A short textual summary of the resource with a maximum length of 250 characters. 
-
-      Usage note: The intended use of this text is in a page containing multiple search results. If omitted, the first part of the description text will be used. This may be up to a certain character count or the detection of a paragraph break."
+      A short textual summary of the resource with a maximum length of 250 characters. 
     recommended: true
     range: string
+    pattern: ^.{1,250}$
+    comments: |
+      purpose:
+        The intended use of this text is in a page containing multiple search results where a short one sentence or so summary is needed. 
+        
+        If omitted, the first part of the description text will be used. This may be up to a certain character count or the detection of a paragraph break, it is up to the application to decide.
+      distinctFrom:
+        - [`description`](/ukgov-metadata-exchange-model/description): to capture a full overview of the data asset
+      guidance:
+        The `summary` will be used where a short text overview of the data asset is required, e.g. in a page of search results. It should provide an idea of what the data asset provides but not give full details. Conciseness is key. 
   telephone:
     slot_uri: vcard:hasTelephone
     description: Telephone number for the contact team