[Enhancement]: Introduce Entity.Fields sub-property

[JerryNixon]

What is it?

• Introduce a fields property under an entity.

This gives us:

1. a unified field description (in OpenAPI & GQL Schema)
2. a toggle to include fields (in read operations)
3. a net-new place for additional metadata
4. a net-new place for metadata/input-validation (in mutation ops)

{
  "entities": [
    {
      "<entity-name>": {
        ...
        "fields": [
          {
            "<field-name>": {
              "metadata": {
                  "key": <true> | <false> (default) // supersedes entity/key-fields
                  "alias": <alias-name> (optional) // supersedes entity/mapping
                  "description": <string> (optional)
                  "read-include": <true> (default) | <false> // supersedes entity/key-fields
              },
              "input-validation": {
                "range":  {
                    "min": <integer/inclusive>
                    "max": <integer/inclusive> 
                } (optional) 
                "regex-pattern": <string/.NET syntax> (optional)
                "script": <string/TBD> (optional)
                "required": <true> | <false>  (default)
                "error-message": <string> (optional)
              } (optional)
...

List new properties

1. fields/ (array)
   Defines a list of fields within an entity.
2. fields/field-name (string)
   The name of a specific field within an entity.
3. field-name/metadata (object)
   Contains metadata information for a field.
4. metadata/key (boolean)
   Indicates if the field is a primary key.
5. metadata/alias (string)
   An optional alias for the field.
6. metadata/description (string)
   An optional description of the field.
7. metadata/read-include (boolean)
   Determines if the field is included in read operations.
8. field-name/input-validation (object)
   Validates the value of fields when submitted to an endpoint for mutations like insert or update.
9. input-validation/range (object)
   Defines inclusive minimum and maximum values for the field.
10. range/min (integer)
    Minimum inclusive value for the field.
11. range/max (integer)
    Maximum inclusive value for the field.
12. input-validation/regex-pattern (string)
    A "must match" pattern using .NET regular expression syntax.
13. input-validation/script (string)
    A TBD feature for custom validation logic, requires further discussion.
14. input-validation/required (boolean)
    Optional indicator that null/empty are invalid. Allows for field to be omitted during insert & update when false.
15. input-validation/error-message (string)
    Optional custom error message for validation failure.

Explain metadata

Allows the developer to include field-specific description. And more in the future.

Where does description show up?

1. OpenAPI (descriptions associated with fields)
2. GraphQL Schema (descriptions associated with fields)

Explain validation

Validation is input validation intended to validate values for inserts & updates.

Questions

1. If a field is not included in the fields array, is it returned in the GET operation? (see read-include) Needs discussion.
2. If more than one type of input-validation is included, does that mean we run them all?
3. How are we going to support script?

• Roslyn Scripting: https://github.com/dotnet/roslyn/blob/main/docs/wiki/Scripting-API-Samples.md
• POC: https://github.com/JerryNixon/embedded-csharp

Related items that will be closed

• [Improvement]: Mappings are ignored when using stored procedures #1773
• Add entity field/parameter mapping support for Stored Procedures #661
• [Enhancement] Add support for mappings feature for Cosmos DB #1512
• Excluding columns from entities by default (without permissions) #1376
• [Bug]: Cannot start DAB when a table has a non-supported data type, even if the column has been added to the exclude list #1503