Section 6. Links is not clear and unorganized on several points:
Link relation type is strongly connected with media types as constraints, but these mime types have additional constraints to these, which results in scattered descriptions and writings of specification.
Constraint for service-doc link relation type is written as
human readable documentation, supported formats are Unicode Text, markdown, HTML and PDF.
but wording Unicode is not clear. Considering restrictions placed at mime types, it should be clearly stated with UTF-8 is mandatory over all applicable types.
hreflang is marked as optional, but should be mandatory for text/plain, text/markdown, and possibly on text/html.
We would propose to rewrite this section into one table for clarification and ease for noticing all of constraints with reorganizing all of attached text for description totally, something like:
Relation-Type
Supported Media Types
Constraints
Remarks
icon
image/png, image/jpeg
service-doc
text/plain, text/html, text/markdown, text/pdf
Linked files MUST use the UTF-8 character encoding. hreflang is mandatory for text/plain and text/markdown
Section 6. Links is not clear and unorganized on several points:
service-doclink relation type is written asbut wording
Unicodeis not clear. Considering restrictions placed at mime types, it should be clearly stated with UTF-8 is mandatory over all applicable types.text/plain,text/markdown, and possibly ontext/html.We would propose to rewrite this section into one table for clarification and ease for noticing all of constraints with reorganizing all of attached text for description totally, something like:
iconimage/png,image/jpegservice-doctext/plain,text/html,text/markdown,text/pdfhreflangis mandatory fortext/plainandtext/markdown