Updates for week of March 4

- add some clarifications around the use of `latest` attribute
- clarify that attributes with default values don't require their owning
  Objects to be present
- be consistent about case after dashes (e.g. -word vs - Word)
- treat hasDocument resources like Groups. Use of ?meta is meaningless, every
  MUST always be in the HTTP body. No xRegistry HTTP headers
- DELETE will NOT return the deleted resources, use "204"
- "latest" on a request that would result in "no latest version" is an error
- "contenttype" is ok to use with RESOURCEurl. No guarantee it matches the
  Content-Type of a the GET to RESOURCEurl though
- URI Template type : per RFC6570 section 3.2.1 (level 1)

Signed-off-by: Doug Davis <[email protected]>

Author: Doug Davis

core/spec.md

@@ -271,7 +271,7 @@ The following attributes are defined for the `endpoint` type:
     where `SPEC` is the non-empty string name of the specification that
     defines the Resource. An OPTIONAL `VERSION` value SHOULD be included if
     there are multiple versions of the specification available
-  - for comparison purposes, this attribute MUST be considered case sensitive
+  - For comparison purposes, this attribute MUST be considered case sensitive
   - If a `VERSION` is specified at the Group level, all Resources within that
     Group MUST have a `VERSION` value that is at least as precise as its
     Group, and MUST NOT expand it. For example, if a Group had a
@@ -299,8 +299,8 @@ The following attributes are defined for the `endpoint` type:
   use this same binding
 - Constraints:
   - At least one of `format` and `binding` MUST be specified
-  - if present, MUST be a non-empty string
-  - if present, MUST follow the naming convention `{NAME}/{VERSION}`,
+  - If present, MUST be a non-empty string
+  - If present, MUST follow the naming convention `{NAME}/{VERSION}`,
     whereby `{NAME}` is the name of the protocol and `{VERSION}` is the
     version of protocol.
 - Examples:
@@ -332,35 +332,35 @@ The following attributes are defined for the `endpoint` type:
   string or excluded from the serialization entirely.
 - Constraints:
   - OPTIONAL
-  - if present, MUST be a string
+  - If present, MUST be a string
 - Examples:
   - `queue1`
 
 ### `deprecated`
 
 - Type: Object containing the following properties:
-  - effective<br>
+  - `effective`<br>
     An OPTIONAL property indicating the time when the Endpoint entered, or will
     enter, a deprecated state. The date MAY be in the past or future. If this
     property is not present the Endpoint is already in a deprecated state.
     If present, this MUST be an [RFC3339][rfc3339] timestamp.
 
-  - removal<br>
+  - `removal`<br>
     An OPTIONAL property indicating the time when the Endpoint MAY be removed.
     The Endpoint MUST NOT be removed before this time. If this property is not
     present then client can not make any assumption as to when the Endpoint
     might be removed. Note: as with most properties, this property is mutable.
     If present, this MUST be an [RFC3339][rfc3339] timestamp and MUST NOT be
     sooner than the `effective` time if present.
 
-  - alternative<br>
+  - `alternative`<br>
     An OPTIONAL property specifying the URL to an alternative Endpoint the
     client can consider as a replacement for this Endpoint. There is no
     guarantee that the referenced Endpoint is an exact replacement, rather the
     client is expected to investigate the Endpoint to determine if it is
     appropriate.
 
-  - docs<br>
+  - `docs`<br>
     An OPTIONAL property specifying the URL to additional information about
     the deprecation of the Endpoint. This specification does not mandate any
     particular format or information, however some possibilities include:
@@ -417,7 +417,7 @@ The following attributes are defined for the `endpoint` type:
   - "MQTT/3.1.1", "MQTT/5.0" - Use the MQTT [3.1.1][MQTT 3.1.1] or [5.0][MQTT
     5.0] protocol. The shorthand "MQTT" maps to "MQTT/5.0".
   - "NATS/1.0.0" - Use the [NATS][NATS] protocol. MAY be shortened to "NATS",
-  - which assumes usage of the latest NATS clients.
+  - Which assumes usage of the latest NATS clients.
   - "KAFKA/3.5" - Use the [Apache Kafka][Apache Kafka] protocol. MAY be
     shortened to "KAFKA", which assumes usage of the latest Apache Kafka
     clients.

endpoint/spec.md

