Document Requirements for Valid Keys and Namespaces

[VJag]

Describe the bug

Description:
As of today, the information regarding:

1. What constitutes a valid key.
2. What constitutes a valid namespace.
   ...is documented directly in the code. However, this needs to be clearly documented in a standalone document, making it accessible to all developers and stakeholders without requiring code inspection.

Steps to reproduce

NA

Expected behavior

• The requirements for valid keys and namespaces are well-documented in a clear, structured, and easily accessible format.

This documentation should include:

• Definitions and rules for valid keys and namespaces.
• Examples illustrating valid and invalid cases.
• References to related code sections, if applicable.

Screenshots

No response

Smartphones

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Were you using an atApplication when the bug was found?

No response

Additional context

No response

[VJag]

Regexes class in at_commons contains regexes used in validating the keys (As in key-value pair).

Following are the constants used:

static const charsInNamespace = r'([\w])+';
static const charsInAtSign = r'[\w-]';
static const charsInEntity = r'''[\w.-'*"]''';
static const allowedEmoji =
r'''((\u00a9|\u00ae|[\u2000-\u3300]|[\ufe00-\ufe0f]|\ud83c[\ud000-\udfff]|\ud83d[\ud000-\udfff]|\ud83e[\ud000-\udfff]))''';

Validation Rules for Regular Expressions

1. charsInNamespace = r'([\w])+'

• Explanation:
  • [\w]: Matches any word character (equivalent to [a-zA-Z0-9_]).
  • +: Matches one or more occurrences of the preceding pattern.
• Purpose:
  Validates that a namespace contains only word characters (letters, digits, or underscores) and has at least one character.
• Examples:
  • Valid: namespace1, valid_namespace, _hidden
  • Invalid: namespace!, namespace space, !@#$

---

2. charsInAtSign = r'[\w\-_]'

• Explanation:
  • [\w]: Matches word characters ([a-zA-Z0-9_]).
  • \-: Matches the literal hyphen -.
  • _: Matches the underscore _.
• Purpose:
  Validates that characters in an "at-sign" context (e.g., @something) can be word characters, hyphens (-), or underscores (_).
• Examples:
  • Valid: @user_name, @user-name, @username123
  • Invalid: @user!name, @user name, @user#

---

3. charsInEntity = r'''[\w\.\-_'*""]'''

• Explanation:

  • [\w]: Matches word characters.
  • \.: Matches the literal dot ..
  • \-: Matches the literal hyphen -.
  • _: Matches the underscore _.
  • ': Matches the single quote '.
  • *: Matches the asterisk *.
  • ": Matches the double quote ".

• Purpose:
  Validates that an entity can contain word characters, dots (.), hyphens (-), underscores (_), single quotes ('), double quotes ("), or asterisks (*).

• Examples:

  • Valid: entity.name, entity-name, entity_name, 'entity', "entity", entity*
  • Invalid: entity space, entity!name, entity@#

---

4. allowedEmoji = r'''((\u00a9|\u00ae|[\u2000-\u3300]|[\ufe00-\ufe0f]|\ud83c[\ud000-\udfff]|\ud83d[\ud000-\udfff]|\ud83e[\ud000-\udfff]))'''

• Explanation:

  • \u00a9: Matches the © copyright symbol.
  • \u00ae: Matches the ® registered trademark symbol.
  • [\u2000-\u3300]: Matches Unicode characters in the specified range (various symbols and punctuation).
  • [\ufe00-\ufe0f]: TO DO.
  • \ud83c[\ud000-\udfff]: TO DO.
  • \ud83d[\ud000-\udfff]: TO DO.
  • \ud83e[\ud000-\udfff]: TO DO.

• Purpose:
  Validates whether a string contains a valid emoji or symbol. This regex checks for Unicode values of emojis and some special symbols.

• Examples:

  • Valid: 😊, 👍, 🤖, 🏠, ©, ®
  • Invalid: text, !@#$

---

Summary Table

Regex	Purpose
charsInNamespace	Validates that a namespace consists of word characters only (letters, digits, underscores).
charsInAtSign	Validates characters allowed after an "at sign" (@): word characters, hyphens, and underscores.
charsInEntity	Validates entities containing word characters, dots, hyphens, underscores, quotes, or asterisks.
allowedEmoji	Validates Unicode emojis and some special symbols like © and ®.

[VJag]

The link shared here contains documentation for the limitations for what is allowed for the key in Hive DB: https://hivedb.dev/#/more/limitations?id=limitations

[VJag]

Due to this piece of code in server, we are able to accept non-ascii chars and make them compatible with Hive :

String prepareKey(String key) {
key = key.trim().toLowerCase().replaceAll(' ', '');
return Utf7.encode(key);
}