DRAFT: Segregate SHOULD from MUST guidelines

[kiriakos]

This commit illustrates the restructuring some API guidelines to give SHOULD guidelines, previously embedded in MUST guidelines, their own space.

• Extracted SHOULD recommendations from MUST requirements
• Creating 6 new standalone SHOULD rule files with proper IDs
• Updating 3 MUST rule files to reference the new SHOULD rules
• Adding cross-references in both directions for discoverability

The changes maintain existing documentation structure while ensuring:

• MUST requirements are pure and unambiguous
• SHOULD recommendations are properly separated
• All rules maintain proper cross-references

This is a work-in-progress proposal for discussion and review.

Changelog:

New

• SHOULD use plural form for data topic names R200020
• SHOULD treat link relation URIs as immutable R100042
• SHOULD provide documentation for resolvable link relation URIs R100043
• SHOULD treat profile URIs as immutable R100073
• SHOULD provide documentation for resolvable profiles R100075
• SHOULD use same namespace for profile URIs R100076

Update

• Refactored rule "MUST follow kafka topic naming convention R200006" to extract SHOULD recommendations into separate rules.
• Refactored rule "MUST use absolute URIs for custom link relation types R100037" to extract SHOULD recommendations into separate rules.
• Refactored rule "MUST use absolute URIs for profiles R100066" to extract SHOULD recommendations into separate rules.

[kiriakos]

Some related art dealing with 2119 keywords in guideline corpora:

• Google AIPs eg: https://google.aip.dev/122 do not seem to handle in discreet Rules (with ids) as the otto api guidelines do, but they clearly separate MUST and SHOULD clauses visually (color) and structurally (list items)
• The OpenAPI Spec https://spec.openapis.org/oas/latest.html implements 2119 and uses MUST and SHOULD for guidance and the lowercase for prose. Does mention the different requirement levels in a single breath on one occasion but seems to keep usage of the keywords low and distinct for the rest of the spec. Is a protocol spec though, not a guideline corpus.
• UK OpenBanking does not segregate. Significantly sqewed towards MUST
• Azure Data Plane API Guidelines and Graph Api Guidelines are a mess and invent their own, emoji driven, terminology. They do have distinct items for each requirement. They do mix May and Should guidance occasionally but otherwise the requirement levels seem to be segregated. We definitely SHOULD NOT copy the emoji part.