@@ -199,8 +199,8 @@ addition to the basic [attributes](../core/spec.md#attributes-and-extensions):
   own. All definitions inside a group MUST use this same format.
 - Constraints:
   - At least one of `metadata` and `binding` MUST be specified.
-  - if present, MUST be a non-empty string
-  - if present, MUST follow the naming convention `{NAME}/{VERSION}`, whereby `{NAME}` is
+  - If present, MUST be a non-empty string
+  - If present, MUST follow the naming convention `{NAME}/{VERSION}`, whereby `{NAME}` is
     the name of the metadata format and `{VERSION}` is the version of the
     metadata format.
 - Examples:
@@ -217,8 +217,8 @@ addition to the basic [attributes](../core/spec.md#attributes-and-extensions):
   this same binding.
 - Constraints:
   - At least one of `metadata` and `binding` MUST be specified.
-  - if present, MUST be a non-empty string
-  - if present, MUST follow the naming convention `{NAME}/{VERSION}`, whereby `{NAME}` is
+  - If present, MUST be a non-empty string
+  - If present, MUST follow the naming convention `{NAME}/{VERSION}`, whereby `{NAME}` is
     the name of the protocol and `{VERSION}` is the version of protocol.
 - Examples:
   - `MQTT/3.1.1`

message/spec.md

@@ -155,22 +155,22 @@ http://example.com/people?limit=100
 Each successful response from the server will adhere to the following:
 - MUST respond with an HTTP 200
 - MUST include zero or more records
-- if the response refers to the start of the set of records, then the `prev`
+- If the response refers to the start of the set of records, then the `prev`
   Link MUST NOT be included in the response
-- if the response does not include the start of the set of records, then the
+- If the response does not include the start of the set of records, then the
   `prev` Link MAY be included in the response
-- the response MAY include the `first` Link in any response
-- if  `limit` attribute was specified as part of the flow, the response MUST
+- The response MAY include the `first` Link in any response
+- If  `limit` attribute was specified as part of the flow, the response MUST
   NOT include more records than what the `limit` attribute has indicated
-- if the response refers to the end of the set of records, then the `next`
+- If the response refers to the end of the set of records, then the `next`
   Link MUST NOT be included in the response
-- if the response does not refer to the end of the set of records, then the
+- If the response does not refer to the end of the set of records, then the
   `next` Link MUST be included in the response
-- the response MAY include the `last` Link in any response
-- the response MAY include the `expires` attribute in any response as an
+- The response MAY include the `last` Link in any response
+- The response MAY include the `expires` attribute in any response as an
   HTTP "Expires" header. If present, it MUST adhere to the format specified in
   [RFC 3339](https://tools.ietf.org/html/rfc7234#section-5.3)
-- it is STRONG RECOMMENDED that all responses include the `count` attribute
+- It is STRONG RECOMMENDED that all responses include the `count` attribute
 
 Additionally, Links MUST appear in the HTTP response as HTTP headers using
 the format described in RFC5988.

pagination/spec.md

@@ -244,8 +244,8 @@ algorithm for generating new `id` values and for determining which is the
 latest Version. See [Version IDs](../core/spec.md#version-ids) for more
 information, but in summary it means:
 - `id`s are unsigned integers starting with `1`
-- they monotomically increase by `1` with each new Version
-- the latest is the Version with the lexically largest `id` value after all
+- They monotomically increase by `1` with each new Version
+- The latest is the Version with the lexically largest `id` value after all
   Version's `id`s have been left-padded with spaces to the same length
 
 When semantic versioning is used in a solution, it is RECOMMENDED to include a

schema/spec.md

@@ -5,6 +5,7 @@
 import pytest
 from verify import (
     _BANNED_PHRASES_PATTERN,
+    _CAPITAL_DASH_PATTERN,
     _FAKE_DOCS_DIR,
     _MARKDOWN_BOOKMARK_PATTERN,
     _PHRASES_THAT_MUST_BE_CAPITALIZED_PATTERN,
@@ -36,6 +37,7 @@ def test_text_issues():
                 ShOULD        nOt
                 mAy
                 Optionally
+                - each
                 "required"
                 """
         )
@@ -47,6 +49,7 @@ def test_text_issues():
         "line 11: 'must' MUST be capitalized ('MUST')",
         "line 14: 'ShOULD        nOt' MUST be capitalized ('SHOULD        NOT')",
         "line 15: 'mAy' MUST be capitalized ('MAY')",
+        "line 17: '- e' should start with a capital letter after the dash",
     }
 
 

tools/test_verify.py

@@ -61,6 +61,7 @@ class Settings:
 )
 _BANNED_PHRASES_PATTERN = re.compile(r"Cloud\s+Events?", flags=re.IGNORECASE)
 _LANGUAGES_DIR_PATTERN = re.compile(f"[/^]{_LANGUAGES_DIR_NAME}[/$]")
+_CAPITAL_DASH_PATTERN = re.compile(r"(^\s*)(-\s*[a-z])", flags=re.MULTILINE)
 
 
 def _is_text_all_uppercase(text: str) -> bool:
@@ -71,6 +72,10 @@ def _banned_phrase_issues(text: str) -> Iterable[Issue]:
     for match in _BANNED_PHRASES_PATTERN.finditer(text):
         yield _pattern_issue(match, text, f"{repr(match.group(0))} is banned")
 
+def _capital_dash_issues(text: str) -> Iterable[Issue]:
+    for match in _CAPITAL_DASH_PATTERN.finditer(text):
+        yield _pattern_issue(match, text, f"{repr(match.group(2))} should start with a capital letter after the dash")
+
 
 def _miscased_phrase_issues(text: str) -> Iterable[Issue]:
     for match in _PHRASES_THAT_MUST_BE_CAPITALIZED_PATTERN.finditer(text):
@@ -90,6 +95,7 @@ def _should_skip_plain_text_issues(text: str) -> bool:
 def _plain_text_issues(text: str) -> Iterable[Issue]:
     if not _should_skip_plain_text_issues(text):
         yield from _banned_phrase_issues(text)
+        yield from _capital_dash_issues(text)
         yield from _miscased_phrase_issues(text)