diff --git a/sections/designRules.md b/sections/designRules.md index 3cf9fe3d..916c4a04 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -214,6 +214,88 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f +
+

Use standard language codes and field names for language content

+
+
Statement
+
+

A resource containing language content MUST follow BCP 47 [[RFC4647]] [[RFC5646]]. + All fields in requests and responses containing monolingual content MUST be an object with two fields (JSON) or tag with two subtags (XML). In it, "taal" (Dutch) or "language" (English) contains a value conforming [[RFC5646]] and "waarde" (Dutch) or "value" (English) contains the lingual content. +

Use the language subtag registry maintained by IANA for possible language subtags. +

+ +

All fields in requests and responses containing multilingual content MUST be an array of objects (JSON) or multiple children tags (XML). All elements either have a field "taal" (Dutch) or all have a field "language" (English) with a value conforming [[RFC5646]] and all have a field "waarde" (Dutch) or have a field "value" (English) with the lingual content. +

+ +

[[?ISO3166-1]] concerns identifiers of countries and MUST NOT be used to denote languages, since countries and languages are not equivalent. +

Following [[RFC4647]] a language code in [[?ISO-639-1]] format matches a language tag in [[RFC5646]] regardless of language subtag. +

+
Rationale
+
+ Standardized language codes removes ambiguity in language handling between systems, potentially present in separate regions with different (spoken) languages. +
+
How to test
+
+
    +
  • Analyse all fields and if the field represents a language and ensure either one of the following options applies: +
      +
    • In case of monolingual content, ensure it is an object (JSON) or tag (XML). It has two fields "taal" and "waarde" or it has two fields "language" and "value". +
    • In case of multilingual content, ensure it is an array consisting of objects (JSON) or multiple children tags (XML). Either all objects/children have two fields "taal" and "waarde" or all objects/children have two fields "language" and "value". +
    +
  • Confirm each field "taal" or "language" has a value in [[RFC5646]] format. +
+
+
+
+ ## Date and time Handling date and time is tricky and can lead to confusion among clients. The date-time rules remove ambiguity and provide clarity in the API contract between servers and clients.